Building a schema

Open Decisions in the sidebar and choose New schema. The wizard asks for a platform (the provider the schema runs on by default), a kind, and then a name, a registry and a first version, and opens the editor on that draft. You fill in a form; you never have to write JSON, though the JSON tab always shows what the form produces.

The three kinds

The kind decides what the answer is. You can change it later, and the editor asks first when that would drop something that belongs to the old kind.

For a yes/no question a probability of at least the threshold counts as yes. The threshold is 0.5 unless you set another one.

Instructions and inputs

The instructions are the question the model answers. They are a template: write {{ticket}} where the value of an input called ticket should go. The editor completes input names as you type, warns about a name that is not declared as an input (with Add as input), about an input the instructions never use, and about empty instructions.

Each input has:

• a key, in camelCase (ticketBody) or snake_case (ticket_body), but not env, which is reserved;
• a type: text, number, yes/no or JSON;
• whether it is required: a call that leaves out a required input is refused with the names of the missing ones;
• an optional description.

Instructions can also use the environment's variables as {{env.variables.name}}. The variable is put in before the text goes to the provider, so one schema can read differently in dev and in prod.

Options

Each option has a label, an id and an optional description. The id follows the label until you edit it yourself, is lowercase letters, digits, - or _, and is unique in the schema. The id is what your code receives, so it is worth keeping stable. Drag options to reorder them.

A pick can allow several options at once. Neither provider can do that natively, so it is done as one yes/no question per option: each option gets its own probability, the probabilities do not add up to 1, and every option at or above the threshold is chosen.

Examples

Examples show the model what you mean. Each is a row of input values and the answer you expect, and the editor shows them as a grid with a column for each input.

• A new example has no answer until you pick one, and the schema is invalid until you do, so a quick click never sends an accidental answer as a worked case.
• Few-shot says whether an example is sent to the provider. Switch it off to keep an example for testing only, so you can see how the model does on cases it was never shown.
• Export writes the grid as CSV and Import reads one back. An import takes everything or nothing, and tells you the line and column of the first mistake.

The panel beside the form

• Compatibility lists each provider you have configured and whether it can run this schema, with the reason when it cannot: too many options, too many levels, or a kind it does not do. A provider that cannot run the schema is skipped for it, without a call.
• JSON is the schema as the gateway sees it, with a Copy button once it is valid.
• Playground runs it for real. See The playground.

Saving and publishing

The editor saves your draft by itself after a short pause, and Save Draft saves at once. Only a valid schema is stored: while the form shows errors, the last good draft stays and the header says so. Publish asks for a version and an optional message, which Suggest can write for you, and warns, without stopping you, when no platform is set or no provider you have configured can run the schema. Publishing makes the version read-only: to change it, choose Draft New Version. See Versions and references.

An example

This is the JSON of a pick with three options, as the JSON tab would show it.

{
  "kind": "choice",
  "name": "route-complaint",
  "description": "Pick the team that should handle a complaint.",
  "instructions": "Which department should handle this complaint?\n\nComplaint: {{ticket}}",
  "inputs": [
    {
      "key": "ticket",
      "type": "text",
      "required": true,
      "description": "The customer's message"
    }
  ],
  "options": [
    { "id": "billing", "label": "Billing", "description": "Payments and refunds" },
    { "id": "technical", "label": "Technical" },
    { "id": "other", "label": "Other" }
  ],
  "examples": [
    { "inputs": { "ticket": "I was charged twice for my order" }, "expected": "billing" }
  ]
}