Design Serialization Schema

Disenar Esquema de Serializacion

Crear esquemas de serializacion bien versionados que evolucionan elegantemente sin romper consumidores.

Cuando Usar

• Definir un nuevo contrato de API o formato de intercambio de datos
• Agregar campos a un esquema existente sin romper consumidores
• Migrar entre versiones de esquema
• Elegir entre sistemas de esquema (JSON Schema, Protobuf, Avro)
• Documentar reglas de validacion de datos para aplicacion automatizada

Entradas

• Requerido: Modelo de datos (relaciones entre entidades, tipos de campos, restricciones)
• Requerido: Requisitos de compatibilidad (quien consume estos datos, cuanto tiempo deben ser legibles los formatos antiguos)
• Opcional: Esquema existente a evolucionar
• Opcional: Requisitos de rendimiento (velocidad de validacion, integracion con registro de esquemas)
• Opcional: Formato de serializacion objetivo (JSON, binario, columnar)

Procedimiento

Paso 1: Elegir un Sistema de Esquema

Esperado: Sistema de esquema seleccionado basado en ecosistema, necesidades de rendimiento y requisitos de evolucion. En caso de fallo: Si hay incertidumbre, comenzar con JSON Schema -- tiene el soporte de herramientas mas amplio y puede agregarse sobre APIs JSON existentes.

Paso 2: Disenar el Esquema Central

Ejemplo de JSON Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/measurement/v1",
  "title": "Measurement",
  "description": "A sensor measurement reading",
  "type": "object",
  "required": ["sensor_id", "value", "unit", "timestamp"],
  "properties": {
    "sensor_id": {
      "type": "string",
      "pattern": "^[a-z]+-[0-9]+$",
      "description": "Unique sensor identifier (lowercase-digits format)"
    },
    "value": {
      "type": "number",
      "description": "Measured value"
    },
    "unit": {
      "type": "string",
      "enum": ["celsius", "fahrenheit", "kelvin", "percent", "ppm"],
      "description": "Unit of measurement"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp with timezone"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional key-value metadata"
    }
  },
  "additionalProperties": false
}

Ejemplo de Protocol Buffers:

syntax = "proto3";
package sensors.v1;

import "google/protobuf/timestamp.proto";

message Measurement {
  string sensor_id = 1;
  double value = 2;
  Unit unit = 3;
  google.protobuf.Timestamp timestamp = 4;
  map<string, string> metadata = 5;
}

enum Unit {
  UNIT_UNSPECIFIED = 0;
  UNIT_CELSIUS = 1;
  UNIT_FAHRENHEIT = 2;
  UNIT_KELVIN = 3;
  UNIT_PERCENT = 4;
  UNIT_PPM = 5;
}

Ejemplo de Apache Avro:

{
  "type": "record",
  "name": "Measurement",
  "namespace": "com.example.sensors",
  "doc": "A sensor measurement reading",
  "fields": [
    {"name": "sensor_id", "type": "string", "doc": "Unique sensor identifier"},
    {"name": "value", "type": "double", "doc": "Measured value"},
    {"name": "unit", "type": {"type": "enum", "name": "Unit", "symbols": ["CELSIUS", "FAHRENHEIT", "KELVIN", "PERCENT", "PPM"]}},
    {"name": "timestamp", "type": {"type": "long", "logicalType": "timestamp-millis"}},
    {"name": "metadata", "type": ["null", {"type": "map", "values": "string"}], "default": null}
  ]
}

Esperado: Esquema auto-documentado con descripciones, restricciones y definiciones claras de tipos. En caso de fallo: Si el modelo de datos aun no es estable, marcar el esquema como draft y evitar publicarlo en un registro.

Paso 3: Planificar la Evolucion del Esquema

Reglas de compatibilidad:

Estrategia de evolucion segura:

1. Solo agregar campos opcionales con valores predeterminados razonables
2. Nunca eliminar ni renombrar -- deprecar en su lugar
3. Versionar el esquema en el identificador (v1, v2)
4. Usar un registro de esquemas para formatos binarios (Confluent Schema Registry para Avro/Protobuf)

Reglas de evolucion de Protobuf:

// v1 — original
message Measurement {
  string sensor_id = 1;
  double value = 2;
  Unit unit = 3;
}

// v2 — safe evolution
message Measurement {
  string sensor_id = 1;
  double value = 2;
  Unit unit = 3;
  // NEW: added in v2 — old clients ignore this field
  google.protobuf.Timestamp timestamp = 4;
  // DEPRECATED: use sensor_id instead
  reserved 6;
  reserved "old_sensor_name";
}

Versionado de JSON Schema:

{
  "$id": "https://example.com/schemas/measurement/v2",
  "allOf": [
    {"$ref": "https://example.com/schemas/measurement/v1"},
    {
      "properties": {
        "location": {
          "type": "string",
          "description": "Added in v2: GPS coordinates"
        }
      }
    }
  ]
}

