JSON Schema es una herramienta potente para definir la estructura, el formato y las restricciones de los datos en formato JSON. Permite automatizar la validación de respuestas de APIs y asegurar la integridad de la información procesada por una aplicación.

Validación de Tipos de Datos

El primer paso para validar un documento JSON es verificar que cada campo contenga el tipo de dato esperado. Los tipos más comunes incluyen string, number, integer, boolean, object y array.

Ejemplo de JSON de entrada:

{
  "estado": true,
  "identificador": 8823,
  "etiqueta": "PROD-99",
  "detalles": {
    "vendedor": "Empresa Alfa",
    "stock": 150
  }
}

Esquema de validación correspondiente:

{
  "type": "object",
  "properties": {
    "estado": { "type": "boolean" },
    "identificador": { "type": "integer" },
    "etiqueta": { "type": "string" },
    "detalles": {
      "type": "object",
      "properties": {
        "vendedor": { "type": "string" },
        "stock": { "type": "integer" }
      }
    }
  }
}

Restricción por Valores Constantes

En ocasiones, un campo debe tener un valor específico y exacto. Para estos casos, utilizamos la palabra clave const.

JSON de entrada:

{
  "version_api": "v2.1"
}

Esquema con constante:

{
  "type": "object",
  "properties": {
    "version_api": {
      "const": "v2.1"
    }
  }
}

Validación mediante Expresiones Regulares

Para campos con formatos complejos como correos electrónicos, números telefónicos o códigos específicos, se utiliza el atributo pattern para aplicar expresiones regulares (Regex).

JSON de entrada:

{
  "codigo_postal": "CP-28001",
  "referencia": "REF_2023_XYZ"
}

Esquema con validación de patrones:

{
  "type": "object",
  "properties": {
    "codigo_postal": {
      "pattern": "^CP-[0-9]{5}$"
    },
    "referencia": {
      "pattern": "^REF_[0-9]{4}_"
    }
  }
}

Caso Integrador de Validación

Un esquema robusto suele combinar tipos, constantes, patrones y la definición de campos obligatorios mediante required.

JSON de ejemplo:

{
  "operacion_exitosa": true,
  "id_transaccion": 550,
  "metodo": "CREDITO",
  "usuario": {
    "rol": "admin",
    "nivel": 5
  }
}

Esquema integral:

{
  "type": "object",
  "properties": {
    "operacion_exitosa": { "type": "boolean" },
    "id_transaccion": { "type": "integer" },
    "metodo": { "pattern": "CREDITO|DEBITO" },
    "usuario": {
      "type": "object",
      "properties": {
        "rol": { "const": "admin" },
        "nivel": { "type": "integer" }
      },
      "required": ["rol", "nivel"]
    }
  },
  "required": ["operacion_exitosa", "id_transaccion", "usuario"]
}

Implementación de Validación con Python

Para ejecutar estas validaciones programáticamente en Python, se utiliza la librería jsonschema. A continuación, se muestra un ejemplo integrado en un caso de prueba.

import jsonschema
import requests
import unittest

class ValidadorApiTest(unittest.TestCase):

    def test_verificar_respuesta_json(self):
        # Configuración de la petición
        endpoint = "https://api.ejemplo.com/v1/recurso"
        credenciales = {"user": "tester", "key": "secret123"}
        
        # Ejecución de la solicitud
        respuesta = requests.get(endpoint, params=credenciales)
        datos_recibidos = respuesta.json()

        # Definición del esquema esperado
        esquema_esperado = {
            "type": "object",
            "properties": {
                "status": {"type": "string", "pattern": "ok"},
                "id": {"type": "number"},
                "items": {"type": "array"}
            },
            "required": ["status", "id"]
        }

        # Ejecución de la validación
        try:
            jsonschema.validate(instance=datos_recibidos, schema=esquema_esperado)
            print("Validación exitosa: Los datos coinciden con el esquema.")
        except jsonschema.exceptions.ValidationError as error:
            self.fail(f"Fallo en la validación del JSON: {error.message}")