System Design
Diccionario de datos
Explica cómo documentar campos, tipos, significado, formato, origen, sensibilidad, reglas, ownership y ciclo de vida mediante un diccionario de datos.
- Última actualización
- Actualizada
- Nivel
- Aplicación
System Design
Explica cómo documentar campos, tipos, significado, formato, origen, sensibilidad, reglas, ownership y ciclo de vida mediante un diccionario de datos.
Un diccionario de datos no copia columnas: documenta significado, procedencia, reglas, sensibilidad, ownership y uso. Debe permitir decidir qué valores son válidos y cómo tratar el dato durante todo su ciclo de vida.
El diccionario de datos conecta lenguaje de negocio, modelo lógico, implementación y operación. Responde no solo “qué tipo tiene”, sino qué representa el dato, quién lo produce, quién puede modificarlo y qué consecuencias tendría interpretarlo mal.
Nombres como status, amount, available o date parecen claros hasta que dos equipos les asignan significados diferentes. Esa ambigüedad provoca reportes incompatibles, integraciones rotas y reglas duplicadas.
Un diccionario convierte conocimiento implícito en un contrato consultable.
Dato
├─ significado
├─ formato y unidad
├─ origen y autoridad
├─ reglas e integridad
├─ sensibilidad y acceso
├─ retención y eliminación
└─ consumidores y usosLa definición debe permitir decidir casos reales.
Malo:
available_stock: stock disponibleMejor:
available_stock: unidades que pueden comprometerse para nuevas ventas en una sucursal; se calcula como existencia física menos reservas activas y bloqueos.Monto es un concepto; numeric(14,2) es una implementación. Registrar ambos evita confundir semántica con almacenamiento.
Cantidad puede significar unidades, kilogramos o cajas. Fecha puede representar instante UTC, fecha local o periodo comercial.
NULL puede significar desconocido, no aplica, aún no asignado o dato eliminado. Cada significado debe ser explícito.
Indica quién produce el dato, cuál sistema es autoritativo y quién responde por su definición.
Incluye rango, unicidad, dependencias, estados válidos, formato y relación con otros campos.
Distingue público, interno, confidencial, dato personal y sensible. La clasificación debe influir en acceso, logging, cifrado y retención.
| Propiedad | Descripción |
|---|---|
| Nombre | Nombre canónico y alias |
| Definición | Significado operacional |
| Tipo conceptual | Monto, cantidad, identificador, instante |
| Implementación | Tipo físico y formato |
| Unidad | USD, kg, unidades, milisegundos |
| Requerido | Regla de presencia y significado de ausencia |
| Fuente | Sistema o proceso autoritativo |
| Reglas | Rango, unicidad, dependencias |
| Sensibilidad | Clasificación y controles |
| Retención | Duración y eliminación |
| Consumidores | APIs, reportes, procesos y modelos |
| Campo | Definición | Regla | Fuente | Sensibilidad |
|---|---|---|---|---|
| available_stock | Unidades vendibles en una sucursal | on_hand - reserved - blocked; no negativo para confirmar venta | Inventario | Interno |
| customer_email | Dirección usada para comunicaciones de la cuenta | Normalizada; única por tenant cuando aplica | Identidad | Dato personal |
| order_total | Monto final acordado al confirmar | Moneda obligatoria; no se recalcula con precios actuales | Pedidos | Confidencial |
Se captura o recibe como hecho primario. Ejemplo: cantidad física contada.
Se calcula desde otros valores. Debe indicar fórmula y frecuencia de actualización.
Copia deliberada para conservar contexto histórico, como dirección o precio de una venta.
Confundir estos tipos crea varias fuentes de verdad.
No basta con listar valores. Explica el significado, transiciones permitidas, valores terminales y estrategia ante valores desconocidos en integraciones.
confirmed
→ pedido aceptado y con compromisos creados
→ no significa pagado necesariamentePara cada dato personal documenta:
La minimización empieza en diseño: no recopiles un dato “por si acaso”.
Aclara:
created_at suele ser un instante UTC; delivery_date puede ser fecha local de la sucursal.
Distingue ID interno, clave natural, identificador visible y referencia externa. No todos deben exponerse en APIs.
Un ID visible puede necesitar no ser enumerable; una referencia externa puede no ser estable.
El diccionario debe versionarse junto con el modelo. Cuando cambia una definición:
Puede ser snapshot histórico o redundancia accidental. Documentar propósito permite distinguirlos.
Usar 0, cadena vacía o fecha actual puede esconder ausencia real. Un default necesita significado.
En integraciones, rechazar nuevos valores puede romper consumidores. Decide tolerancia y observabilidad.
Soft delete no garantiza eliminación por privacidad: pueden quedar copias en eventos, logs, cachés o backups.
status sin explicar estados.Es imprescindible cuando varios equipos, integraciones, analítica o regulación dependen de los datos. En un sistema pequeño puede ser compacto, pero los campos ambiguos o críticos siguen necesitando definición.
NULL necesita una definición?Normalización y consistencia de datos explica cómo evitar anomalías y controlar las copias deliberadas.