Esperado: Plan de evolucion documentado: que cambios son seguros, cuales requieren nuevas versiones. En caso de fallo: Si un cambio incompatible es inevitable, versionar el esquema (v1 -> v2) y mantener soporte paralelo durante la migracion.

Paso 4: Implementar Validacion de Esquema

# JSON Schema validation (Python)
from jsonschema import validate, ValidationError
import json

schema = json.load(open("measurement_v1.json"))

def validate_measurement(data: dict) -> list[str]:
    """Validate a measurement against the schema. Returns list of errors."""
    errors = []
    try:
        validate(instance=data, schema=schema)
    except ValidationError as e:
        errors.append(f"{e.json_path}: {e.message}")
    return errors

# Usage
errors = validate_measurement({"sensor_id": "s-01", "value": "not_a_number"})
# -> ["$.value: 'not_a_number' is not of type 'number'"]

// TypeScript with Zod (runtime + compile-time)
import { z } from 'zod';

const MeasurementSchema = z.object({
  sensor_id: z.string().regex(/^[a-z]+-[0-9]+$/),
  value: z.number(),
  unit: z.enum(['celsius', 'fahrenheit', 'kelvin', 'percent', 'ppm']),
  timestamp: z.string().datetime(),
  metadata: z.record(z.string()).optional(),
});

type Measurement = z.infer<typeof MeasurementSchema>;

// Validation
const result = MeasurementSchema.safeParse(inputData);
if (!result.success) {
  console.error(result.error.issues);
}

Esperado: La validacion se ejecuta en todos los datos entrantes en los limites del sistema (endpoints API, ingestion de archivos). En caso de fallo: Registrar errores de validacion con la carga completa (redactando campos sensibles) para depuracion.

Paso 5: Documentar el Esquema

Crear una pagina de documentacion del esquema con: resumen, tabla de campos (campo, tipo, requerido, descripcion, restricciones), registro de cambios (version, fecha, cambios) y politica de compatibilidad.

# Measurement Schema (v1)

## Overview
Represents a single sensor reading with metadata.

## Fields
| Field | Type | Required | Description | Constraints |
|-------|------|----------|-------------|-------------|
| sensor_id | string | Yes | Unique sensor ID | Pattern: `^[a-z]+-[0-9]+$` |
| value | number | Yes | Measured value | Any valid IEEE 754 double |
| unit | enum | Yes | Unit of measurement | One of: celsius, fahrenheit, kelvin, percent, ppm |
| timestamp | string | Yes | Reading time | ISO 8601 with timezone |
| metadata | object | No | Key-value pairs | String keys and values |

## Changelog
| Version | Date | Changes |
|---------|------|---------|
| v1 | 2025-03-01 | Initial schema |

## Compatibility
- **Backwards**: Consumers of v1 will continue to work with future versions
- **Policy**: Only additive, optional field changes between minor versions

Esperado: La documentacion se genera automaticamente o se mantiene sincronizada con la definicion del esquema. En caso de fallo: Si la documentacion se desvia del esquema, agregar una verificacion CI que valide la documentacion contra la fuente del esquema.

Validacion

• El esquema usa el sistema apropiado para el caso de uso (JSON Schema, Protobuf, Avro)
• Todos los campos tienen tipos, descripciones y restricciones
• Campos requeridos vs opcionales estan definidos explicitamente
• Estrategia de evolucion documentada (cambios seguros, politica de versionado)
• Validacion implementada en los limites del sistema
• El esquema esta versionado con un registro de cambios
• Prueba de ida y vuelta: serializar -> deserializar -> comparar confirma sin perdida de datos

Errores Comunes

• Restringir demasiado temprano: Validacion estricta en un esquema nuevo bloquea la iteracion. Comenzar permisivo (additionalProperties: true), restringir despues.
• Sin valores predeterminados: Agregar un campo requerido sin predeterminado rompe todos los datos existentes. Siempre proporcionar predeterminados para nuevos campos.
• Ignorar null: Muchos esquemas no manejan campos null/faltantes claramente. Ser explicito sobre nullable vs opcional.
• Version en la carga, no en la URL: Para datos de larga duracion (almacenamiento, eventos), incrustar la version del esquema en los datos mismos, no solo en la URL del endpoint.
• Exhaustividad de enum: Agregar un nuevo valor enum puede causar crashes en consumidores que usan sentencias switch exhaustivas. Documentar que los valores desconocidos deben manejarse elegantemente.

Habilidades Relacionadas

• serialize-data-formats -- seleccion de formato e implementacion de codificacion/decodificacion
• implement-pharma-serialisation -- serializacion farmaceutica (esquemas regulados)
• write-validation-documentation -- documentacion de validacion para esquemas regulados