Generador de esquema JSON

Para qué sirve JSON Schema

JSON Schema es una forma declarativa de describir cómo debe verse un documento JSON: qué propiedades tiene, qué tipos llevan esas propiedades, qué es requerido vs opcional y qué valores son válidos. Es el equivalente del mundo JSON a XSD para XML o a una definición de tabla de base de datos. El proyecto oficial vive en json-schema.org.

Donde te lo encontrarás:

• Contratos de API. OpenAPI 3.1 (lanzado en febrero de 2021) embebe JSON Schema directamente: cada cuerpo de petición y cuerpo de respuesta en una spec de API moderna se describe con un fragmento de JSON Schema.
• Autocompletado y validación de IDE. El settings.json de VS Code, los package.json y tsconfig.json de tu proyecto, los archivos workflow.yml de GitHub Actions, todos autocompletan y se lintean contra JSON Schemas publicados.
• Validación del lado del servidor. Express / Fastify / Spring / Flask / FastAPI / Echo se integran todos con validadores de JSON Schema (AJV, jsonschema, fastjsonschema) para rechazar cuerpos de petición malformados antes de que lleguen a la lógica de negocio.
• Generación de código. Herramientas como quicktype, json-schema-to-typescript y datamodel-code-generator convierten un schema en structs de Go, tipos de TypeScript, dataclasses de Python, POJOs de Java, etc., proporcionando tipos agnósticos al lenguaje desde una sola fuente.
• Documentación. Un schema sirve también como documentación legible por máquina para cualquier dato con forma de JSON que publiques.

Los drafts que verás por ahí

La especificación de JSON Schema se ha publicado como una serie de drafts. El draft estable actual es 2020-12 (según la página oficial de la spec: «The current version is 2020-12»). Los drafts que podrías encontrarte:

• Draft 4, viejo pero todavía en uso; OpenAPI 3.0 usaba un subconjunto extendido del JSON Schema Specification Wright Draft 00 (a veces llamado informalmente Draft 5), cercano pero no idéntico a Draft 4.
• Draft 6, Draft 7, Draft 7 (2018) fue el draft de producción dominante durante años y sigue siendo muy común en herramientas legacy.
• Draft 2019-09, primer draft en usar la convención de identificador año-mes; introdujo $defs junto a la palabra clave legacy definitions.
• Draft 2020-12, el draft estable actual y lo que este generador emite. Alineado con OpenAPI 3.1.

Ante la duda, elige el draft que coincida con tu validador. AJV (el validador de JavaScript más popular) soporta Drafts 04, 06, 07, 2019-09 y 2020-12 con opt-in explícito. jsonschema en Python hace lo mismo. Si no sabes qué quiere tu consumidor aguas abajo, 2020-12 es un default seguro para trabajo nuevo.

Los tipos integrados

JSON Schema describe siete tipos base correspondientes a las clases de valor de JSON:

Las palabras clave de composición te dejan mezclar y combinar: oneOf (exactamente uno), anyOf (al menos uno), allOf (todos), not (el inverso). Más enum para una lista finita de valores permitidos y const para un único valor fijo.

Lo que un schema autogenerado puede y no puede decirte

Inferir un schema desde un único ejemplo JSON es potente pero limitado. El generador puede detectar:

• El tipo de cada valor hoja (string vs number vs boolean vs array vs object).
• La estructura de objetos y arrays anidados.
• Las claves que aparecen en el ejemplo (y marcarlas como required si activas la opción).

No puede detectar:

• Campos opcionales. Una clave en tu ejemplo podría ser opcional en la spec real, pero un único ejemplo no puede decirte cuál. Todo parece requerido por defecto.
• Pistas de formato. La cadena "2024-04-12" parece una fecha, pero también podría ser una etiqueta de texto libre que casualmente parece una fecha. Añade format: date a mano si el campo es de verdad una fecha.
• Restricciones de validación. Longitud máxima, valores enum permitidos, patrones regex: todos necesitan input humano.
• Cadenas de documentación. title, description y examples en cada campo mejoran la experiencia de desarrollador pero requieren curaduría.
• Variantes. Si un campo puede ser cadena o número según el contexto, un único ejemplo elegirá uno y se perderá el otro. Combina varios ejemplos o usa oneOf manualmente.

Trata la salida como un punto de partida al 70%. Las adiciones valiosas (qué campos están realmente requeridos, qué formatos de cadena aplican, qué rangos de valor están permitidos, qué significa cada campo) son la fase de curaduría humana.

Dos trampas sutiles que conviene conocer

• format es consultivo por defecto en 2020-12. El vocabulario format-annotation marca format: email como una pista, no como una regla de validación dura, a menos que tu validador opte explícitamente por format-assertion. Así que una cadena que no coincide con la regex de email sigue pasando por defecto. El modo strict de AJV y el paquete ajv-formats añaden validación de formato completa; comprueba los defaults de tu validador antes de confiar en chequeos de formato para input crítico de seguridad.
• additionalProperties: false no coopera bien con allOf. Si compones schemas con allOf para validación tipo herencia, additionalProperties: false en una rama no ve propiedades definidas en ramas hermanas, así que campos legítimos fallan la validación. El arreglo en Draft 2019-09+ es unevaluatedProperties: false, que es consciente de la composición.

JSON Schema vs Zod / Joi / Yup vs tipos de TypeScript

Varias tecnologías se solapan con el rol de JSON Schema; cada una tiene un sweet spot distinto:

