Jaco van der Laan

📘 Entity‑First Playbook: Naming, Ownership & Quality Gates

11/10/2025  ·  Data Modeling  ·  Metadata

‹ ›

Track A (Business) — Part 3 of the Entity‑First series

Series navigation: A1 — Why We Need a Business‑Friendly Data Transformation Model • A2 — Entities, Subject Areas & Transformation Steps • B1 — How dbt & SQLMesh Organize Metadata and Code • B2 — Designing an Entity‑First YAML → SQL Generator • A3 (you are here)

Summary

This playbook turns the Entity‑First approach into day‑to‑day practice. It covers naming conventions, ownership/RACI, change workflow, and quality gates so that modelers and engineers ship reliable data products with the same rules, vocabulary, and review process.

Press enter or click to view image in full size

1) Goals & scope

  • Create a shared rulebook for business modelers and engineers.
  • Keep definitions business‑readable while remaining machine‑actionable.
  • Bake governance into the workflow via checklists, templates, and CI gates.

Applies to: all entities (Source, Intermediate, Delivery) and all patterns (Core, Characteristic, Associative, Reference) across all subject areas.

2) Naming conventions

2.1 General principles

  • Readable > compressed: prefer order_enriched over ord_enr.
  • Consistency > cleverness: once a rule exists, follow it everywhere.
  • Stable identifiers: avoid renaming entities casually; treat names as contracts.
  • No physical leakage: names reflect meaning, not materialization.

2.2 Subject areas

  • sales, marketing, finance, operations, support, shared (reference/utility).
  • Keep subject areas business‑aligned (mirrors capabilities/value streams).

2.3 Entities

  • Format: <subject_area>.<entity_name> (e.g., sales.order_enriched).
  • Role suffix (optional in description): (source|intermediate|delivery) not in the name.
  • Pattern tag appears in metadata (Core, Characteristic, Associative, Reference).
  • Aggregates: name by grain, e.g., order_daily_metrics, customer_monthly_kpis.

2.4 Columns

  • Primary keys: <entity>_id or domain‑appropriate key; avoid overloaded business keys.
  • Foreign keys: <referenced_entity>_id.
  • Booleans: is_*/has_* (e.g., is_active).
  • Timestamps: _at suffix (created_at, updated_at).
  • Durations: descriptive (days_to_ship).

2.5 Relationships

  • Named relationships: order_to_customer (left→right).
  • Join rules are metadata; avoid embedding bespoke join SQL in names.

2.6 Files & folders (for generated artifacts)

entities/<subject_area>/<entity>/<entity>.entity.yml    # source of truth  
# Generated:  
dbt/models/staging|integration|marts/<subject_area>/...  
sqlmesh/models/...

3) Ownership & RACI

3.1 Roles

  • Entity Owner (business): accountable for semantics, definitions, and fitness for purpose.
  • Modeling Lead (data modeler): maintains structure, keys, relationships, and alignment to standards.
  • Engineering Owner (data/analytics engineer): responsible for generated SQL, performance, deployment.
  • Data Steward (governance): ensures documentation quality, glossary terms, sensitivity classifications.
  • Reviewer pool: cross‑subject‑area architects for design consistency.

3.2 RACI per activity

Tip: enforce code ownership in Git (_CODEOWNERS_) mapped to subject areas.

4) Change workflow (from idea to merge)

  1. Propose: open a ticket referencing business need; attach draft entity YAML and glossary terms.
  2. Design review: short async review focusing on naming, role/pattern, PK/FK, and step type.
  3. PR: commit entity YAML; CI runs validators, generates SQL, tests, and diagrams.
  4. Stakeholder sign‑off: Entity Owner and Modeling Lead approve; Steward checks docs.
  5. Deploy: merge → compile/run in staging; smoke tests → promote.

Pull request template

  • Business goal / Jira link
  • Entity(ies) changed (role, pattern)
  • PK/FK summary
  • Step type(s) and grain after change
  • Impacted downstream entities
  • Screenshots of generated diagram / docs
  • Checklists (below) ticked

