Field references

When the state is JSON, instructions and criteria can point at a field with {{path}}. The model reads that field where it sits in the state, and you do not pay for it twice.

Syntax#

A path is a dot-separated chain of keys, with array indexes in square brackets:

Array indexes start at 0.

Keys with other characters#

Keys made of letters, digits, underscores and hyphens can be written as they are. A key with any other character, such as a space or a dot, goes in square brackets with double quotes:

{{customer["full name"]}}

Pointer semantics#

Dex does not paste the field's value into the question. The rendered question names the path, and the rendered state shows every field with its path, so the model reads the field in place.

Two things follow:

• You are not billed twice. The field's value counts once, in state_tokens. The reference itself adds only the few question tokens of the path.
• Many questions can point at one field. Three questions that each reference {{ticket.body}} still pay for the body once.

Validation#

Every referenced path must exist in the state. The check runs before anything is charged.

A missing path error names the question field that holds the reference in param, and the path in message:

{
  "error": {
    "type": "validation",
    "code": "state_path_not_found",
    "message": "Question 'spoed' refers to {{bericht.txt}}, which is not in the state.",
    "param": "questions.spoed.instructions",
    "request_id": "req_01M5CJXHG0M9S346Q3D25VT4F5"
  }
}

Literal braces#

• {{ without a matching }} is literal text.
• \{{ escapes a literal {{ that would otherwise start a reference.

In a JSON string the backslash itself must be escaped, so the text \{{ is written "\\{{" in the request body:

{ "instructions": "Does {{post.text}} contain template syntax such as \\{{name}}?" }

SDK helpers#

Until the SDKs are on PyPI and npm, install them from Downloads.

ref builds a reference from path parts and adds brackets and quotes where a key needs them. escape_braces (Python) and escapeBraces (TypeScript) turn every {{ in a text into \{{.

from thinqit_dex import ref, escape_braces

ref("ticket", "messages", 0, "text")  # "{{ticket.messages[0].text}}"
ref("customer", "full name")          # '{{customer["full name"]}}'
escape_braces("a {{b}}")               # "a \\{{b}}"

import { ref, escapeBraces } from "@thinqit/dex";

ref("ticket", "messages", 0, "text"); // "{{ticket.messages[0].text}}"
ref("customer", "full name");         // '{{customer["full name"]}}'
escapeBraces("a {{b}}");              // "a \\{{b}}"