Validacion de JSON Schema: Guia Completa para Definir y Validar Datos JSON

Que es JSON Schema?

JSON Schema es un lenguaje declarativo que te permite describir la estructura, contenido y restricciones de un documento JSON. Piensa en el como un contrato entre un productor y un consumidor de datos. El productor dice "siempre enviare un objeto con un string name y un entero age", y el consumidor puede verificar que cada payload entrante realmente cumple esa promesa antes de procesarlo.

Esto importa porque JSON en si mismo no tiene esquema. Cualquier valor JSON valido -- un string, un numero, un objeto profundamente anidado con claves aleatorias -- es perfectamente legal. Esa libertad es maravillosa para prototipar rapido, pero se convierte en una carga el momento en que dos sistemas necesitan ponerse de acuerdo sobre como deben verse los datos.

Por que JSON Schema Importa para las APIs

Las APIs REST se comunican a traves de payloads JSON, y cada endpoint tiene una forma implicita: campos obligatorios, tipos esperados, restricciones de valor. JSON Schema hace esa forma explicita y legible por maquinas. Una vez que tienes un esquema, puedes:

• Validar solicitudes en el servidor antes de que lleguen a tu logica de negocio, retornando errores 400 claros en lugar de 500 cripticos.
• Validar respuestas en pruebas de integracion para capturar cambios que rompen antes de que lleguen a produccion.
• Generar documentacion automaticamente -- herramientas como Swagger/OpenAPI usan JSON Schema como columna vertebral de sus definiciones de tipos.
• Generar codigo -- herramientas de esquema a TypeScript, esquema a Go struct y esquema a Python dataclass eliminan definiciones de tipos manuales.

Fundamentos de JSON Schema

Cada JSON Schema es en si mismo un objeto JSON. El esquema mas simple posible es un objeto vacio {}, que acepta cualquier JSON valido. Desde ahi, agregas palabras clave para estrechar lo que esta permitido.

Tipos Primitivos

La palabra clave type es el fundamento. JSON Schema reconoce seis tipos primitivos mas un modificador estructural:

Propiedades y Campos Obligatorios

Para objetos, la palabra clave properties define que claves se esperan y como debe verse cada una. La palabra clave required lista cuales de esas claves deben estar presentes.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name", "email"]
}

Este esquema dice: los datos deben ser un objeto; debe tener un string name no vacio y un string email valido; age es opcional pero si esta presente debe ser un entero no negativo.

Controlando Propiedades Adicionales

Por defecto, los objetos aceptan cualquier clave extra mas alla de lo que properties define. Configurar "additionalProperties": false hace el esquema estricto. Esto es valioso para APIs donde campos inesperados pueden indicar un error del cliente o una incompatibilidad de version.

Validacion de Formato

La palabra clave format proporciona validacion semantica mas alla de los tipos basicos. Un campo puede ser un string, pero no cualquier string -- debe ser una direccion de email, una fecha, un URI o una direccion IP.

Formatos Incorporados

Formato como Anotacion vs. Asercion

Un matiz importante: por defecto, la palabra clave format es una anotacion, no una asercion. En Draft 2020-12, debes habilitar explicitamente la asercion de formato si quieres que la validacion falle con formatos invalidos.

Versiones de Borrador: Draft-07 vs 2020-12

JSON Schema ha evolucionado a traves de varias versiones de borrador. Las dos que encontraras con mas frecuencia son Draft-07 (publicado en 2018) y Draft 2020-12 (la version estable actual).

Diferencias Clave

Cual Version Elegir?

Elige Draft-07 si tu ecosistema ya lo usa o si necesitas maxima compatibilidad con herramientas existentes.

Elige Draft 2020-12 si empiezas un nuevo proyecto sin restricciones heredadas o si necesitas unevaluatedProperties para composicion limpia de esquemas.

Como Usar Nuestro Generador de JSON Schema

Nuestro Generador de JSON Schema gratuito toma cualquier payload JSON y produce un esquema valido automaticamente. Todo se ejecuta en tu navegador, asi que tus datos nunca salen de tu dispositivo.

Guia Paso a Paso

1. Abre la herramienta Generador de JSON Schema.
2. Pega tu JSON en el area de entrada.
3. Haz clic en Generar y la herramienta analizara cada campo, inferira tipos, detectara formatos y identificara propiedades obligatorias.
4. Revisa la salida -- el esquema generado aparece en el panel de salida.
5. Cambia a la pestana Validar para probar tu esquema contra nuevos payloads JSON.
6. Copia el esquema con un clic e integralo en tu proyecto.