5) Quality gates (CI checks)

5.1 Structural & semantic

  • ✅ JSON Schema validation of YAML
  • ✅ Graph acyclicity; all inputs resolvable
  • ✅ PK exists and appears in structure.columns
  • ✅ FK targets exist; relationship paths valid
  • ✅ Step‑type constraints obeyed (e.g., union alignment; aggregate grain defined)

5.2 Testing & data quality

  • ✅ Generated tests for PK uniqueness, NOT NULL on required columns
  • ✅ Relationships tests (FK) between entities
  • ✅ Optional freshness checks on Source entities
  • ✅ Profiling queries emitted for Sources & Intermediates

5.3 Documentation

  • ✅ Entity description, business glossary links
  • ✅ Subject area and ownership metadata
  • ✅ Diagram node present with role/pattern badges
  • ✅ Exposure notes (for Delivery entities)

6) Checklists

6.1 New entity checklist

  • Subject area chosen and owner assigned
  • Role (Source/Intermediate/Delivery) and Pattern (Core/Characteristic/Associative/Reference) set
  • Primary key defined and documented
  • Columns typed; sensitive fields tagged
  • Inputs & relationships listed
  • Step type selected with predicates/aggregations as needed
  • Constraints captured (NOT NULL/UNIQUE/FK)
  • Glossary entries added/linked
  • Diagrams generated and reviewed

6.2 Change checklist (breaking)

  • Grain change reviewed; downstream entities identified
  • Deprecation/migration plan documented
  • Version note added to release notes

6.3 Aggregate entity checklist

  • Group‑by fields match declared grain
  • Aggregations defined per column
  • Surrogate PK for the aggregate grain
  • Post‑derivations documented (e.g., KPIs)

7) Templates

7.1 Entity YAML skeleton

enity: <name>  
subject_area: <domain>  
role: <source|intermediate|delivery>  
pattern: <core|characteristic|associative|reference>  
primary_key: <pk>  
structure:  
  columns: { }  
step:  
  type: <derive|filter|aggregate|union|translate>  
inputs: []  
relationships: []  
mappings: {}  
constraints: {not_null: [], unique: [], foreign_keys: []}  
ownership: {entity_owner: <name>, engineering_owner: <name>, steward: <name>}  
documentation: {description: "", glossary: ["<term>"]}

7.2 PR template (Markdown)

**Business goal:** <why>  
**Entities touched:** <list>  
**Role/Pattern:** <e.g., Intermediate/Core>  
**PK/FK summary:** <table or bullets>  
**Step types:** <derive/filter/...>  
**Downstream impact:** <who/what>  
**Docs & diagrams:** <screenshots/links>  
**Checklist:** see Playbook §6

7.3 Glossary term template

title: <term>  
definition: <business definition>  
related_entities: [<sa.entity>, ...]  
owner: <name/role>

8) Example: Sales subject area

  • Core entities: sales.customer (Source), sales.order (Source)
  • Intermediate Core: sales.order_enriched (Derive: join + translate)
  • Delivery Core: sales.order_daily_metrics (Aggregate: day,country)
  • Reference: shared.code_translation

Outputs: generated dbt/SQLMesh SQL, ERD + movement diagrams, PK/NN/FK tests, profiling queries.

9) Adoption & rollout

  1. Pilot one subject area; socialize outcomes.
  2. Establish CODEOWNERS and PR template.
  3. Turn checklists into required CI gates.
  4. Migrate legacy model documentation into glossary/metadata.
  5. Publish diagrams and a living wiki; gather feedback; iterate.

10) Links back to the series

🔗 Model-Driven Data Engineering — Entity-First Series

Track A (Business)
← A2 — Entities, Subject Areas & Transformation Steps
A3 — Entity-First Playbook: Naming, Ownership & Quality Gates (you’re here)
→ A4 — Communicating Lineage & Data Quality to Stakeholders

Part of the Model-Driven Data Engineering series — bridging business understanding and metadata-driven design.