---
file: data-dictionary.md
owner_role: <analytics-engineering-lead>
approver_role: <head-of-data>
status: draft
version: 1
effective_from: <YYYY-MM-DD>
last_reviewed: <YYYY-MM-DD>
review_by: <YYYY-MM-DD>
review_cadence: on schema or property change, otherwise quarterly
change_triggers: [new CRM property, model contract change, new source, identity change]
open_items: 0
---

# Data dictionary

Copy to `martech-context/data-dictionary.md`. Explain meaning, origin and relationships. Do not paste column lists: link the model or export that holds them. No real records or personal data.

## Open items

- <question> | owner: <role> | due: <YYYY-MM-DD>

## Entities and identifiers

### <Entity, for example Account>

- Business key: <account_id>, created by <system> at <moment>
- Mappings: <account_id -> crm_company_id (one current CRM company per account)>; <account_id -> billing_customer_id (one to one)>
- Person to entity: <one person can belong to several accounts; never join on email>
- Anonymous to known: <how the anonymous ID reaches the backend or CRM, or "not linked">
- Authoritative source for state: <billing for plan and status; CRM for owner and stage>

## Timestamps

- `<created_at>` on <object>: <meaning>, <time zone>, set by <system>
- `<qualified_at>`: <meaning>
- `<synced_at>`: <when the connector copied the row; never a business date>

## Shared properties

Defined once here, referenced by event contracts and models. Includes custom attributes in messaging and CRM tools.

- `<property_name>`: <type>; allowed values <list or format>; unit <unit>; `null_means` <meaning>; written by <systems>; on conflict <which writer wins, or last write wins>; used by <events, models, tools>

## Join hazards

- <account -> contacts -> subscriptions>: multiplies rows; use <approved model> or aggregate to <grain> first.

## Known lags and limitations

- <CRM lifecycle stage lags billing status by up to N hours>
- <Ad cost for day D is complete by D+1 at HH:MM in time zone>

## Misleading fields

Fields whose names suggest something they do not record.

- `<field>` in <system>: records <what it really is>, not <what the name suggests>. For <question>, use <approved field or model>.

## Deprecated fields still populated

- `<field>`: replaced by `<field>` from <YYYY-MM-DD>; do not use for <purpose>.

## Archive

Superseded definitions with `effective_to`.