BroadRouter
Inizia

JSON Schema

Aggiornato

JSON Schema è un vocabolario, scritto in JSON, per descrivere e validare la struttura dei dati JSON: tipi, campi obbligatori, valori ammessi e annidamento. La versione attuale è la 2020-12. Le API LLM lo usano per definire i parametri dei tool e la forma esatta che un output strutturato deve seguire.

Detto anche: JSON Schema, schema JSON, schema JSON per LLM, validazione JSON Schema, json_schema, JSON Schema draft 2020-12

Un prompt che dice “rispondi in JSON” lascia la forma al caso. Un JSON Schema la mette per iscritto, così una macchina può verificarla.

Come funziona

La specifica ha due parti principali: Core, che “defines the basic foundation of JSON Schema” (traduzione: definisce le basi di JSON Schema), e Validation, che “defines the validation keywords” (traduzione: definisce le keyword di validazione). La versione attuale è la 2020-12; la precedente era la 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
}

Le API LLM usano gli schemi in due punti. Le definizioni dei tool ne mettono uno in parameters per descrivere gli argomenti. L’output strutturato ne invia uno in response_format come {"type": "json_schema", "json_schema": {...}}, che secondo OpenAI “ensures the model will match your supplied JSON schema” (traduzione: garantisce che il modello rispetti il JSON Schema fornito).

La strict mode di OpenAI accetta solo un sottoinsieme. Dalla sua sezione sugli schemi supportati:

  • Tipi: string, number, boolean, integer, object, array, enum e anyOf.
  • La radice deve essere un oggetto e non può usare anyOf.
  • additionalProperties: false e ogni campo elencato in required; per rendere un campo facoltativo, ammetti null, come fa note qui sopra.
  • Fino a 5000 proprietà di oggetto e 10 livelli di annidamento, e fino a 1000 valori enum in totale.
  • Non supportati: allOf, not, dependentRequired, dependentSchemas, if, then, else.

Perché è importante

  • Validazione. Lo stesso schema che guida il modello controlla la sua risposta nel tuo codice. Un controllo fallito dà un errore preciso da rimandare al modello.
  • Portabilità. Uno schema scritto entro il sottoinsieme strict funziona con più provider di uno che usa tutte le keyword.
  • Token. Gli schemi nelle definizioni dei tool vengono inviati come input a ogni richiesta. Descrizioni lunghe costano token a ogni turno.

Su BroadNet Inference

Il riferimento API di BroadNet documenta tool calling e output strutturato per GLM 5.3 e Qwen3.8 27B, ma non quali keyword dello schema vengano applicate. Limita gli schemi al sottoinsieme semplice qui sopra e valida ogni risposta. Crea uno schema con il generatore di JSON Schema, controlla le risposte con il validatore di output JSON per LLM e guarda l’articolo sull’output strutturato per un esempio completo. Sugli altri modelli, chiedi JSON nel prompt e valida la risposta; la JSON mode non è documentata da BroadNet, quindi provala prima di farci affidamento.

Errori comuni

  • Usare allOf o keyword condizionali e dare per scontato che il server le applichi.
  • In strict mode, rendere facoltativi i campi togliendoli da required invece di ammettere null.

Domande frequenti

Le API LLM supportano tutto JSON Schema?

No. OpenAI ne supporta un sottoinsieme: per esempio la radice deve essere un oggetto, ogni campo deve essere obbligatorio, additionalProperties deve essere false e keyword come allOf, not e if/then/else non sono supportate.

Che differenza c’è tra JSON Schema e JSON mode?

La JSON mode promette solo JSON valido. Un JSON Schema dice al modello, e al tuo validatore, quali campi e tipi deve avere quel JSON.

Posso usare JSON Schema con BroadNet Inference?

I parametri dei tool e l’output strutturato, che usano entrambi schemi, sono documentati per GLM 5.3 e Qwen3.8 27B. BroadNet non documenta quali keyword dello schema applica, quindi valida ogni risposta.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity