He enviado suficientes API para saber el momento exacto en que un proyecto necesita un esquema JSON. Nunca es al principio. Pasan tres semanas cuando un segundo equipo comienza a consumir su punto final, alguien envía un cuerpo de solicitud con formato incorrecto y a null se desliza en un campo que todos asumieron que siempre fue una cadena. De repente necesitas un contrato, un documento que diga, en una forma que una máquina puede hacer cumplir, " así es como se ve una carga útil válida." Ese documento es un esquema JSON, y escribir uno a mano desde un punto final que ya devuelve datos reales es uno de los trabajos más tediosos en el trabajo backend.
TL;Dr: Pegue una muestra JSON en el Generador de esquemas JSON, elija Draft-07 o 2020-12 e infiere un esquema - tipos,
requiredcampos, elementos de matriz fusionados y formatos de cadena comodate-timeyuuid. Se ejecuta completamente en su navegador, por lo que las cargas útiles que transportan tokens y datos personales nunca salen de la página. Trate el resultado como un primer borrador sólido y luego apriételo con las restricciones que solo usted conoce.
Construí esta herramienta para Toolz.dev porque seguí haciendo lo mismo a mano: abrir un cuerpo de respuesta, entrecerrar los ojos y transcribir su forma en un esquema cláusula por cláusula. Es repetitivo, y la transcripción repetitiva es donde se esconden los errores. Esta guía explica qué hace el generador, dónde la inferencia es confiable, dónde necesita su juicio y cómo un esquema generado encaja en un flujo de trabajo de validación real.
¿qué es un esquema JSON y por qué generar uno a partir de datos?
JSON Schema es un vocabulario para describir la estructura de JSON, mantenido como una especificación por derecho propio más que como una convención. Un esquema es en sí mismo un documento JSON que declara el tipo esperado de cada campo, qué campos se requieren, qué forma toman los objetos y matrices anidados y, con palabras clave como pattern, enum, minimumy format - qué valores están realmente permitidos. Los validadores en casi todos los idiomas leen un esquema y le dicen si un documento determinado cumple. Es lo más parecido que tiene el mundo JSON a un sistema de tipos que cruza los límites del servicio.
La razón para generar un esquema a partir de una muestra, en lugar de escribirlo desde cero, es que la mayor parte de un esquema es mecánico. Caminar sobre una carga útil y grabar " Esta es una cadena, este es un número entero, este objeto tiene estas claves" es exactamente el tipo de trabajo que debe hacer una máquina. Qué es no mecánica es la capa semántica: saber eso status puede que sólo sea una de cuatro cuerdas, eso age eso no puede ser negativo email debe coincidir con un patrón de dirección real. Generation maneja el andamio mecánico para que puedas dedicar tu atención a las limitaciones que importan. Comienzas desde un documento que ya coincide con la realidad y agregas reglas, en lugar de comenzar desde un archivo en blanco y esperar recordar cada campo.
También hay una dimensión de confianza. Cuando escribes un esquema a mano, codificas lo que haces creer el punto final regresa. Las creencias se alejan de la realidad: se agrega un campo, un número entero se vuelve anulable, un punto final que devolvió un solo objeto comienza a devolver una matriz. Un esquema generado a partir de una respuesta real está anclado a lo que el servicio realmente envió el día que lo capturó. Ese ancla vale mucho cuando estás depurando por qué la validación pasa en la puesta en escena y falla en la producción.
Cómo el generador infiere un esquema
El motor analiza su JSON y recorre el valor de forma recursiva, emitiendo un nodo de esquema para cada parte de la estructura. Las reglas son deliberadamente conservadoras, porque un esquema demasiado vago es inútil y un esquema demasiado estricto rechaza datos válidos.
Para escalares, distingue integer de number - 42 se convierte en integer, 4.2 se convierte en number - porque esa distinción es significativa para los validadores y para cualquiera que lea el esquema. Booleanos y null mapear a sus propios tipos. Las cuerdas se convierten type: string, y si la detección de formato está activada, el motor comprueba el valor con un conjunto de patrones conocidos y lo etiqueta: date-time, date, time, email, uri, uuidy ipv4.
Para los objetos, registra cada clave, infiere un esquema para cada valor y - si required la inferencia está habilitada: marca una clave requerida cuando está presente en cada objeto en esa posición. Para un solo objeto eso significa todas las claves; el caso interesante son las matrices.
Para matrices de objetos, el generador hace algo más útil que un paseo ingenuo. En lugar de emitir un esquema separado para cada elemento o un extenso anyOf de formas casi idénticas, fusiona todos los objetos de la matriz en uno items esquema que describe un solo elemento. Se requiere una clave presente en cada elemento; una clave presente sólo en algunos elementos queda opcional. Esto refleja cómo se comportan las colecciones API reales: una lista paginada donde la mayoría de los registros contienen un avatarUrl pero algunos no. El esquema fusionado captura " Estos campos siempre aparecen, estos a veces aparecen " en una definición legible. Puedes ver esto en la muestra incorporada, donde members la matriz tiene dos objetos, uno con un active campo y uno sin - y las marcas del esquema del elemento generado id y role requerido pero se va active opcional.
Para conjuntos de escalares mixtos, el motor colapsa los tipos de elementos en uno solo type matriz - ["integer", "string", "boolean"] - en lugar de una unión detallada. Cuando las formas de objetos y no objetos se mezclan genuinamente en una matriz, vuelve a caer anyOf, que es la construcción correcta del esquema JSON para "una de estas alternativas."
Cómo utilizar el generador de esquemas JSON
Paso 1: Pegue una muestra representativa
Introduzca una respuesta API, un dispositivo, un archivo de configuración o un cuerpo de webhook. Lo más importante que puede hacer para lograr precisión es pegar un representante muestra. Si tiene varios registros de una respuesta real, inclúyalos todos dentro de una matriz; el generador los fusionará e inferirá la opcionalidad correctamente. Una muestra de un solo registro le dice al motor que cada campo que ve siempre está presente, lo que a menudo es incorrecto. Primero cargue la muestra incorporada para ver cómo se manejan los objetos anidados, las matrices de objetos y las cadenas formateadas antes de pegar los suyos propios.
Paso 2: elige el dialecto
Elija Draft-07 para obtener la compatibilidad más amplia entre bibliotecas de validación, o 2020-12 para la especificación actual. La herramienta escribe el correcto $schema identificador en la raíz para que su validador aplique las reglas correctas. Para las formas de objetos y matrices que produce este generador, la salida estructural es la misma en ambos dialectos; la diferencia visible es el identificador. Si no está seguro de qué son compatibles sus herramientas, Draft-07 es el valor predeterminado seguro: tiene el soporte de biblioteca más amplio de cualquier versión.
Paso 3: establece tus opciones
Agregar un title si desea que el esquema se autodocumente. Decide si emitir required - la mayoría de las veces lo desea, pero durante las primeras exploraciones puede preferir un esquema más flexible. Mantenga activada la detección de formato a menos que vea falsos positivos. Y active el modo estricto (additionalProperties: false) cuando el esquema protege algo que usted controla completamente, como un archivo de configuración o un cuerpo de solicitud, y desea que se rechacen claves inesperadas en lugar de ignorarlas.
Paso 4: generar, revisar y exportar
Presione Generar y luego lea la salida críticamente. Compruébalo required coincide con su intención, ese número entero versus número salió bien y que cualquier formato detectado es correcto en lugar de coincidencia. Cuando se vea bien, copie el esquema o descárguelo como .json archivo listo para colocar en su validador o repositorio.
Un ejemplo trabajado
Considere esta respuesta desde un punto de vista hipotético /projects punto final:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
El generador produce un esquema donde id es una cadena con format: "uuid", createdAt es una cadena con format: "date-time", score es un number (no es un número entero, debido al decimal), y members es una matriz cuyo items el esquema requiere id y role pero no active. Ese último detalle es la recompensa: de dos miembros de ejemplo se infirió correctamente active es opcional. Hacer ese razonamiento a mano a través de una gran carga útil es exactamente el tipo de trabajo cuidadoso y aburrido que elimina un generador.
Donde termina la inferencia y comienza tu juicio
Quiero ser directo acerca de los límites, porque un esquema generado entregado directamente a la producción es un error. La inferencia ve tipos y estructuras; no puede ver la intención.
No puede saber eso role es una enumeración de owner, editory viewer - de la muestra sólo lo sabe role es una cadena. No puede saber eso score oscila entre 0 y 5, eso name tiene una longitud máxima, o que un código que parece un UUID es en realidad un identificador opaco que debería seguir siendo una cadena simple. Infiere required por presencia, un campo opcional que aparece en su muestra se marcará como requerido hasta que lo corrija. Y funciona a partir de los datos que le proporciones: si tu muestra nunca incluye a null para un campo anulable, el esquema no sabrá que ese campo puede ser nulo.
El modelo mental correcto es el andamiaje. El generador construye el marco con precisión: cada campo, su tipo, el anidamiento, las formas de la matriz, la lista requerida basada en la presencia. Luego agrega las restricciones semánticas: enumeraciones, patrones, límites numéricos y cualquier formato que el motor no pueda ver a partir de un valor. Esto es más rápido y menos propenso a errores que partir de la nada, porque la tediosa transcripción estructural ya está hecha y es correcta.
Draft-07 versus 2020-12: ¿cuál deberías elegir?
| ponderación | Borrador-07 | 2020-12 |
|---|---|---|
| Soporte de biblioteca | Más amplio; apoyado en casi todas partes | Creciendo; revisa tu validador |
| Estado | Ampliamente desplegado, estable | Especificación actual |
$schema preciar |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| Palabras clave de elementos de matriz | items para esquemas de un solo elemento |
items / prefixItems dividir por tuplas |
| Mejor cuando | La máxima compatibilidad importa | Quiere las funciones de especificaciones más recientes |
Para los esquemas que genera esta herramienta (objetos, listas requeridas, matrices de una sola forma de elemento), ambos dialectos expresan la misma estructura. La decisión práctica se reduce a lo que admite su biblioteca de validación. Si está conectando el esquema a una pila establecida, haga coincidir la versión con los documentos de su validador. Si está empezando de nuevo y no tiene restricciones, Draft-07 sigue siendo la opción pragmática por su incomparable soporte ecosistémico.
Casos de uso comunes
Documentar una API existente. Cuando hereda un punto final sin esquema, generar uno a partir de una respuesta real le brinda un documento inicial preciso en segundos. Luego lo refinas en un contrato publicado. Esto se combina naturalmente con la generación de tipos para el código de su cliente: la misma muestra puede alimentar el JSON a mecanografiado herramienta para que su contrato de servidor y tipos de clientes provengan de la misma fuente de verdad.
Validación de organismos de solicitud. Para un cuerpo de solicitud que controle, genere un esquema a partir de un ejemplo válido, active el modo estricto para rechazar claves inesperadas y agregue las enumeraciones y límites que aplica su punto final. Ahora las solicitudes con formato incorrecto fallan en el borde con un error de validación claro en lugar de causar fallas confusas en lo profundo de su controlador.
Validación de archivos de configuración. Las aplicaciones que leen la configuración JSON se benefician enormemente de un esquema. Genere uno a partir de una configuración en buen estado, apriétela y valídela al iniciar, de modo que un error tipográfico en una clave de configuración falle en voz alta en lugar de desactivar silenciosamente una función.
Pruebas y accesorios. Un esquema también funciona como activo de prueba. Valide sus accesorios contra él en CI para que un dispositivo que se deforme quede atrapado antes de que produzca una prueba verde engañosa.
Pruebas de contrato entre servicios. Cuando dos servicios acuerdan una carga útil, un esquema compartido es el contrato. Generarlo a partir de un mensaje real y refinarlo les da a ambos equipos un documento con el que pueden validar de forma independiente.
Privacidad: por qué esto se ejecuta en su navegador
Las muestras de API son algunos de los textos más confidenciales que maneja un desarrollador. Habitualmente contienen tokens de acceso, identificadores de sesión, direcciones de correo electrónico, ID de registros internos y, ocasionalmente, datos personales que nunca deben pegarse en un formulario web aleatorio. Precisamente por eso el generador de esquemas JSON hace todo su trabajo en el lado del cliente. El análisis, la inferencia y la serialización se realizan en JavaScript en su navegador. No se carga, registra ni almacena nada en un servidor. Puede verificar esto abriendo la pestaña de su red mientras genera o desconectándose de Internet; la herramienta aún funciona. Esto me importa porque no usaría una herramienta que enviara mis cargas útiles a otra persona & #39;s servidor, y tampoco se lo pediría. El mismo principio se aplica a todo Toolz.dev, que es el argumento que expongo detalladamente en el Privacidad de datos en herramientas en línea escribir.
Cómo se adapta al conjunto de herramientas JSON más amplio
Un esquema es un artefacto en un flujo de trabajo JSON más grande. Antes de generar un esquema, es útil tener una entrada limpia y válida: el Formateador JSON formateará y validará una carga útil para que no introduzca texto con formato incorrecto en el generador. Después de tener un esquema, a menudo desea tipos para el código de su aplicación, que es donde JSON a mecanografiado entra. Y si su canalización se mueve entre formatos, el JSON a YAM converter maneja la conversión que muchos sistemas de configuración y CI esperan. He escrito sobre cómo se conectan estas piezas en el Guía definitiva de las herramientas JSON, y sobre montar un kit más amplio en el Kit de herramientas para desarrolladores web descripción general. El objetivo de un kit de herramientas conectado es que una sola muestra pueda fluir a través de varias herramientas (esquema, tipos, conversión de formato) sin tener que abandonar su navegador.
preguntasrán el
¿Cómo genero un esquema JSON desde JSON?
Pegue su JSON en el editor, elija Draft-07 o 2020-12 y presione Generar. La herramienta infiere el tipo de cada campo, extrae las claves requeridas y genera un esquema que puede copiar directamente en un validador. No se carga nada: la inferencia se ejecuta completamente en su navegador.
¿Cuál es la diferencia entre Draft-07 y 2020-12?
Son dos versiones de la especificación del esquema JSON. Draft-07 tiene el soporte más amplio en todas las bibliotecas y es un valor predeterminado seguro. 2020-12 es la versión actual y cambia la forma en que se expresan las matrices y subesquemas, entre otras cosas. Para las formas de objetos y matrices, esta herramienta produce la estructura que es la misma; la principal diferencia visible es la $schema identificador.
¿Cómo decide la herramienta qué campos se requieren?
Se marca una clave requerida cuando aparece en cada objeto que ve el generador. Para un solo objeto que significa cada clave; para una matriz de objetos significa claves presentes en todos los elementos. Las claves que aparecen en algunos registros se quedan fuera de Obligatorio, reflejando cómo las API omiten campos opcionales. Puede desactivar por completo la detección de campo obligatorio.
¿Qué sucede con una matriz de objetos?
Los objetos se fusionan en uno items esquema que describe un solo elemento y la propiedad se escribe como una matriz del mismo. Se requieren claves presentes en cada elemento; las claves presentes en sólo algunos permanecen opcionales. Esto mantiene el esquema legible en lugar de producir un gran anyOf de formas casi idénticas.
¿Qué formatos de cadena detecta?
Reconoce date-time, date, time, email, uri, uuidy ipv4 cuerdas y agrega la coincidencia format palabra clave. La detección es el mejor esfuerzo de una sola muestra, así que revise los resultados: un código que parezca un UUID se etiquetará como tal. Puede desactivar la detección de formato si prefiere tipos de cadenas simples.
¿Puedo generar un esquema a partir de una sola muestra?
Sí, pero una muestra sólo muestra una forma posible. Un campo que es un número en su muestra puede ser nulo o una cadena en otro lugar, y se requerirá un campo opcional que esté presente. Cuanto más representativa sea la muestra (idealmente varios registros reales), más precisos serán los tipos inferidos y la lista requerida.
¿Está listo un esquema generado para la validación de la producción?
Trátelo como un punto de partida sólido en lugar de un documento terminado. La inferencia captura tipos, estructuras y campos obligatorios con precisión, pero las restricciones semánticas (súmbulos, patrones de cadenas, mínimos y máximos numéricos, formatos que no puede ver en un valor) aún deben agregarse a mano. La generación elimina el tedioso andamiaje para que puedas concentrarte en esas reglas.
¿Mi json está cargado en un servidor?
No. Todo el motor de inferencia se ejecuta como JavaScript en su navegador. No se transmite, registra ni almacena nada. Puede confirmar esto observando la pestaña de su red mientras genera o desconectándose de Internet; la herramienta aún funciona.
