Salida estructurada

Devuelve un objeto JSON que tu sistema puede usar tal cual, o una pantalla que tu app renderiza — construido a partir del resultado (sin modelo) o por un LLM, siempre validado antes de salir de Dcision.

Una decisión responde preguntas: result, confidence y la action. Un destino de salida estructurada (json) también te devuelve un objeto listo para tu sistema —el ticket que abrir, el pedido que actualizar, el lead que crear— y lo valida contra los campos que defines antes de que salga de Dcision.

Vuelve en el campo output de nivel superior de la respuesta:

{
  "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" } }
  ]
}

Dos formas de llenarla

modeCómoCosto y latencia
template (predeterminado)Una plantilla JSON con variables: el estado, las respuestas, los niveles ponderados, los compuestos y los params.Gratis, instantáneo: sin llamada a un modelo.
extractUn LLM lee el estado y llena los campos, con tu clave de OpenRouter o de Vercel AI Gateway —como las respuestas de LLM.Los tokens del proveedor; quien llama espera (cuenta como una de las 3 llamadas que hacen esperar a quien llama).

Usa template cuando los valores ya existen, en el estado o en las respuestas. Usa extract cuando están enterrados en un texto: un número de pedido en un e-mail, un nombre en un mensaje de chat.

Los campos

El schema es un objeto JSON Schema, el mismo formato que usan los proveedores de LLM para las salidas estructuradas:

{
  "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"]
}
Palabra claveUso
typestring, number, integer, boolean, object o array —o ["string", "null"] para aceptar null. La raíz siempre es un object.
properties, requiredLos campos de un objeto y cuáles deben estar presentes. Todo objeto declara sus campos.
itemsLo que contiene una lista (obligatorio en array).
enumValores permitidos de un campo de texto o numérico (hasta 50).
descriptionQué significa un campo: el modelo lo lee en el modo extract.
minimum, maximum, minLength, maxLength, minItems, maxItemsLímites de números, textos y listas.

Los campos que no están en el schema no se aceptan. Límites: hasta 3 niveles de objetos anidados, 50 campos en total y 8 KB de schema; la salida en sí admite hasta 16 KB. En el editor, Campos de la salida construye el schema fila por fila; la pestaña JSON Schema lo muestra como JSON, y puedes pegar uno allí.

Modo template

La plantilla es JSON con variables, codificado como el cuerpo de una solicitud de API: fuera de comillas, una variable se convierte en un valor JSON; dentro de comillas, se convierte en texto.

{
  "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}}\"}"
  }
}
  • El texto del estado no puede romper el JSON: las comillas y los saltos de línea se escapan dondequiera que esté la variable.
  • No se pueden usar secretos: la salida vuelve a quien llama. {{secrets.NAME}} se rechaza al guardar.
  • Al guardar, la plantilla debe ser JSON válido con valores de ejemplo y tener los campos obligatorios. Completar a partir de los campos, en el editor, escribe una plantilla inicial: un campo con el nombre de un campo del estado, una pregunta, un compuesto o un param lo lee.

Modo extract

"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
}
CampoPredeterminadoDescripción
provideropenrouteropenrouter o vercel: la clave guardada en Configuración → Motor.
model—El ID del modelo en el proveedor. Elige uno que admita salidas estructuradas (JSON Schema).
instructions—Qué extraer (mensaje de sistema): hasta 8,000 caracteres. Se permiten variables, no secretos.
inputtodo el estadoEl mensaje del usuario: hasta 8,000 caracteres.
temperature0De 0 a 2.
maxTokens1024De 16 a 4,096.
timeoutMs20000De 1,000 a 25,000, reintentos incluidos.

Dcision envía el schema en el modo estricto de salida estructurada del proveedor (response_format: json_schema). El modo estricto exige todos los campos, así que los campos opcionales se envían como anulables y los null que el modelo escribe para ellos se eliminan antes de la validación. Si la respuesta aun así no encaja —JSON inválido, un valor fuera de enum, un campo faltante—, Dcision la devuelve una vez con los problemas, dentro del mismo timeoutMs.

Cuando falla

Una salida estructurada nunca hace fallar la decisión. La entrada vuelve con "status": "failed", un error y, cuando el objeto no coincidió, los 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 es un JSON Pointer al valor (/items/2). El output de nivel superior es:

Casooutput
Un destino json se completóSu objeto: el primero, en el orden del schema, cuando se dispararon varios.
Se dispararon destinos json, ninguno se completónull
No se disparó ningún destino jsonausente

Pantallas (json-render)

Con "format": "ui", la salida es una pantalla en lugar de datos: una spec de json-render —tarjetas, textos, badges, tablas, botones— que tu app renderiza de forma nativa. Responde a quien llama con una interfaz, no solo con un valor: el estado del pedido con un botón Hablar con soporte, el resumen del lead con un enlace Agendar una demo.

"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\"}}}}}}"
}

Una pantalla es { "root", "elements" }: un mapa plano de elementos, cada uno con un type, props, children (claves de elementos) y un on opcional (evento → acción). La salida vuelve completa: todas las props de cada componente, null cuando no se usan.

El catálogo

Las pantallas usan el catálogo de Dcision: un subconjunto exacto de los componentes shadcn de json-render, con las mismas props:

ComponentesUso
Card, Stack, Grid, SeparatorDiseño.
Heading, Text, Badge, AlertTexto y estado.
Table, Image, Avatar, ProgressDatos y multimedia.
Button, LinkAcciones (on.press).
AcciónParamsSignificado
reply{ "text": "…" }Envía el texto de vuelta como el siguiente mensaje del usuario: una respuesta rápida.
open_url{ "url": "https://…" }Abre una URL.

Cómo Dcision valida una pantalla

Toda pantalla —de una plantilla o de un LLM— pasa por las validaciones propias de json-render y por el refuerzo de Dcision:

  1. autoFixSpec de json-render corrige errores comunes de los modelos (un visible dentro de props, un hijo que no existe).
  2. La estructura debe sostenerse: una raíz que existe, hijos que existen, tipos de componente conocidos.
  3. Las props se validan por componente con su schema: las props desconocidas se rechazan.
  4. Acciones: solo reply y open_url, en un evento que el componente tiene (press), con params válidos.
  5. Las URLs —Link.href, Image.src, Avatar.src, open_url— deben ser https:// (sin enlaces javascript:, sin rastreo por http plano).
  6. Solo valores finales: sin repeat, condiciones de visibilidad ni expresiones $state; className siempre es null. Como máximo 60 elementos y 32 KB.

En el modo extract, el modelo recibe el prompt de catálogo de json-render más tus instrucciones; si su pantalla no pasa una validación, Dcision le devuelve los problemas una vez. Las plantillas se validan al guardar, con valores de ejemplo.

Renderízala

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 también renderiza la misma spec con React Native, React Email, React PDF y otros destinos: mapea allí los mismos nombres de componentes.

En el Playground y en los logs

  • En el Playground, los destinos template siempre se ejecutan (son gratis); los destinos extract muestran el prompt y el schema estricto que se enviarían ("status": "preview"), a menos que ejecutes los destinos de verdad. Las pantallas se renderizan, y al pulsar un botón se muestra la acción que enviaría.
  • El log de ejecución guarda el output cuando la decisión almacena las salidas (storeOutput); con storeOutput: false, solo guarda si la salida se construyó.
  • Los SDKs la exponen como decision.output; en TypeScript, tipada con dcision.decide<Result, Output>(…).

En esta página