Validador JSON Schema

¿Qué es un Validador JSON Schema?

// A 5-line schema that catches three real bugs
const schema = {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
};

// Three bugs the schema catches:
const bad = { "id": "42", "age": 200 };
//   /id   → type: expected integer, got string
//   /email → required: missing
//   /age   → maximum: 200 > 150

// In Node:        new Ajv().compile(schema)(bad)  // false; ajv.errors has the paths
// In Python:      jsonschema.validate(bad, schema)
// In the browser: this tool — same errors, same paths, no install

Características principales

Ejemplos

{
  "id": 42,
  "email": "alice@example.com",
  "age": 30
}

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

{
  "id": "42",
  "age": 200
}

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "maximum": 150 }
  },
  "required": ["id", "email"]
}

{
  "type": "order.created",
  "data": { "orderId": "ORD-001234", "totalUsd": 49.99 }
}

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "order.created" },
        "data": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
            "totalUsd": { "type": "number", "minimum": 0 }
          },
          "required": ["orderId", "totalUsd"]
        }
      },
      "required": ["type", "data"]
    },
    {
      "properties": {
        "type": { "const": "order.refunded" },
        "data": { "type": "object", "required": ["refundId"] }
      },
      "required": ["type", "data"]
    }
  ]
}

[
  { "sku": "A1", "qty": 3 },
  { "sku": "B2", "qty": 5 },
  { "sku": "A1", "qty": 3 }
]

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "pattern": "^[A-Z][0-9]+$" },
      "qty": { "type": "integer", "minimum": 1 }
    },
    "required": ["sku", "qty"]
  }
}

Cómo usar

1. 1

   Pega tu JSON Schema

   Coloca tu esquema en el panel derecho. El validador autodetecta el draft a partir del URI $schema si está presente; en caso contrario, elige Draft 2020-12, 2019-09 o Draft-07 en la barra de herramientas.

2. 2

   Pega tus datos JSON

   Coloca el documento JSON que quieres comprobar en el panel izquierdo. La validación se ejecuta mientras escribes; las entradas grandes (>200 KB) cambian a un botón manual de Validate para que la escritura siga ágil.

3. 3

   Lee la lista de errores

   Cada error tiene una ruta JSON Pointer, una keyword y un mensaje de una línea. Haz clic en un error para saltar a la ubicación en tus datos, corrígelo y observa cómo el contador baja en tiempo real.

Errores comunes en JSON Schema

{ "qty": 1.0 }   schema: { "type": "integer" }   → error: not an integer

{ "qty": 1 }     schema: { "type": "integer" }   → valid

{ "properties": { "name": { "type": "string", "required": true } } }

{ "properties": { "name": { "type": "string" } }, "required": ["name"] }

{ "properties": { "id": { "type": "integer" } } }   accepts: { "id": 1, "foo": "bar", "x": null }

{ "properties": { "id": { "type": "integer" } }, "additionalProperties": false }

{ "type": "string", "nullable": true }   in 2020-12: nullable is just an unknown keyword

{ "type": ["string", "null"] }   in 2020-12: explicitly allows null

pattern: "[A-Z]+"   accepts: "helloX"   (because X matches)

pattern: "^[A-Z]+$"   accepts only: "HELLO"

oneOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → error: matches both

anyOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → valid

Casos de uso comunes

Validación de petición de API

Pega un cuerpo de petición y el esquema de tu endpoint antes de desplegar. Atrapa respuestas 400 que tus tests no cubrieron — campos requeridos faltantes, tipos incorrectos, números fuera de rango.

Verificación de payload de webhook

¿El proveedor envió un payload que tu manejador rechaza? Valida el payload real contra tu esquema y luego contra el esquema publicado del proveedor. La diferencia entre ambos es tu bug.

Linting de archivos de configuración

package.json, tsconfig.json, helm values.yaml — todo archivo de configuración tiene un esquema público. Pega el esquema, pega la configuración, encuentra el typo. Olvídate del prueba y error.

Pruebas de componentes OpenAPI

Extrae un componente de esquema de un documento OpenAPI 3.1, pégalo aquí y valida payloads de muestra. Más rápido que levantar un servidor mock, determinista, sin SDK.

Pre-vuelo de envío de formulario

Pega un payload de formulario de muestra antes de cablear la validación del frontend. Confirma que el esquema rechaza lo que esperas y acepta lo que esperas, y luego envía el mismo esquema a cliente y servidor.

Verificación de contrato de pipeline de datos

¿La salida ETL ha derivado? Pega una fila de muestra y el esquema posterior. Identifica qué productor cambió y qué claves se rompieron antes de que el pipeline reintente 10.000 registros.

Detalles técnicos

Conforme con Draft 2020-12

Implementa la especificación publicada de Draft 2020-12 — keywords, sistema de tipos, vocabulario format. Comprobado contra la salida de Ajv 8.x y ajv-formats.

Rutas de error con JSON Pointer

Los errores usan JSON Pointer RFC 6901 (/user/email/0). Cada fallo de keyword apunta a una ubicación resoluble única en los datos — sin ambigüedad, sin búsqueda por cadena.

Resolución interna de $ref

Resuelve punteros $ref dentro de un único documento (#/$defs/foo, #/properties/bar). Detecta y reporta ciclos. Los $ref HTTP externos están desactivados por privacidad.

Buenas prácticas

Activa siempre additionalProperties: false

En contratos de entrada (cuerpos de petición, archivos de configuración, mensajes de cola), las claves desconocidas suelen ser bugs — typos, campos accidentales o sondeos de atacantes. Recházalas por defecto.

Usa $defs para subesquemas reutilizables

Si copias la misma forma dos veces, divergirán. Mueve las definiciones compartidas a $defs y referéncialas con $ref — una sola fuente de verdad, todo cambio se aplica en todas partes.

Valida antes de la lógica de negocio

Ejecuta la validación de esquema justo después de JSON.parse, antes de tocar la estructura parseada. El estrechamiento de tipos, los valores por defecto y la persistencia asumen que el contrato se cumple — asegúrate de que así sea.

Preguntas frecuentes