Decision schema
O documento JSON por trás de toda decisão — o estado que ela aceita, as perguntas que responde, composites, as políticas que escolhem a ação, as configurações de runtime e os destinos.
Uma decisão é definida por um único documento JSON, o decision schema. O editor e o construtor visual o editam por você (o painel da direita o mostra em Schema da decisão), a CLI gera o esqueleto e o valida offline, e cada versão publicada guarda um snapshot completo dele.
O schema é neutro em relação ao engine: nada nele é específico do Jev ou de qualquer outro engine.
Um exemplo completo
Este é o template Qualificação de leads como ele fica guardado, com todos os padrões preenchidos:
{
"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 primeiro nível
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
stateSchema | object | Sim | A entrada que a decisão aceita — veja State schema. |
questions | array | Sim | De 1 a 64 perguntas — veja Perguntas. |
composites | array | Não | Até 20 combinações ponderadas de respostas. Padrão [] — veja Composites. |
policies | array | Não | Até 50 regras, avaliadas em ordem. Padrão [] — veja Políticas e ações. |
context | string | Não | Até 8.000 caracteres de contexto de negócio enviados com todo estado — veja Contexto. |
settings | object | Não | Engine, armazenamento, orçamento de tempo, ação de fallback e comportamento em erros de engine — veja Configurações da decisão. |
destinations | array | Não | Até 20 destinos — o que acontece depois da decisão, por opção, nível, limiar ou ação final. Padrão [] — veja Destinos. |
Chaves
Os campos do estado, as chaves das perguntas, as chaves dos composites e os valores das opções de choice seguem uma mesma regra, porque viram chaves e valores JSON na resposta da API:
- snake_case: começam com uma letra minúscula, seguida de letras minúsculas, dígitos ou
_; - no máximo 48 caracteres (padrão
^[a-z][a-z0-9_]{0,47}$); - únicos: chaves de perguntas e de composites dentro da decisão, chaves de campos dentro do estado, valores de opções dentro de uma pergunta.
State schema
O estado é o que a sua aplicação envia no body da requisição como { "state": … }. Escolha um de três tipos — as mesmas três formas que o Jev avalia nativamente:
| Tipo | Envie | Bom para |
|---|---|---|
object | um objeto JSON com campos tipados | a maioria das decisões: campos nomeados deixam cada parte da entrada clara |
text | uma string não vazia | uma mensagem, um comentário ou um trecho |
list | um array não vazio de strings ou objetos | a transcrição de um chat, um lote de registros |
Estado de objeto
{ "kind": "object", "fields": [{ "key": "message", "type": "string", "required": true }] }fields contém até 50 definições de campo:
| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
key | string | — | A chave JSON no estado. |
type | string | — | Um de string, number, integer, boolean, array, object — ou um arquivo: image, audio, file (veja Entradas). |
required | boolean | false | Rejeita estados que não têm este campo. |
description | string | — | Até 255 caracteres. Documenta o campo no contrato da API mostrado pelo editor. |
Como o estado é validado antes de o engine rodar:
- o estado precisa ser um objeto JSON (não um array, uma string ou
null); - um campo
requiredprecisa estar presente e não sernull; um campo opcional pode faltar ou sernull; - os tipos são estritos:
numberé qualquer número finito,integerum número inteiro,objectum objeto não nulo que não é array —"500"não é umnumber;image,audioefileaceitam uma URLdata:, uma URLhttps://ou{ "data" | "url", "filename" }; - campos não declarados são aceitos e repassados ao engine, então você pode enviar contexto extra sem mudar o schema;
- o primeiro campo que falhar é informado, por exemplo
422 INVALID_STATEcom"Field company_size must be a number.".
As descrições dos campos são documentação
O engine recebe as chaves e os valores do seu estado, o context da decisão e as perguntas — não as descrições dos campos. Dê ao engine o que ele precisa por meio de nomes de campos descritivos, context e instruções precisas, e cite os campos nas instruções pelo nome: "Does `message` ask for a demo?".
Estado de texto
{ "kind": "text" }O estado precisa ser uma string não vazia: { "state": "Congratulations! You won a $1000 gift card…" }. O engine recebe a própria string.
Estado de lista
{ "kind": "list", "items": "string" }O estado precisa ser um array não vazio de até 500 itens. items define o que cada item é:
items | Cada item precisa ser | Exemplo de estado |
|---|---|---|
string (padrão) | uma string | ["Hi!", "My card was charged twice.", "Can you refund one?"] |
object | um objeto JSON (não null, não um array) | [{ "role": "customer", "text": "My card was charged twice." }, { "role": "agent", "text": "Let me check." }] |
O engine recebe o próprio array. Os erros dizem qual é o problema: "Field state must be a non-empty array.", "Field state has too many items (612, max 500)." ou "Item 2 of state must be an object.".
Uma lista é um estado: cada pergunta é respondida sobre a lista como um todo — "esta conversa pede um reembolso?" — e não uma vez por item. Para classificar os itens de forma independente, envie uma decisão por item, ou use um estado de objeto como { "messages": [ … ] } com uma pergunta por posição ("Is `messages[2]` a complaint?").
Limites de tamanho
O estado serializado precisa caber em 128 KB e em cerca de 32.000 tokens (estimados como caracteres ÷ 4) — sem contar os arquivos dele, que têm limites próprios (20 MB cada; o texto deles é cortado para caber — veja Entradas).
O Jev também tem um orçamento de tokens para a chamada inteira: cerca de 32.000 tokens para o estado mais a pergunta mais longa e 64.000 tokens para o estado mais todas as perguntas. A Dcision confere os dois antes de chamar o engine; um estado acima dos limites falha com 422 INVALID_STATE e uma mensagem que diz qual limite foi atingido — por exemplo "The state plus all questions is too large for one engine call (~65210 tokens, max 64000). Shorten the state or split the decision." Veja Limites.
Contexto
context é texto livre, de até 8.000 caracteres, enviado com todo estado sob a chave reservada decision_context — por exemplo "Inbound messages from the pricing page of a B2B SaaS. Prices start at $29/month." Descreva o negócio, não a resposta esperada.
Como o engine o recebe:
| Tipo de estado | O que o engine avalia quando context está definido |
|---|---|
object | o seu objeto mais um campo decision_context |
text, list | { "decision_context": "<context>", "input": <your state> } |
Sem context, o engine recebe o seu estado sem alterações.
decision_context é reservado: quando a decisão tem um context, ele substitui um campo decision_context que a sua aplicação envie num estado de objeto. Qualquer outro campo — inclusive um chamado context — é repassado como está.
Entradas estruturadas
As instruções, as descrições das opções de choice, os níveis de score e os critérios de probability aceitam objetos ou arrays JSON além de texto — o Jev lê estrutura nativamente. Use isso para rotular as partes de uma pergunta longa, para passar dados de apoio ou para dar uma rubrica a cada opção. Veja Instruções e critérios estruturados.
Validação
As mesmas regras rodam em todo lugar:
-
Editor — valida enquanto você digita, mostra cada problema com um link Ir para o erro e só salva automaticamente rascunhos válidos.
-
API — salvar ou publicar um schema inválido falha com
422 INVALID_SCHEMA;detailslista cada problema com o caminho dele:{ "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.jsonconfere um arquivo offline, edcision check-stateconfere um estado contra ele.
As regras de validação podem ficar mais rígidas com o tempo — desde a v0.3, por exemplo, os valores das regras são conferidos contra as opções, os níveis e os intervalos com que eles são comparados ("Use a number between 0 and 1 (e.g. 0.7, not 70)."). Regras mais rígidas valem quando você salva ou publica; as versões já publicadas continuam rodando sem mudanças, então uma regra endurecida nunca transforma um endpoint no ar num erro.
O contrato da API
A visão Contrato da API do editor mostra no que os clientes da decisão podem confiar: o estado como JSON Schema, o formato da resposta de cada pergunta e os composites.
{
"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" }
}
}Um estado de texto aparece como { "type": "string" } e um estado de lista como { "type": "array", "items": { "type": "string" } } (ou "object"). As escalas de score listam os rótulos dos níveis, também para níveis estruturados. composites só aparece quando a decisão tem algum.
Início rápido
Cadastre-se, crie uma decisão a partir de um template, teste no Playground, faça o deploy e chame-a com cURL, JavaScript ou Python — em cerca de cinco minutos.
Entradas — texto, JSON, imagens, áudio e documentos
O que uma decisão consegue ler — texto, JSON estruturado, imagens, áudios e documentos (PDF, Word, Excel, PowerPoint, CSV e mais) — e como cada um chega ao Jev, ao Laya ou à OpenAI Decisions.