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

PublicadoHerramientaGenerador de JSON Schema

Contenido
  1. Si alguna vez has escrito a mano un esquema a partir de una sola respuesta de API
  2. Cómo escribir a mano un esquema Draft-07 sin herramientas
  3. Puntos que suelen generar confusión al leer el resultado
  4. Conclusión
  5. Preguntas frecuentes

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]
}
  1. Como el valor de nivel superior es un objeto, el esquema superior empieza con "type": "object" y dentro de properties se escribe cada clave una por una.
  2. id es un número sin comillas, así que es number; zipCode está entre comillas, así que es string. Que el valor lleve comillas o no es el único criterio.
  3. Si el valor es a su vez otro objeto, como address, dentro de él se repiten igualmente type: object y properties.
  4. Si todos los elementos de un array son del mismo tipo, como en tags, se toma uno de ellos como representante y en items se escribe solo ese tipo. Si los tipos de los elementos están mezclados, como en history, se coloca anyOf dentro de items y se enumera un esquema por cada tipo que aparezca.
  5. 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.
  6. Arriba del todo se escribe "$schema": "http://json-schema.org/draft-07/schema#" y, si hace falta, se añade title para 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.

Generador de JSON Schema

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 frecuenteComportamiento real
Un valor formado solo por dígitos, como "06236", se detecta como numberSi está entre comillas, el tipo es siempre string
Los enteros se distinguen como integer y los decimales como numberSe basa en typeof, así que siempre es number sin distinguir enteros de decimales
La casilla de required selecciona y guarda solo los campos necesariosAl marcarla, todas las claves de ese objeto entran en required sin excepción
Si el array tiene varios elementos, se examinan todos y se combinanSi los tipos son iguales, se construye items mirando solo el primer elemento
El esquema generado garantiza todas las formas de datos posiblesEs 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.
Generador de JSON Schema

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

Artículos relacionados

  1. Error de sintaxis JSON: lee el mensaje y encuentra la causaQué indica la posición en un error de JSON y cómo reconocer los fallos más comunes: coma final, comillas simples, comentarios y claves sin comillas.
  2. JSON a TypeScript: cuándo aparecen ? y | en las interfacesCómo decide la conversión de JSON a TypeScript cuándo una clave lleva ? opcional y cuándo sus valores se unen con |, con ejemplos reales.
  3. Convertir JSON a YAML: reglas de listas e indentaciónDescubre cómo los arrays de JSON pasan a listas con guion y los objetos anidados a niveles de indentación, y evita errores de comillas en Kubernetes.
  4. Sintaxis JSONPath: qué selecciona cada símbolo con ejemplosRepasa qué selecciona cada símbolo de JSONPath ($, ., [n], [*], ..) con un JSON de ejemplo y por qué los filtros y slices no están soportados.
  5. Cómo decodificar un JWT: estructura y fecha de expUn JWT no está cifrado, solo codificado: aprende a leer el header y el payload, y a convertir exp e iat en fechas legibles.
  6. Verificar un JWT: cómo comprobar si la firma fue alteradaDescubre cómo se calcula y compara la firma HMAC-SHA256 de un JWT y por qué falla la verificación: clave distinta o token manipulado.

Herramientas relacionadas