JSON Schema: validación y definición de datos

1) ¿Qué es JSON Schema?

JSON Schema es un estándar para describir, validar y documentar la estructura de un documento JSON.

Permite definir qué campos existen, qué tipo de datos tienen y qué restricciones deben cumplir. Es equivalente a un “contrato” entre quien envía y quien recibe el JSON.

Sirve para validar automáticamente datos en APIs REST, formularios web o bases de datos NoSQL.

2) Ejemplo simple

JSON a validar

{
  "nombre": "Ana",
  "edad": 28,
  "activo": true
}

JSON Schema correspondiente

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "nombre": { "type": "string" },
    "edad": { "type": "integer", "minimum": 0 },
    "activo": { "type": "boolean" }
  },
  "required": ["nombre", "edad"]
}

3) Elementos básicos de JSON Schema

• type — Define el tipo (string, number, integer, boolean, null, object, array).
• properties — Define las claves de un objeto y sus restricciones.
• required — Lista de campos obligatorios.
• items — Estructura de los elementos de un array.
• minimum, maximum, minLength, maxLength — Restricciones numéricas y de texto.
• enum — Lista de valores permitidos.
• pattern — Validación con expresiones regulares para strings.

4) Ejemplo con validaciones

JSON a validar

{
  "email": "user@example.com",
  "rol": "admin",
  "edad": 25
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "rol": { "type": "string", "enum": ["admin", "editor", "usuario"] },
    "edad": { "type": "integer", "minimum": 18, "maximum": 99 }
  },
  "required": ["email", "rol"]
}

5) Validar arrays

JSON a validar

{
  "tags": ["tecnología", "json", "api"]
}

JSON Schema

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "uniqueItems": true
    }
  }
}

6) Objetos anidados

JSON a validar

{
  "usuario": {
    "nombre": "María",
    "direccion": {
      "calle": "San Martín",
      "numero": 123,
      "ciudad": "Córdoba"
    }
  }
}

JSON Schema

{
  "type": "object",
  "properties": {
    "usuario": {
      "type": "object",
      "properties": {
        "nombre": { "type": "string" },
        "direccion": {
          "type": "object",
          "properties": {
            "calle": { "type": "string" },
            "numero": { "type": "integer" },
            "ciudad": { "type": "string" }
          },
          "required": ["calle", "numero"]
        }
      },
      "required": ["nombre", "direccion"]
    }
  }
}

7) Ejemplo avanzado: catálogo de productos

JSON válido

{
  "tienda": "Tech Store",
  "productos": [
    {
      "codigo": 101,
      "descripcion": "Teclado",
      "precio": 1200.50,
      "disponible": true,
      "categorias": ["periféricos", "ofertas"]
    }
  ]
}

JSON Schema

{
  "type": "object",
  "properties": {
    "tienda": { "type": "string" },
    "productos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "codigo": { "type": "integer" },
          "descripcion": { "type": "string", "minLength": 3 },
          "precio": { "type": "number", "minimum": 0 },
          "disponible": { "type": "boolean" },
          "categorias": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["codigo", "descripcion", "precio"]
      }
    }
  },
  "required": ["tienda", "productos"]
}

8) Validación en distintos lenguajes

Python (con jsonschema)

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "nombre": {"type": "string"},
        "edad": {"type": "integer", "minimum": 0}
    },
    "required": ["nombre", "edad"]
}

data = {"nombre": "Ana", "edad": 25}

try:
    validate(instance=data, schema=schema)
    print("JSON válido")
except ValidationError as e:
    print("Error:", e.message)

Lib: jsonschema.

JavaScript (con ajv)

import Ajv from "ajv";
const ajv = new Ajv();

const schema = {
  type: "object",
  properties: {
    nombre: { type: "string" },
    edad: { type: "integer", minimum: 0 }
  },
  required: ["nombre", "edad"]
};

const validate = ajv.compile(schema);
const valid = validate({ nombre: "Ana", edad: 25 });

console.log(valid ? "JSON válido" : "Error", validate.errors);

Lib: AJV.

9) Usos prácticos de JSON Schema

• Validación de entradas en APIs REST — asegurar que el cliente envía datos correctos.
• Documentación — describe qué estructura se espera en cada endpoint.
• Generación automática de formularios (ej.: React JSON Schema Form).
• Contratos entre microservicios — asegura que todos usan el mismo formato.
• Testing — validar que las respuestas de una API cumplen con lo especificado.

Resumen

• JSON Schema define reglas sobre qué estructura debe tener un JSON.
• Permite especificar tipos, obligatorios, rangos, enums, arrays y objetos anidados.
• Existen librerías en casi todos los lenguajes (Python: jsonschema, JS: AJV, Java: Everit, Go: gojsonschema).
• Es fundamental para APIs modernas, microservicios y validación de datos.