Structured output
Return a JSON object your system can use as is, or a screen your app renders — built from the result (no model) or by an LLM, always checked before it leaves Dcision.
A decision answers questions: result, confidence and the action. A structured output destination (json) also hands back an object ready for your system — the ticket to open, the order to update, the lead to create — and checks it against the fields you define before it leaves Dcision.
It comes back in the response's top-level output:
{
"result": { "route": "support", "priority": "high" },
"action": "continue",
"output": { "awb": "1Z999AA10123456784", "team": "support", "priority": 3, "summary": "Package is 3 days late" },
"destinations": [
{ "key": "ticket", "type": "json", "mode": "template", "status": "completed", "output": { "awb": "1Z999AA10123456784", "team": "support", "priority": 3, "summary": "Package is 3 days late" } }
]
}Two ways to fill it
mode | How | Cost and latency |
|---|---|---|
template (default) | A JSON template with variables — the state, the answers, weighted levels, composites and params. | Free, instant: no model call. |
extract | An LLM reads the state and fills the fields, on your OpenRouter or Vercel AI Gateway key — like LLM answers. | The provider's tokens; the caller waits (it counts as one of the 3 calls that make the caller wait). |
Use template when the values already exist — in the state or in the answers. Use extract when they are buried in text: an order number in an e-mail, a name in a chat message.
The fields
The schema is a JSON Schema object, the same format LLM providers use for structured outputs:
{
"type": "object",
"properties": {
"awb": { "type": "string", "description": "The tracking number" },
"team": { "type": "string", "enum": ["sales", "support", "billing"] },
"priority": { "type": "integer", "minimum": 1, "maximum": 4 },
"items": { "type": "array", "items": { "type": "string" }, "maxItems": 10 },
"note": { "type": ["string", "null"] }
},
"required": ["awb", "team"]
}| Keyword | Use |
|---|---|
type | string, number, integer, boolean, object or array — or ["string", "null"] to accept null. The root is always an object. |
properties, required | The fields of an object, and which ones must be present. Every object declares its fields. |
items | What a list holds (required on array). |
enum | Allowed values of a text or number field (up to 50). |
description | What a field means — the model reads it in extract mode. |
minimum, maximum, minLength, maxLength, minItems, maxItems | Bounds of numbers, texts and lists. |
Fields that aren't in the schema are not accepted. Limits: up to 3 levels of nested objects, 50 fields in total and 8 KB of schema; the output itself is up to 16 KB. In the editor, Output fields builds the schema row by row; the JSON Schema tab shows it as JSON, and you can paste one there.
Template mode
The template is JSON with variables, encoded like the body of an API request: outside quotes a variable becomes a JSON value, inside quotes it becomes text.
{
"key": "ticket",
"type": "json",
"when": { "conditions": [{ "field": "route", "on": "output", "operator": "eq", "value": "support" }] },
"params": { "awb": { "from": "state.awb", "required": true } },
"json": {
"mode": "template",
"schema": { "type": "object", "properties": { "awb": { "type": "string" }, "team": { "type": "string" }, "priority": { "type": "number" }, "summary": { "type": "string" } }, "required": ["awb", "team"] },
"template": "{\"awb\": {{params.awb}}, \"team\": {{result.route}}, \"priority\": {{scores.priority}}, \"summary\": \"Customer said: {{state.message}}\"}"
}
}- Text from the state can't break the JSON: quotes and line breaks are escaped wherever the variable is.
- Secrets can't be used — the output goes back to the caller.
{{secrets.NAME}}is refused when you save. - When you save, the template must be valid JSON with sample values and have the required fields. Fill from fields in the editor writes a starting template: a field named like a state field, a question, a composite or a param reads it.
Extract mode
"json": {
"mode": "extract",
"schema": { "type": "object", "properties": { "order_id": { "type": "string" }, "customer": { "type": "string" }, "request": { "type": "string", "enum": ["refund", "exchange", "tracking"] } }, "required": ["order_id", "request"] },
"provider": "openrouter",
"model": "openai/gpt-5-mini",
"instructions": "Extract the order this customer is writing about.",
"input": "{{state.message}}",
"temperature": 0,
"maxTokens": 1024,
"timeoutMs": 20000
}| Field | Default | Description |
|---|---|---|
provider | openrouter | openrouter or vercel — the key saved in Settings → Engine. |
model | — | The provider's model ID. Pick one that supports structured outputs (JSON Schema). |
instructions | — | What to extract (system message): up to 8,000 characters. Variables allowed, no secrets. |
input | the whole state | The user message: up to 8,000 characters. |
temperature | 0 | 0 to 2. |
maxTokens | 1024 | 16 to 4,096. |
timeoutMs | 20000 | 1,000 to 25,000, retries included. |
Dcision sends the schema in the provider's strict structured-output mode (response_format: json_schema). Strict mode needs every field, so optional fields go as nullable and the nulls the model writes for them are removed before validation. If the answer still doesn't fit — invalid JSON, a value outside enum, a missing field — Dcision sends it back once with the problems, within the same timeoutMs.
When it fails
A structured output never fails the decision. The entry comes back with "status": "failed", an error and, when the object didn't match, the issues:
{
"key": "ticket",
"type": "json",
"mode": "template",
"status": "failed",
"error": "The output doesn't match the schema.",
"issues": [{ "path": "/awb", "message": "Must not be null." }]
}issues[].path is a JSON Pointer to the value (/items/2). The top-level output is:
| Case | output |
|---|---|
A json destination completed | Its object — the first one, in schema order, when several fired. |
json destinations fired, none completed | null |
No json destination fired | absent |
Screens (json-render)
With "format": "ui" the output is a screen instead of data: a json-render spec — cards, text, badges, tables, buttons — that your app renders natively. It answers the caller with an interface, not just a value: the order status with a Talk to support button, the lead's summary with a Book a demo link.
"json": {
"format": "ui",
"mode": "template",
"template": "{\"root\": \"card\", \"elements\": {\"card\": {\"type\": \"Card\", \"props\": {\"title\": \"Order {{state.awb}}\"}, \"children\": [\"status\", \"talk\"]}, \"status\": {\"type\": \"Badge\", \"props\": {\"text\": {{result.route}}}, \"children\": []}, \"talk\": {\"type\": \"Button\", \"props\": {\"label\": \"Talk to support\"}, \"children\": [], \"on\": {\"press\": {\"action\": \"reply\", \"params\": {\"text\": \"support\"}}}}}}"
}A screen is { "root", "elements" }: a flat map of elements, each with a type, props, children (element keys) and optional on (event → action). The output comes back complete — every prop of each component, null when unused.
The catalog
Screens use Dcision's catalog — an exact subset of json-render's shadcn components, with the same props:
| Components | Use |
|---|---|
Card, Stack, Grid, Separator | Layout. |
Heading, Text, Badge, Alert | Text and status. |
Table, Image, Avatar, Progress | Data and media. |
Button, Link | Actions (on.press). |
| Action | Params | Meaning |
|---|---|---|
reply | { "text": "…" } | Send the text back as the user's next message — a quick reply. |
open_url | { "url": "https://…" } | Open a URL. |
How Dcision checks a screen
Every screen — from a template or from an LLM — goes through json-render's own checks and Dcision's hardening:
- json-render's
autoFixSpecfixes common model mistakes (avisibleinsideprops, a child that doesn't exist). - The structure must hold: a root that exists, children that exist, known component types.
- Props are checked per component with its schema — unknown props are refused.
- Actions: only
replyandopen_url, on an event the component has (press), with valid params. - URLs —
Link.href,Image.src,Avatar.src,open_url— must behttps://(nojavascript:links, no tracking over plain http). - Final values only: no
repeat, visibility conditions or$stateexpressions;classNameis alwaysnull. At most 60 elements and 32 KB.
In extract mode the model gets json-render's catalog prompt plus your instructions; if its screen fails a check, Dcision sends the problems back once. Templates are checked when you save, with sample values.
Render it
npm install @json-render/core @json-render/react @json-render/shadcn zodimport { defineCatalog } from "@json-render/core";
import { JSONUIProvider, Renderer, defineRegistry } from "@json-render/react";
import { schema } from "@json-render/react/schema";
import { shadcnComponents } from "@json-render/shadcn";
import { shadcnComponentDefinitions as d } from "@json-render/shadcn/catalog";
import { z } from "zod";
const names = ["Card", "Stack", "Grid", "Separator", "Heading", "Text", "Badge", "Alert", "Table", "Image", "Avatar", "Progress", "Button", "Link"] as const;
const catalog = defineCatalog(schema, {
components: Object.fromEntries(names.map((name) => [name, d[name]])),
actions: {
reply: { params: z.object({ text: z.string() }), description: "Quick reply" },
open_url: { params: z.object({ url: z.string() }), description: "Open a URL" },
},
});
const { registry } = defineRegistry(catalog, {
components: Object.fromEntries(names.map((name) => [name, shadcnComponents[name]])),
actions: { reply: async () => {}, open_url: async () => {} },
});
export function DecisionScreen({ decision, send }) {
return (
<JSONUIProvider
registry={registry}
handlers={{
reply: async ({ text }) => send(text),
open_url: async ({ url }) => window.open(url, "_blank", "noopener"),
}}
>
<Renderer spec={decision.output} registry={registry} />
</JSONUIProvider>
);
}json-render also renders the same spec with React Native, React Email, React PDF and other targets — map the same component names there.
In the Playground and the logs
- In the Playground,
templatedestinations always run (they're free);extractdestinations show the prompt and the strict schema that would be sent ("status": "preview") unless you run destinations for real. Screens are rendered, and pressing a button shows the action it would send. - The execution log keeps the
outputwhen the decision stores outputs (storeOutput); withstoreOutput: falseit keeps only whether the output was built. - The SDKs expose it as
decision.output— in TypeScript, typed withdcision.decide<Result, Output>(…).