Schema

Resumen

Un schema es una descripción formal de cómo debe estar organizada cierta información. Define qué campos existen, qué tipos de valores aceptan, cuáles son obligatorios, qué relaciones hay entre partes del modelo y qué restricciones deben cumplirse para considerar válida esa estructura.

Importa porque convierte acuerdos implícitos en contratos verificables. Sin schema, dos sistemas pueden creer que hablan del mismo dato cuando en realidad usan nombres, tipos o reglas distintas. Con schema, frontend, backend, base de datos, validadores y herramientas comparten una definición explícita de la forma esperada.

Alcance y supuestos

Este paquete cubre schema como concepto general en software: estructura, tipos, campos, constraints, relaciones y validación de datos o contratos en APIs, documentos y bases de datos.

No cubre tutoriales completos de JSON Schema, GraphQL SDL, SQL DDL, ORMs, migraciones ni modelado visual detallado. Asume que entiendes datos estructurados, APIs, validación básica y que distintos componentes de software intercambian información.

Modelo mental

Piensa en el plano de una casa. El plano no es la casa misma, pero sí define cuántas habitaciones hay, dónde están las puertas, qué espacios se conectan y qué dimensiones debe respetar la construcción. Si un albañil improvisa una puerta donde no va, o elimina una columna estructural, el resultado deja de cumplir el plano.

Un schema cumple ese rol para los datos. No es el dato en sí, sino la definición de su forma permitida. Dice qué piezas existen, cómo se llaman, qué tipo de valor admiten y qué combinaciones son válidas. Luego cada tecnología lo materializa a su manera: una API lo expresa como request/response shape, GraphQL como tipos y campos, y una base relacional como tablas, columnas, claves y constraints.

La idea clave es separar contenido de estructura. Puedes cambiar los valores de un pedido, un usuario o un evento miles de veces, pero mientras respeten el mismo schema, productores y consumidores siguen entendiendo el contrato.

Uso práctico

Usa schemas cuando necesites que varias piezas del sistema compartan una estructura verificable:

• ✅ Validar payloads de entrada antes de procesarlos.
• ✅ Documentar contratos de APIs para que frontend y backend hablen el mismo idioma.
• ✅ Modelar tablas, columnas, claves y constraints en bases de datos.
• ✅ Hacer evolucionar un contrato agregando o deprecando campos de forma controlada.
• ❌ Un schema no reemplaza toda la lógica de negocio; puede validar estructura, pero no todas las reglas semánticas complejas.
• ❌ No sirve de mucho si el equipo lo ignora y cada servicio serializa datos de forma distinta por fuera del contrato.

Ejemplo trabajado: definir el schema de un pedido para una integración

Supón que una tienda envía pedidos a un servicio externo de fulfillment. Si ambos lados solo dicen "mándame un pedido en JSON", el acuerdo es ambiguo. Un schema vuelve explícito qué estructura esperan:

{
  "type": "object",
  "required": ["orderId", "customerEmail", "items"],
  "properties": {
    "orderId": { "type": "string" },
    "customerEmail": { "type": "string", "format": "email" },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["sku", "quantity"],
        "properties": {
          "sku": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 }
        }
      }
    }
  }
}

Qué aporta ese schema:

1. Define campos obligatorios: no puedes enviar un pedido sin orderId, customerEmail o items.
2. Define tipos: quantity no puede ser cualquier texto; debe ser un entero.
3. Define restricciones: items debe tener al menos un elemento y quantity debe ser mayor o igual a 1.
4. Reduce ambigüedad entre productor y consumidor: ambos saben qué forma esperan.
5. Permite automatizar validación, documentación y tooling alrededor del contrato.

La misma idea aparece en otras tecnologías:

• En GraphQL, el schema define qué tipos y campos puedes consultar.
• En una base relacional, el schema define tablas, columnas, claves y constraints.
• En formatos de eventos o mensajes, el schema define el payload válido que otros servicios consumen.

Antes de diseñar un schema, conviene revisar estas preguntas:

1. ¿Qué estructura mínima necesita el consumidor para hacer su trabajo?
2. ¿Qué campos son obligatorios y cuáles opcionales?
3. ¿Qué tipos y restricciones deben validarse de forma automática?
4. ¿Cómo evolucionará el contrato sin romper consumidores existentes?
5. ¿Qué reglas pertenecen al schema y cuáles requieren lógica de negocio adicional?

Evidencia

• GraphQL, Schemas and Types explica que el type system describe qué datos puede consultar una API y que el conjunto de esas capacidades constituye su schema.
• JSON Schema, What is a schema? muestra que un schema sirve para describir la estructura esperada de un documento JSON y validar si un dato cumple ese contrato.
• Oracle AI Database, Schemas and Schema Objects define un database schema como un contenedor lógico de estructuras de datos y enumera objetos como tablas, índices y vistas.