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

modeHowCost and latency
template (default)A JSON template with variables — the state, the answers, weighted levels, composites and params.Free, instant: no model call.
extractAn 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"]
}
KeywordUse
typestring, number, integer, boolean, object or array — or ["string", "null"] to accept null. The root is always an object.
properties, requiredThe fields of an object, and which ones must be present. Every object declares its fields.
itemsWhat a list holds (required on array).
enumAllowed values of a text or number field (up to 50).
descriptionWhat a field means — the model reads it in extract mode.
minimum, maximum, minLength, maxLength, minItems, maxItemsBounds 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
}
FieldDefaultDescription
provideropenrouteropenrouter 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.
inputthe whole stateThe user message: up to 8,000 characters.
temperature00 to 2.
maxTokens102416 to 4,096.
timeoutMs200001,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:

Caseoutput
A json destination completedIts object — the first one, in schema order, when several fired.
json destinations fired, none completednull
No json destination firedabsent

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:

ComponentsUse
Card, Stack, Grid, SeparatorLayout.
Heading, Text, Badge, AlertText and status.
Table, Image, Avatar, ProgressData and media.
Button, LinkActions (on.press).
ActionParamsMeaning
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:

  1. json-render's autoFixSpec fixes common model mistakes (a visible inside props, a child that doesn't exist).
  2. The structure must hold: a root that exists, children that exist, known component types.
  3. Props are checked per component with its schema — unknown props are refused.
  4. Actions: only reply and open_url, on an event the component has (press), with valid params.
  5. URLs — Link.href, Image.src, Avatar.src, open_url — must be https:// (no javascript: links, no tracking over plain http).
  6. Final values only: no repeat, visibility conditions or $state expressions; className is always null. 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 zod
import { 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, template destinations always run (they're free); extract destinations 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 output when the decision stores outputs (storeOutput); with storeOutput: false it keeps only whether the output was built.
  • The SDKs expose it as decision.output — in TypeScript, typed with dcision.decide<Result, Output>(…).

On this page