BroadRouter
Comenzar

JSON Schema (esquema JSON)

Actualizado

JSON Schema es un vocabulario, escrito en JSON, para describir y validar la estructura de datos JSON: tipos, campos obligatorios, valores permitidos y anidamiento. La versión actual es la 2020-12. Las APIs de LLM lo usan para definir los parámetros de las herramientas y la forma exacta que debe seguir una salida estructurada.

También llamado: esquema JSON, JSON Schema, validación de JSON, json_schema, JSON Schema draft 2020-12

Un prompt que dice “responde en JSON” deja la forma al azar. Un JSON Schema pone la forma por escrito para que una máquina pueda verificarla.

Cómo funciona

La especificación tiene dos partes principales: Core, que “defines the basic foundation of JSON Schema” (traducción: define la base de JSON Schema), y Validation, que “defines the validation keywords” (traducción: define las palabras clave de validación). La versión actual es la 2020-12; la anterior fue 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
}

Las APIs de LLM usan esquemas en dos lugares. Las definiciones de herramientas ponen uno en parameters para describir los argumentos. La salida estructurada envía uno en response_format como {"type": "json_schema", "json_schema": {...}}, que según OpenAI “ensures the model will match your supplied JSON schema” (traducción: garantiza que el modelo coincida con el JSON Schema que usted proporcionó).

El modo estricto de OpenAI solo acepta un subconjunto. De su sección de esquemas admitidos:

  • Tipos: string, number, boolean, integer, object, array, enum y anyOf.
  • La raíz debe ser un objeto y no puede usar anyOf.
  • additionalProperties: false y todos los campos listados en required; para que un campo sea opcional, permita null, como hace note arriba.
  • Hasta 5000 propiedades de objeto y 10 niveles de anidamiento, y hasta 1000 valores de enum en total.
  • No se admiten: allOf, not, dependentRequired, dependentSchemas, if, then, else.

Por qué importa

  • Validación. El mismo esquema que guía al modelo verifica su respuesta en su código. Una verificación fallida da un error exacto que puede reenviar al modelo.
  • Portabilidad. Un esquema escrito con el subconjunto estricto funciona con más proveedores que uno que usa todas las palabras clave.
  • Tokens. Los esquemas de las definiciones de herramientas se envían como entrada en cada solicitud. Las descripciones largas cuestan tokens en cada turno.

En BroadNet Inference

La referencia de la API de BroadNet documenta tool calling y salida estructurada para GLM 5.3 y Qwen3.8 27B, pero no qué palabras clave del esquema se aplican. Limite sus esquemas al subconjunto sencillo de arriba y valide cada respuesta. Cree un esquema con el generador de JSON Schema, verifique las respuestas con el validador de salida JSON de LLM y consulte el artículo sobre salida estructurada para ver un ejemplo completo. Con otros modelos, pida JSON en el prompt y valide la respuesta; BroadNet no documenta el modo JSON, así que pruébelo antes de depender de él.

Errores comunes

  • Usar allOf o palabras clave condicionales y suponer que el servidor las aplica.
  • Hacer opcionales los campos dejándolos fuera de required en modo estricto, en lugar de permitir null.

Preguntas frecuentes

¿Las APIs de LLM admiten todo JSON Schema?

No. OpenAI admite un subconjunto: por ejemplo, la raíz debe ser un objeto, todos los campos deben ser obligatorios, additionalProperties debe ser false, y palabras clave como allOf, not e if/then/else no se admiten.

¿Cuál es la diferencia entre JSON Schema y el modo JSON?

El modo JSON solo promete JSON válido. Un JSON Schema le indica al modelo, y a su validador, qué campos y tipos debe tener ese JSON.

¿Puedo usar JSON Schema con BroadNet Inference?

Los parámetros de herramientas y la salida estructurada, que usan esquemas, están documentados para GLM 5.3 y Qwen3.8 27B. BroadNet no documenta qué palabras clave del esquema aplica, así que valide cada respuesta.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity