Crear un JSON Schema: reglas de detección de tipos

Contenido
Cuando pegas datos JSON y al instante se genera un JSON Schema en formato Draft-07, es porque la herramienta recorre cada valor de forma recursiva y determina el tipo automáticamente.
Este artículo está pensado para desarrolladores que tienen a mano un ejemplo de respuesta de API o un archivo de configuración y necesitan crear reglas de validación con urgencia, y también para quienes se preguntan qué significan exactamente campos como required o anyOf que aparecen en el resultado.
Aquí solo se explican las reglas de determinación de tipos y cómo leer el resultado; no se abordan decisiones como qué diseño de esquema conviene.
Resumen ① El tipo de un valor se determina automáticamente en el orden null → array → object/string/number/boolean, y un número entre comillas se trata siempre como string. ② Si todos los elementos de un array son del mismo tipo, basta con mirar el primer elemento para construir items; si los tipos están mezclados, se enumeran ejemplos por tipo con anyOf. ③ Si marcas "Establecer todas las propiedades como obligatorias", todas las claves de ese objeto entran tal cual en required, y el esquema en sí no es más que una estimación derivada de un único ejemplo de entrada.
Si alguna vez has escrito a mano un esquema a partir de una sola respuesta de API
Imagina que lo único que tienes es un ejemplo de respuesta JSON que llegó del backend. A partir de ese ejemplo tienes que crear el JSON Schema que irás a usar en el código de validación del frontend o en la documentación de la API.
El problema empieza cuando los campos pasan de diez a veinte. Al trasladar a mano objetos y arrays anidados, y valores mezclados con null, es fácil olvidar un corchete o una coma.
En particular, la sintaxis de anyOf cuando dentro de un array hay tipos mezclados, o el criterio para decidir qué campos incluir en required, son puntos que generan dudas una y otra vez.
Cómo escribir a mano un esquema Draft-07 sin herramientas
Un JSON Schema Draft-07 se compone de unas cuantas combinaciones de palabras clave. La regla para trasladar un valor a un esquema es la siguiente.
- String →
{ "type": "string" } - Número (sin distinguir entre entero y decimal) →
{ "type": "number" } - Verdadero/falso →
{ "type": "boolean" } - null →
{ "type": "null" } - Objeto →
{ "type": "object", "properties": { ... } } - Array →
{ "type": "array", "items": { ... } }
Aplicando las reglas al JSON de ejemplo
Vamos a trasladar estas reglas tal cual al JSON de ejemplo.
{
"id": 1024,
"zipCode": "06236",
"name": "홍길동",
"isActive": true,
"note": null,
"address": { "city": "서울", "district": "강남구" },
"tags": ["vip", "return"],
"history": [1, "pending", true]
}
- Como el valor de nivel superior es un objeto, el esquema superior empieza con
"type": "object"y dentro depropertiesse escribe cada clave una por una. ides un número sin comillas, así que es number;zipCodeestá entre comillas, así que es string. Que el valor lleve comillas o no es el único criterio.- Si el valor es a su vez otro objeto, como
address, dentro de él se repiten igualmentetype: objectyproperties. - Si todos los elementos de un array son del mismo tipo, como en
tags, se toma uno de ellos como representante y enitemsse escribe solo ese tipo. Si los tipos de los elementos están mezclados, como enhistory, se colocaanyOfdentro deitemsy se enumera un esquema por cada tipo que aparezca. - Las claves que en estos datos deben existir siempre las decide una persona y las escribe en el array
required. Esta decisión solo puede tomarla con precisión quien conoce todos los datos reales, no un único ejemplo. - Arriba del todo se escribe
"$schema": "http://json-schema.org/draft-07/schema#"y, si hace falta, se añadetitlepara terminar.
Si lo trasladas a mano de esta forma, el resultado es el siguiente.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": { "type": "number" },
"zipCode": { "type": "string" },
"name": { "type": "string" },
"isActive": { "type": "boolean" },
"note": { "type": "null" },
"address": {
"type": "object",
"properties": {
"city": { "type": "string" },
"district": { "type": "string" }
}
},
"tags": { "type": "array", "items": { "type": "string" } },
"history": {
"type": "array",
"items": {
"anyOf": [
{ "type": "number" },
{ "type": "string" },
{ "type": "boolean" }
]
}
}
}
}
Si son pocos campos, basta con seguir este orden tal cual. El problema es que cuanto más aumentan los campos y más profundo es el anidamiento, más crece el trabajo de repetir a mano las mismas reglas de determinación.
Compruébalo con nuestra herramienta.
Pega tu JSON y la herramienta crea al instante un esquema Draft-07 en el navegador; los datos que introduces no se envían a ningún servidor.

Puntos que suelen generar confusión al leer el resultado
Hemos reunido los puntos que más malentendidos provocan al revisar visualmente el esquema generado.
| Error frecuente | Comportamiento real |
|---|---|
| Un valor formado solo por dígitos, como "06236", se detecta como number | Si está entre comillas, el tipo es siempre string |
| Los enteros se distinguen como integer y los decimales como number | Se basa en typeof, así que siempre es number sin distinguir enteros de decimales |
| La casilla de required selecciona y guarda solo los campos necesarios | Al marcarla, todas las claves de ese objeto entran en required sin excepción |
| Si el array tiene varios elementos, se examinan todos y se combinan | Si los tipos son iguales, se construye items mirando solo el primer elemento |
| El esquema generado garantiza todas las formas de datos posibles | Es solo el resultado de inferir a partir de un único ejemplo de entrada |
Cuando el array está formado por objetos, y algunas excepciones
Cuando todos los elementos de un array son objetos, esta regla se nota especialmente. Si se determina que todos los elementos son del tipo "object", items.properties se construye únicamente con la composición de claves del primer objeto.
Las claves que solo existen en el segundo objeto en adelante no aparecen en absoluto en el esquema. Si un campo que sí existe en los datos reales falta en el esquema generado, normalmente se debe a esta regla.
Si introduces un array vacío, items se rellena con {}, sin ninguna restricción. Es porque no hay ningún elemento y, por tanto, no hay base para determinar un tipo.
Si dejas vacío el campo de título (title), la clave title no se incluye en el esquema generado. Solo cuando rellenas el valor, title se añade justo debajo de $schema.
Conclusión
- El tipo de un valor se determina automáticamente en el orden null → array → object/string/number/boolean, y la presencia o ausencia de comillas es el único criterio que separa un string de un número.
- Los enteros y los decimales se muestran siempre como number, sin distinción.
- En un array, si todos los elementos son del mismo tipo, items se construye mirando solo el primer elemento; si los tipos están mezclados, se enumeran ejemplos por tipo con anyOf.
- required solo aparece cuando se activa la casilla, e incluye todas las claves de ese objeto sin excepción.
- El esquema generado es el resultado de inferir a partir de un único ejemplo de entrada, así que no garantiza campos ni combinaciones de tipos que no aparecían en ese ejemplo.
Pega tu JSON y la herramienta crea al instante un esquema Draft-07 en el navegador; los datos que introduces no se envían a ningún servidor.
Preguntas frecuentes
¿Cómo se representa en el esquema un valor formado solo por números, como un código postal?
El único criterio es si el valor va entre comillas. Si está entre comillas, como "06236", se interpreta como string y se genera { "type": "string" }.
Si lo escribes sin comillas, como 06236, no es un número JSON válido (un número que empieza por 0 es un error de sintaxis de JSON), así que se muestra un error en la fase de análisis.
¿Qué pasa si un array mezcla valores de distintos tipos?
Cuando los elementos de un array son de varios tipos, se toma un ejemplo de cada tipo, se crea un esquema para cada uno y se agrupan todos en un array anyOf dentro de items.
Por ejemplo, si en el array se mezclan números, strings y booleanos, dentro de anyOf aparecen tres esquemas de tipo uno al lado del otro.
¿Qué cambia exactamente la casilla «Marcar todas las propiedades como obligatorias»?
Al marcarla, en cada nodo de objeto se añaden a su array required todos los nombres de clave de ese objeto, tal cual.
No sirve para elegir solo algunas claves de forma selectiva, y si la desmarcas, ningún objeto incluye el array required.
¿Puedo validar todos los datos reales con un único esquema generado?
El esquema generado es el resultado de analizar un solo ejemplo de JSON pegado en el campo de entrada. En los datos reales, un mismo campo puede llegar con otro tipo, o pueden aparecer campos que no estaban en el ejemplo.
Por eso, el esquema no garantiza automáticamente todos los casos de tus datos reales. Si necesitas un esquema que cubra varias situaciones, puedes introducir por separado varios ejemplos representativos y comparar los resultados.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano