Reference Files
references/data-dictionary-template.md - Template table with all standard columns (field name, description, data type, format, valid values, source, owner, business rules, nullable, example). Read this in Step 3 when documenting individual entities.
Overview
Based on the BABOK Guide v3 (IIBA) - Data Dictionary technique, which defines a data dictionary as a structured repository of data element definitions that eliminates ambiguity about what data means, where it comes from, and who owns it. Also draws on Business Analysis Techniques by James Cadle for Entity-Relationship Diagrams, CRUD Matrix, and Data Dictionary best practices. The key insight: a data dictionary is not a database schema dump. It is a business-facing document that defines what each data element means in business terms, who is the authoritative source, and what rules govern its values.
Workflow
Step 1: Identify data sources and scope
SYSTEM(S): [which systems are in scope]
PURPOSE: [why this data dictionary is being created - new build, migration, integration, audit]
AUDIENCE: [who will use this - developers, testers, business users, auditors]
SOURCES: [where to get the data definitions - database schemas, APIs, existing docs, SMEs]
Step 2: List entities and relationships
Identify the key business entities and how they relate:
| Entity | Description | Relationships |
|--------|-------------|---------------|
| Customer | A person or organization that purchases products | Has many Orders; Belongs to one Segment |
| Order | A purchase transaction | Belongs to one Customer; Has many Line Items |
| Product | An item available for sale | Appears in many Line Items |
Draw or describe the Entity-Relationship model: cardinality (1:1, 1:N, M:N), mandatory vs. optional.
Step 3: Document each entity's fields
For each entity, use the template from references/data-dictionary-template.md:
ENTITY: [name]
| Field | Description | Type | Format | Valid Values | Source | Nullable | Business Rules |
|-------|-------------|------|--------|-------------|--------|----------|---------------|
| customer_id | Unique identifier | UUID | xxxxxxxx-xxxx | System-generated | [system] | No | Immutable after creation |
| email | Primary contact email | String | name@domain.com | Valid email format | User input | No | Must be unique per customer |
| status | Account status | Enum | - | active, suspended, closed | [system] | No | Can only transition: active->suspended->closed |
Step 4: Build the CRUD matrix
Map which functions Create, Read, Update, or Delete each entity:
| Entity / Function | Registration | Order Mgmt | Reporting | Admin |
|-------------------|-------------|------------|-----------|-------|
| Customer | C, R | R | R | C, R, U, D |
| Order | - | C, R, U | R | R, U, D |
| Product | - | R | R | C, R, U, D |
This reveals: which functions are authoritative (C), which are consumers (R only), and where delete authority sits.
Step 5: Document data lineage
For shared or derived fields, trace the data path:
FIELD: total_revenue (Reporting Dashboard)
SOURCE: orders.line_items.unit_price * orders.line_items.quantity
TRANSFORMATION: Sum by customer_id, grouped by month
REFRESH: Daily batch at 02:00 UTC
AUTHORITATIVE SOURCE: Order Management System
Step 6: Identify data quality rules
For each critical field:
FIELD: [name]
QUALITY RULE: [validation, format, range, uniqueness, referential integrity]
CURRENT QUALITY: [% compliant if known]
REMEDIATION: [what to do when data violates the rule]
Step 7: Output the data dictionary
Deliver: entity list with relationships, field-level definitions per entity, CRUD matrix, data lineage for derived/shared fields, and data quality rules.
Anti-Patterns
1. Database schema dump labeled as a data dictionary
Bad: Exporting column names and data types from the database and calling it done.
Good: Each field has a business description, valid values, source system, and business rules.
2. Technical descriptions only
Bad: "VARCHAR(255), NOT NULL" (That's the schema, not the dictionary.)
Good: "Customer's primary email address. Used for order confirmations and password reset. Must be unique per customer account."
3. No ownership or source attribution
Bad: Field definitions without noting which system is the authoritative source.
Good: Every field traces to its source system and data owner. When systems disagree, the authoritative source is explicit.
4. Static document that's never updated
Bad: Data dictionary written at project start, never maintained.
Good: Data dictionary is a living document updated whenever entities, fields, or rules change. Version-controlled.
5. Missing CRUD matrix
Bad: Field definitions without documenting which functions interact with each entity.
Good: CRUD matrix reveals who creates, reads, updates, and deletes each entity - critical for integration and security design.
Quality Checklist