🔗 Data and bindings

A widget layout is not static: text, images and buttons are bound to data. The schema defines the shape of that data; the agent or your API supplies the values.

📐 The schema

The schema is a JSON Schema contract. It drives three things:

• which fields the agent fills for a Show widget function;
• which paths are suggested while you write code;
• validation of the payload (required keys, types, enum).

{
  "type": "object",
  "properties": {
    "customer": { "type": "string" },
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title":  { "type": "string" },
          "total":  { "type": "number" },
          "status": { "type": "string", "enum": ["new", "shipping", "done"] }
        }
      }
    }
  },
  "required": ["orders"]
}

🧷 Binding syntax

In JSX a binding is a plain expression; in the stored tree it is a path inside double curly braces:

• value={customer} → "{{customer}}"
• value={order.total} → "{{order.total}}" — dot paths.
• label={orders[0].status} — index access.
• value={orders.length} — array length.

A prop that is exactly one binding keeps the bound value's type (an array stays an array). Mixed with text, the result becomes a string:

<Title value={order.title} />        → "{{order.title}}"
<Text value={"$" + order.total} />    → "${{order.total}}"

🔁 Looping over arrays

Lists are written with .map() and compile to a Repeat node:

<Card gap={2}>
  {orders.map(order => (
    <Row align="center" gap={2}>
      <Text value={order.title} />
      <Spacer />
      <Badge label={order.status} />
    </Row>
  ))}
</Card>

• The item is bound under the name you chose — order.
• Its position is available as orderIndex (item name + Index).
• Use <>…</> to return several nodes per item.

🧮 Where data comes from

API response  >  function (action) data  >  Default example  >  empty values from the schema

• With Show widget, the agent fills the data following the schema.
• With Call API + show widget, data comes from the endpoint response and can be reshaped through response mapping.
• Form fields (Input, Select …) write into that same data under their name key.
• A set_variables function also updates it, in the browser only.

⚠️ Good to know

• A missing path renders empty — it never breaks the widget.
• Default never overrides live data; it exists for the editor.
• What a visitor types stays in the browser. To send it to your server, list the field in the function's additional inputs.