Esquema de decisión
El documento JSON detrás de cada decisión — el estado que acepta, las preguntas que responde, los compuestos, las políticas que eligen la acción, la configuración de runtime y los destinos.
Una decisión se define con un único documento JSON, el esquema de decisión. El editor y el constructor visual lo editan por ti (el panel de la derecha lo muestra en Schema de la decisión), la CLI lo genera y lo valida sin conexión, y cada versión desplegada guarda un snapshot completo de él.
El esquema es neutral respecto al motor: nada en él es específico de Jev ni de ningún otro motor.
Un ejemplo completo
Esta es la plantilla Calificación de leads tal como se guarda, con todos los valores predeterminados completados:
{
"stateSchema": {
"kind": "object",
"fields": [
{ "key": "message", "type": "string", "required": true, "description": "Inbound lead message" },
{ "key": "company_size", "type": "number", "required": false, "description": "Employee count" },
{ "key": "source", "type": "string", "required": false, "description": "website, referral, ads…" }
]
},
"questions": [
{
"key": "purchase_intent",
"type": "probability",
"instructions": "Does this lead have real intent to buy in the next 30 days?",
"criteria": {
"yes": "asks for pricing, a demo, a quote or a start date",
"no": "just browsing, student, vendor or spam"
}
},
{
"key": "priority",
"type": "score",
"instructions": "How urgent is it to answer this lead?",
"scale": ["low", "medium", "high", "critical"]
},
{
"key": "route",
"type": "choice",
"instructions": "Which team should receive this lead?",
"options": [
{ "value": "sales", "description": "high intent, ready to talk to sales" },
{ "value": "sdr", "description": "some intent, needs qualification" },
{ "value": "nurture", "description": "early stage, send content" },
{ "value": "spam", "description": "spam, vendor pitch or irrelevant" },
{ "value": "other", "description": "none of the options above" }
]
}
],
"composites": [
{
"key": "lead_score",
"description": "0–1 ranking: intent counts double, priority adds, spam-like routes don't count",
"terms": [
{ "question": "purchase_intent", "weight": 2 },
{ "question": "priority", "weight": 1 },
{ "question": "route", "option": "sales", "weight": 1 }
]
}
],
"policies": [
{ "field": "route", "on": "output", "operator": "eq", "value": "spam", "action": "block" },
{ "field": "purchase_intent", "on": "confidence", "operator": "lt", "value": 0.6, "action": "escalate" }
],
"settings": {
"storeInput": true,
"storeOutput": true,
"timeoutMs": 5000,
"fallbackAction": "escalate",
"onEngineError": "error"
}
}Campos de nivel superior
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
stateSchema | object | Sí | La entrada que acepta la decisión — consulta Esquema del estado. |
questions | array | Sí | De 1 a 64 preguntas — consulta Preguntas. |
composites | array | No | Hasta 20 combinaciones ponderadas de respuestas. Predeterminado [] — consulta Compuestos. |
policies | array | No | Hasta 50 reglas, evaluadas en orden. Predeterminado [] — consulta Políticas y acciones. |
context | string | No | Hasta 8,000 caracteres de contexto de negocio enviados con cada estado — consulta Contexto. |
settings | object | No | Motor, almacenamiento, presupuesto de tiempo, acción de fallback y comportamiento ante errores del motor — consulta Configuración de la decisión. |
destinations | array | No | Hasta 20 destinos — qué pasa después de la decisión, por opción, nivel, umbral o acción final. Predeterminado [] — consulta Destinos. |
Claves
Los campos del estado, las claves de las preguntas, las claves de los compuestos y los valores de las opciones de choice comparten una misma regla, porque se convierten en claves y valores JSON en la respuesta de la API:
- snake_case: empiezan con una letra minúscula, seguida de letras minúsculas, dígitos o
_; - como máximo 48 caracteres (patrón
^[a-z][a-z0-9_]{0,47}$); - únicas: las claves de preguntas y compuestos dentro de la decisión, las claves de campo dentro del estado, los valores de opción dentro de una pregunta.
Esquema del estado
El estado es lo que tu aplicación envía en el body de la solicitud como { "state": … }. Elige uno de tres tipos — las mismas tres formas que Jev evalúa de forma nativa:
| Tipo | Envía | Adecuado para |
|---|---|---|
object | un objeto JSON con campos tipados | la mayoría de las decisiones: los campos con nombre mantienen clara cada parte de la entrada |
text | un string no vacío | un mensaje, comentario o fragmento |
list | un array no vacío de strings u objetos | la transcripción de un chat, un lote de registros |
Estado de objeto
{ "kind": "object", "fields": [{ "key": "message", "type": "string", "required": true }] }fields contiene hasta 50 definiciones de campo:
| Propiedad | Tipo | Predeterminado | Descripción |
|---|---|---|---|
key | string | — | La clave JSON en el estado. |
type | string | — | Uno de string, number, integer, boolean, array, object — o un archivo: image, audio, file (consulta Entradas). |
required | boolean | false | Rechaza los estados que no tienen este campo. |
description | string | — | Hasta 255 caracteres. Documenta el campo en el contrato de la API que muestra el editor. |
Cómo se valida el estado antes de que se ejecute el motor:
- el estado debe ser un objeto JSON (no un array, un string ni
null); - un campo
requireddebe estar presente y no sernull; un campo opcional puede faltar o sernull; - los tipos son estrictos:
numberes cualquier número finito,integerun número entero,objectun objeto no nulo que no es un array —"500"no es unnumber;image,audioyfileaceptan una URLdata:, una URLhttps://o{ "data" | "url", "filename" }; - los campos no declarados se aceptan y se reenvían al motor, así que puedes enviar contexto adicional sin cambiar el esquema;
- se informa el primer campo que falla, por ejemplo
422 INVALID_STATEcon"Field company_size must be a number.".
Las descripciones de campo son documentación
El motor recibe las claves y los valores de tu estado, el context de la decisión y las preguntas — no las descripciones de los campos. Dale al motor lo que necesita mediante nombres de campo descriptivos, context e instrucciones precisas, y refiérete a los campos por su nombre en las instrucciones: "Does `message` ask for a demo?".
Estado de texto
{ "kind": "text" }El estado debe ser un string no vacío: { "state": "Congratulations! You won a $1000 gift card…" }. El motor recibe el propio string.
Estado de lista
{ "kind": "list", "items": "string" }El estado debe ser un array no vacío de hasta 500 elementos. items define qué es cada elemento:
items | Cada elemento debe ser | Estado de ejemplo |
|---|---|---|
string (predeterminado) | un string | ["Hi!", "My card was charged twice.", "Can you refund one?"] |
object | un objeto JSON (no null, no un array) | [{ "role": "customer", "text": "My card was charged twice." }, { "role": "agent", "text": "Let me check." }] |
El motor recibe el propio array. Los errores nombran el problema: "Field state must be a non-empty array.", "Field state has too many items (612, max 500)." o "Item 2 of state must be an object.".
Una lista es un solo estado: cada pregunta se responde sobre la lista en su conjunto — "¿esta conversación pide un reembolso?" — no una vez por elemento. Para clasificar elementos de forma independiente, envía una decisión por elemento, o usa un estado de objeto como { "messages": [ … ] } con una pregunta por posición ("Is `messages[2]` a complaint?").
Límites de tamaño
El estado serializado debe caber en 128 KB y en unos 32,000 tokens (estimados como caracteres ÷ 4) — sin contar sus archivos, que tienen sus propios límites (20 MB cada uno; su texto se recorta para que quepa — consulta Entradas).
Jev también tiene un presupuesto de tokens para toda la llamada: unos 32,000 tokens para el estado más la pregunta más larga y 64,000 tokens para el estado más todas las preguntas. Dcision comprueba ambos antes de llamar al motor; un estado que supera los límites falla con 422 INVALID_STATE y un mensaje que indica qué límite se alcanzó — por ejemplo "The state plus all questions is too large for one engine call (~65210 tokens, max 64000). Shorten the state or split the decision." Consulta Límites.
Contexto
context es texto libre, de hasta 8,000 caracteres, enviado con cada estado bajo la clave reservada decision_context — por ejemplo "Inbound messages from the pricing page of a B2B SaaS. Prices start at $29/month." Describe el negocio, no la respuesta esperada.
Cómo lo recibe el motor:
| Tipo de estado | Qué evalúa el motor cuando context está definido |
|---|---|
object | tu objeto más un campo decision_context |
text, list | { "decision_context": "<context>", "input": <your state> } |
Sin context, el motor recibe tu estado sin cambios.
decision_context está reservado: cuando la decisión tiene un context, este reemplaza un campo decision_context que tu aplicación envíe en un estado de objeto. Cualquier otro campo — incluido uno llamado context — se reenvía tal cual.
Entradas estructuradas
Las instrucciones, las descripciones de las opciones de choice, los niveles de score y los criterios de probability aceptan objetos o arrays JSON además de texto — Jev lee estructuras de forma nativa. Úsalo para etiquetar las partes de una pregunta larga, para pasar datos de apoyo o para dar a cada opción una rúbrica. Consulta Instrucciones y criterios estructurados.
Validación
Las mismas reglas se aplican en todas partes:
-
Editor — valida mientras escribes, muestra cada problema con un enlace Ir al error y solo guarda automáticamente los borradores válidos.
-
API — guardar o desplegar un esquema no válido falla con
422 INVALID_SCHEMA;detailslista cada problema con su ruta:{ "error": { "code": "INVALID_SCHEMA", "message": "The decision schema is invalid.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w", "details": [ { "path": "questions.0.options", "message": "Add at least 2 options (besides \"other\")." }, { "path": "policies.1.field", "message": "Unknown question \"intent\"." }, { "path": "composites.0.terms.2.option", "message": "Pick the option whose probability counts." } ] } } -
CLI —
dcision validate decision.jsoncomprueba un archivo sin conexión, ydcision check-statecomprueba un estado contra él.
Las reglas de validación pueden volverse más estrictas con el tiempo — desde la v0.3, por ejemplo, los valores de las reglas se comprueban contra las opciones, los niveles y los rangos con los que se comparan ("Use a number between 0 and 1 (e.g. 0.7, not 70)."). Las reglas más estrictas se aplican cuando guardas o despliegas; las versiones ya desplegadas siguen ejecutándose sin cambios, así que una regla endurecida nunca convierte un endpoint en vivo en un error.
El contrato de la API
La vista Contrato de la API del editor muestra aquello con lo que pueden contar los clientes de la decisión: el estado como JSON Schema, la forma de la respuesta de cada pregunta y los compuestos.
{
"name": "lead-qualification",
"state": {
"type": "object",
"required": ["message"],
"properties": {
"message": { "type": "string", "description": "Inbound lead message" },
"company_size": { "type": "number", "description": "Employee count" },
"source": { "type": "string", "description": "website, referral, ads…" }
}
},
"questions": {
"purchase_intent": { "type": "probability", "range": [0, 1] },
"priority": { "type": "score", "scale": ["low", "medium", "high", "critical"] },
"route": { "type": "choice", "options": ["sales", "sdr", "nurture", "spam", "other"] }
},
"composites": {
"lead_score": { "type": "number" }
}
}Un estado de texto se muestra como { "type": "string" } y un estado de lista como { "type": "array", "items": { "type": "string" } } (o "object"). Las escalas de score listan las etiquetas de los niveles, también para los niveles estructurados. composites solo aparece cuando la decisión tiene alguno.
Inicio rápido
Regístrate, crea una decisión a partir de una plantilla, pruébala en el Playground, despliégala y llámala con cURL, JavaScript o Python — en unos cinco minutos.
Entradas — texto, JSON, imágenes, audio y documentos
Lo que una decisión puede leer — texto, JSON estructurado, imágenes, notas de voz y documentos (PDF, Word, Excel, PowerPoint, CSV y más) — y cómo llega cada uno a Jev, Laya u OpenAI Decisions.