Um prompt que diz “responda em JSON” deixa o formato ao acaso. Um JSON Schema registra esse formato para que uma máquina possa verificá-lo.
Como funciona
A especificação tem duas partes principais: Core, que “defines the basic foundation of JSON Schema” (tradução: define a base do JSON Schema), e Validation, que “defines the validation keywords” (tradução: define as palavras-chave de validação). A versão atual é a 2020-12; a anterior era a 2019-09.
{
"type": "object",
"properties": {
"name": {"type": "string"},
"amount": {"type": "number", "minimum": 0},
"currency": {"type": "string", "enum": ["SAR", "AED", "USD"]},
"note": {"type": ["string", "null"]}
},
"required": ["name", "amount", "currency", "note"],
"additionalProperties": false
}
APIs de LLM usam schemas em dois lugares. Definições de tools colocam um em parameters para descrever os argumentos. A saída estruturada envia um em response_format como {"type": "json_schema", "json_schema": {...}}, o que, segundo a OpenAI, “ensures the model will match your supplied JSON schema” (tradução: garante que o modelo vai seguir o JSON Schema fornecido).
O modo strict da OpenAI aceita só um subconjunto. Da seção de schemas suportados:
- Tipos: string, number, boolean, integer, object, array, enum e anyOf.
- A raiz precisa ser um objeto e não pode usar
anyOf. additionalProperties: falsee todos os campos listados emrequired; para tornar um campo opcional, permitanull, comonotefaz acima.- Até 5000 propriedades de objeto e 10 níveis de aninhamento, e até 1000 valores de enum no total.
- Não suportados:
allOf,not,dependentRequired,dependentSchemas,if,then,else.
Por que isso importa
- Validação. O mesmo schema que orienta o modelo verifica a resposta no seu código. Uma verificação que falha gera um erro preciso para devolver ao modelo.
- Portabilidade. Um schema escrito dentro do subconjunto strict funciona em mais provedores do que um que usa todas as palavras-chave.
- Tokens. Schemas em definições de tools são enviados como entrada em toda requisição. Descrições longas custam tokens a cada turno.
Na BroadNet Inference
A referência da API da BroadNet documenta tool calling e saída estruturada para GLM 5.3 e Qwen3.8 27B, mas não quais palavras-chave do schema são aplicadas. Mantenha os schemas no subconjunto simples acima e valide toda resposta. Monte um schema com o gerador de JSON Schema, confira as respostas com o validador de saída JSON de LLM e veja o post sobre saída estruturada para um exemplo completo. Em outros modelos, peça JSON no prompt e valide a resposta; o JSON mode não é documentado pela BroadNet, então teste antes de depender dele.
Erros comuns
- Usar
allOfou palavras-chave condicionais e presumir que o servidor as aplica. - No modo strict, tornar campos opcionais tirando-os de
requiredem vez de permitirnull.