BroadRouter
Começar

JSON Schema

Atualizado em

JSON Schema é um vocabulário, escrito em JSON, para descrever e validar a estrutura de dados JSON: tipos, campos obrigatórios, valores permitidos e aninhamento. A versão atual é a 2020-12. APIs de LLM o usam para definir parâmetros de tools e o formato exato que uma saída estruturada deve seguir.

Também chamado de: JSON Schema, schema JSON, esquema JSON, validação com JSON Schema, json_schema, JSON Schema draft 2020-12

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: false e todos os campos listados em required; para tornar um campo opcional, permita null, como note faz 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 allOf ou palavras-chave condicionais e presumir que o servidor as aplica.
  • No modo strict, tornar campos opcionais tirando-os de required em vez de permitir null.

Perguntas frequentes

As APIs de LLM suportam todo o JSON Schema?

Não. A OpenAI suporta um subconjunto: por exemplo, a raiz precisa ser um objeto, todo campo precisa ser obrigatório, additionalProperties precisa ser false e palavras-chave como allOf, not e if/then/else não são suportadas.

Qual é a diferença entre JSON Schema e JSON mode?

O JSON mode só promete JSON válido. Um JSON Schema diz ao modelo, e ao seu validador, quais campos e tipos esse JSON precisa ter.

Posso usar JSON Schema com a BroadNet Inference?

Parâmetros de tools e saída estruturada, que usam schemas, estão documentados para GLM 5.3 e Qwen3.8 27B. A BroadNet não documenta quais palavras-chave do schema ela aplica, então valide toda resposta.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity