Skip to documentation

Reference · Template language

Available

Render typed values from the request and state

DotMock uses canonical Handlebars-style helpers in response templates and one bounded expression language for conditions. Exact helper expressions preserve JSON types; embedded expressions always stringify.

In this guide

  • Use canonical helper syntax
  • Read the correct protocol scope
  • Preserve typed JSON output
  • Select missing-state and conditional outcomes safely

Prerequisites

  • A DotMock workspace you can access
  • The API ID in $API_ID and its published runtime URL in $MOCK_URL when the example calls the mock
On this page
  1. Exact and embedded expressions behave differently
  2. REST request helpers
  3. GraphQL request helpers
  4. gRPC request helpers
  5. SOAP request helpers
  6. Conditions use one visible expression language
  7. Read state with dynamic keys and fallbacks
  8. Use atomic mutation helpers
  9. Know the runtime boundary

Exact and embedded expressions behave differently

If a JSON string contains exactly one helper, the result keeps its native object, array, number, boolean, or null type. Text before or after a helper makes the final value a string.

Typed number
{ "quantity": "{{randomInt 1 10}}" }

Embedded string
{ "orderId": "order-{{uuid}}" }

Typed object
{{state.get "users-by-id" "$param.userId" "" null}}

REST request helpers

Use focused helpers for path parameters, query values, lowercase request headers, and JSON body paths. request accepts only method or path.

handlebars
{{param "userId"}}
{{query "page"}}
{{header "x-plan"}}
{{body "customer.email"}}
{{request "method"}}

GraphQL request helpers

GraphQL templates can read resolved variables, root-field arguments, operation metadata, headers, and the HTTP envelope.

handlebars
{{variable "input.customerId"}}
{{argument "id"}}
{{operation "name"}}
{{operation "type"}}
{{operation "field"}}

gRPC request helpers

gRPC templates read the current request message, ordered client-stream messages, incoming metadata, and method context. ProtoJSON output is validated against the compiled response descriptor.

handlebars
{{message "userId"}}
{{messages "1.userId"}}
{{metadata "x-tenant-id"}}
{{grpc "method"}}

SOAP request helpers

SOAP templates read the complete XML envelope with XPath and expose the selected action, operation, version, headers, and normalized body.

handlebars
{{xpath "//*[local-name()='customerId']"}}
{{soap "action"}}
{{soap "operation"}}
{{soap "version"}}

Conditions use one visible expression language

Conditions combine request values, time, and state. Use bracket access for dynamic keys and lowercase header names. Numeric query values need an explicit conversion.

expression
method == "POST" && path == "/orders"
query["preview"] == "true" && header["x-plan"] == "pro"
body.total >= 100
int(query["amount"]) >= 100
!state.exists("users-by-id", params["userId"])
!state.exists("users-by-id", message["userId"])

Read state with dynamic keys and fallbacks

state.get accepts resource, key, optional nested path, and optional typed fallback. Dynamic key prefixes resolve from the current request.

handlebars
{{state.get "users-by-id" "$param.userId"}}
{{state.get "users-by-id" "$param.userId" "profile.name" null}}
{{state.get "users-by-id" "$variable.userId" "" null}}
{{state.get "sessions" "$header.x-session-id"}}

Use atomic mutation helpers

Visual before actions and inline helpers use the same transaction. state.create uses the complete request object. Other helpers accept a resource, dynamic key, and operation-specific values.

handlebars
{{state.create "users-by-id"}}
{{state.merge "users-by-id" "$param.userId"}}
{{state.increment "request-count" "$header.x-customer-id" 1}}
{{queue.push "jobs" "$body.customerId" "send-email"}}
{{queue.pop "jobs" "$body.customerId"}}
{{stack.push "undo" "$param.userId" "profile-change"}}
{{set.add "seen-products" "$body.customerId" "sku_123"}}

Know the runtime boundary

REST, GraphQL, SOAP, gRPC, LLM fixtures, and webhooks have connected protocol-aware template scopes. SOAP XML helpers stringify embedded values while JSON and ProtoJSON exact expressions preserve typed values.