Blog de SchemaSafe
Errores comunes al crear esquemas JSON
JSON Schema, actualmente Draft 2020-12, es la forma estándar de describir y validar la forma de JSON. La mayoría de los esquemas rotos no son errores de sintaxis; son errores permisivos que permiten datos inválidos. Los cuatro que más aparecen en la revisión de código son un arreglo requerido que falta, una propiedad adicional abierta, uniones de tipo mal utilizadas y un $ref que apunta a nowhere.
Olvidando el array requerido
Cuando agregas una propiedad bajo properties, solo estás describiendo su forma, no exigiendo su presencia. Si el array requerido omite esa clave, una instancia sin el campo se valida con éxito. Esto es un paso silencioso porque el validador trata la propiedad como opcional. He visto equipos que envían API donde un identificador crítico faltaba en required, lo que llevó a errores de null-pointer downstream que solo aparecieron en producción.
Por ejemplo, un esquema de usuario que espera un id debe contener:
{ "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id"] } Sin la línea requerida, un objeto con solo {"name":"Ada"} pasaría, aunque la API posteriormente trata id como obligatorio.
Dejar additionalProperties abierto
El valor predeterminado de additionalProperties es true. Esto permite que cualquier clave no definida en properties pase la validación. Un error tipográfico como "user_name" en lugar de "username" se convierte entonces en un campo aceptado silenciosamente, contaminando el modelo de datos y dificultando las migraciones posteriores. He visto a equipos pasar semanas limpiando claves errantes que entraron en la base de datos porque el esquema nunca las rechazó.
Aquí está una versión estricta del esquema de producto:
{ "type": "object", "properties": { "sku": { "type": "string" }, "price": { "type": "number", "minimum": 0 } }, "required": ["sku","price"], "additionalProperties": false } Con este esquema, una instancia que contiene {"sku":"ABC","price":10,"extra":1} falla la validación, detectando el error tipográfico temprano.
Abuso de uniones de tipos
La palabra clave de tipo espera una cadena o una matriz de cadenas. Escribir "type": "string, number" es un esquema JSON inválido; el analizador trata el valor completo como un solo tipo desconocido, que muchos validadores ignoran silenciosamente, lo que permite que cualquier valor pase. Otro error común es omitir el tipo por completo para un campo opcional, lo que hace que el validador omita la comprobación de tipo para esa clave.
Ejemplo de un campo de fecha nulo:
{ "type": "object", "properties": { "issuedAt": { "type": ["string","null"], "format": "date-time" } }, "required": ["issuedAt"] } Aquí se permite null, por lo que {"issuedAt":null} pasa, mientras que {"issuedAt":"not-a-date"} falla.
Trampas de $ref y deriva de versión
Un $ref que se resuelve en una ubicación que falta hace que todo el esquema falle al cargar, lo que es ruidoso y fácil de detectar. El problema más silencioso es una referencia que se resuelve pero apunta a la definición incorrecta porque la versión de borrador cambió o la estructura de carpetas se desplazó. En el borrador 2020-12, la palabra clave para bloques reutilizables se movió de definiciones a $defs. Si mantienes la antigua clave, el esquema todavía se valida (la palabra clave más antigua se ignora) pero pierdes la capacidad de reutilizar definiciones, lo que lleva a código duplicado y deriva.
Ejemplo de una referencia correcta:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" } }, "required": ["street","city"] } }, "type": "object", "properties": { "billing": { "$ref": "#/$defs/address" }, "shipping": { "$ref": "#/$defs/address" } }, "required": ["billing","shipping"] } Si accidentalmente escribiste "$ref": "#/definitions/address" la referencia se resolvería a indefinido y el validador lanzaría un error, alertándote sobre la discrepancia.
Validar con muestras antes de publicar
La verificación de confianza más barata es ejecutar un puñado de instancias JSON representativas a través del validador antes de tratar el esquema como un contrato. Un buen conjunto de pruebas contiene al menos un ejemplo válido que coincide con el uso previsto y un ejemplo inválido que deliberadamente rompe cada regla que te importa. Si el esquema acepta la buena muestra y rechaza la mala, tienes evidencia de que no es excesivamente permisivo. He visto equipos saltarse este paso y descubrir más tarde que un requisito faltante permitió que los pedidos sin IDs de producto se filtraran, causando errores de cumplimiento.
const Ajv = require('ajv'); const ajv = new Ajv({allErrors: true}); const schema = require('./user-schema.json'); const good = { "id": "123", "name": "Ada" }; const bad = { "name": "Ada" }; // missing id const validate = ajv.compile(schema); console.log('Muestra buena:', validate(good) ? 'pass' : 'fail'); if (!validate(good)) console.error(validate.errors); console.log('Muestra mala:', validate(bad) ? 'pass' : 'fail'); if (validate(bad)) console.error('Muestra mala aceptada inesperadamente'); Ejecutar esto en CI garantiza que un error permisivo nunca llegue a producción.
Qué no es esto
Esta guía no promete que seguir estos puntos hará que su esquema sea inmune a todos los errores posibles. JSON Schema es un lenguaje flexible, y nuevos obstáculos pueden aparecer a medida que lo extienda con palabras clave personalizadas o lo combine con otras herramientas como OpenAPI. No estoy afirmando que los cuatro errores enumerados sean los únicos que importan; son simplemente los que aparecen con más frecuencia en las revisiones de código que he visto. El consejo aquí se basa en mi experiencia manteniendo SchemaSafe y en especificaciones públicamente disponibles; no es un sustituto de leer la especificación oficial o de ejecutar sus propias pruebas de validación.
Referencias
https://ajv.js.org/json-schema.html
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
https://json-schema.org
https://json-schema.org/draft/2020-12/json-schema-core.html
Preguntas frecuentes
Declarar una propiedad en properties no la hace obligatoria. Debe enumerarla en la matriz requerida. La matriz es un hermano de properties, no anidado dentro de ella.
Por defecto es true, por lo que las claves desconocidas pasan. Establezca additionalProperties: false donde la rigidez es importante, o restrínjala con un esquema para campos de extensión. Los esquemas abiertos permiten que los errores de escritura pasen silenciosamente.
Omítala de requerida e incluya "null" en su matriz de tipo, por ejemplo ["string", "null"] . Escribir una cadena de tipo separada por comas es inválida y puede anular la restricción.
Bajo $defs . La clave de definiciones más antigua todavía funciona, pero marca un borrador antiguo. Siempre fije $schema para que el validador aplique el borrador que pretendía.
Pruebe el producto: SchemaSafe
2026-09-16 · solo fuentes primarias · no hay métricas de tráfico fabricadas
Artículos relacionados
Validación de esquema JSON sin LLM (2026)
Explorar la matriz completa de temas de micro-SaaS de IA →
¿Por qué mi esquema acepta campos que faltan?
Declarar una propiedad en properties no la hace obligatoria. Debes enumerarla en la matriz required . La matriz es un hermano de properties , no anidado dentro de ella.
¿Qué hace additionalProperties por defecto?
Por defecto es true, por lo que las claves desconocidas pasan. Establezca additionalProperties: false donde sea importante la rigidez, o restrínjala con un esquema para campos de extensión. Los esquemas abiertos permiten que los errores de escritura pasen silenciosamente.
¿Cómo marco un campo como opcional en JSON Schema?
Omítalo de required e incluya \
¿Dónde van las definiciones reutilizables en Draft 2020-12?
Debajo de $defs . La clave definitions más antigua todavía funciona, pero marca un borrador antiguo. Siempre fije $schema para que el validador aplique el borrador que pretendía.
Solo para apoyo a la toma de decisiones. No sustituye una revisión formal de esquemas o auditorías certificadas.