• JSON Schema. JSON declarativo, validación en tiempo de ejecución, agnóstico al lenguaje. Gana cuando los contratos de API cruzan fronteras lingüísticas (p. ej. un servidor Go, un pipeline de datos Python y un frontend TypeScript que consumen la misma API).
• Tipos de TypeScript. Sólo en tiempo de compilación. Hermosos para seguridad de tipos en proceso dentro de una codebase TS pero desaparecen en runtime, sin proporcionar validación de JSON entrante. Herramientas como json-schema-to-typescript generan tipos desde un schema para lo mejor de ambos mundos.
• Zod / Joi / Yup. Validación runtime code-first en JavaScript / TypeScript, con inferencia de TypeScript integrada. Un solo lenguaje, pero excelente experiencia de desarrollador dentro de ese lenguaje. Los schemas son objetos JS, no JSON portable.
• Pydantic / Marshmallow. Los equivalentes Python: validación runtime basada en clases con anotaciones de tipo de Python.

Si tu schema necesita ser consumido por varios lenguajes o por herramientas (IDEs, tooling de OpenAPI, generadores de código), JSON Schema es el hogar correcto. Si te quedas dentro de un solo lenguaje, la opción nativa de ese lenguaje suele ser más agradable de escribir.

Casos de uso comunes

• Iniciar una spec de OpenAPI. Pega una respuesta de API real, genera el schema, mételo en tu components.schemas.
• Generar tipos de TypeScript / Go / Python vía quicktype o similar, proporcionando tipos agnósticos al lenguaje desde una sola fuente.
• Validar input no confiable en un endpoint de servidor con AJV / jsonschema / Pydantic.
• Escribir autocompletado de IDE para un formato de configuración personalizado. VS Code, los IDEs de JetBrains y otros leen JSON Schemas para alimentar el autocompletado de archivos JSON.
• Documentar la forma de un archivo de configuración para consumidores aguas abajo.
• Migrar entre formatos de datos. Un JSON Schema generado desde una fuente puede impulsar validación, transformación o documentación aguas abajo.

Errores comunes

1. Tratar el schema autogenerado como la spec final. Es un punto de partida. Añade pistas de formato, marca campos genuinamente opcionales, añade documentación, define rangos de valor.
2. Saltarse la declaración $schema. Los validadores la usan para saber qué draft aplicar. Inclúyela siempre arriba del schema.
3. Tratar required como un atributo por propiedad. A diferencia de XSD o de los schemas de Mongoose, el required de JSON Schema es un array a nivel del objeto padre que lista los nombres de las propiedades requeridas.
4. Olvidar additionalProperties: false cuando quieres validación estricta. El default es true, lo que significa que las claves desconocidas se permiten silenciosamente.
5. Confundir enum con examples. enum = la lista de valores permitidos (validación). examples = valores de muestra sólo para documentación (sin efecto de validación).
6. Asumir que format se hace cumplir. Por defecto en Draft 2020-12 es una anotación, no una aserción; tu regex de email no se ejecuta a menos que optes por ello.
7. Inferir opcionalidad desde un único ejemplo. Cada clave de tu ejemplo se vuelve requerida por defecto. Las specs reales casi siempre tienen campos opcionales; quítalos del array required como parte de la curaduría.

Más preguntas frecuentes

¿Funcionará el schema con OpenAPI 3.1?

Sí. OpenAPI 3.1 (lanzado en febrero de 2021) alineó su lenguaje de schema completamente con JSON Schema Draft 2020-12, que es lo que este generador emite. Mete el schema en components.schemas dentro de tu documento OpenAPI y referéncialo vía $ref. El antiguo OpenAPI 3.0 usaba un subconjunto anterior; podrías necesitar ajustar si te diriges a 3.0.

¿Puedo generar tipos en mi lenguaje a partir de este schema?

Sí. quicktype genera TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm y otros desde un JSON Schema. json-schema-to-typescript es una alternativa específica de JS. La mayoría de lenguajes modernos tienen al menos una herramienta schema-a-tipos; el schema generado funciona como entrada para todas ellas.

¿Cuál es la diferencia entre $defs y definitions?

Ambos son lugares para poner sub-schemas reutilizables que puedes $referenciar en otra parte del documento. definitions es el nombre legacy, usado en Drafts 04, 06 y 07. $defs es el nombre actual, introducido en Draft 2019-09 y continuando en 2020-12. Funcionalmente equivalentes, pero usa $defs para trabajo nuevo.

¿Mi JSON se envía a algún sitio?

No. La generación de schema corre enteramente en tu navegador. El JSON pegado se parsea localmente, se recorre y se emite como un schema en el textarea de salida. Nada se sube a un servidor, se loguea ni se conserva tras cerrar la pestaña. Esto importa porque los ejemplos JSON suelen contener datos reales (registros de cliente, respuestas de API internas, info de empleados) que no quieres que pasen por un tercero.

¿Por qué el schema de mi array sólo describe el primer elemento?

La inferencia desde un único ejemplo trata los arrays como homogéneos: mira el primer elemento y asume que el resto coincide. Si tu array real puede contener formas distintas, tendrás que escribir los items como { "oneOf": [...] } a mano. O ejecutar el generador en cada variante por separado y combinar los schemas.

¿Debería usar un generador o escribir el schema a mano?

Para un schema pequeño que controlas de extremo a extremo, escribirlo a mano te enseña la spec más rápido. Para una respuesta de API grande con docenas de objetos anidados, generar te da un borrador en segundos y dedicas el tiempo ahorrado a curar restricciones, descripciones y arrays required. La mayoría de los desarrolladores en activo hacen ambas cosas: generar, luego curar.