Data Dictionary¶

Purpose¶

The Organizational Data Dictionary defines the meaning, context, ownership, and governance of concepts and data used across the organization.

It provides a common semantic language between business users, data practitioners, engineers, systems, and analytical applications.

The dictionary distinguishes between:

What something means
        ↓
Where it comes from
        ↓
How it is implemented

A source system's terminology does not automatically become the organization's canonical terminology.

Definition Types¶

The initial dictionary supports four primary definition types:

Type	Purpose
Concept	Defines an organizational concept and its meaning.
Metric	Defines a quantitative measurement and how it is calculated or interpreted.
KPI	Defines a metric or group of metrics used to evaluate important performance.
Data Asset	Defines a managed collection of data such as a dataset or table.

Additional definition types may be introduced as the model evolves.

Common Metadata¶

Where applicable, definitions may contain:

Property	Description
`id`	Stable identifier for the definition.
`name`	Human readable name.
`type`	Definition type.
`definition`	Canonical meaning of the concept or measurement.
`description`	Additional contextual explanation.
`domain`	Domain in which the definition is primarily used.
`status`	Lifecycle status of the definition.
`owner`	Organizational owner accountable for the definition.
`steward`	Person or team responsible for maintaining the definition.
`related`	Related concepts, metrics, datasets, systems, or documents.
`version`	Version of the definition where semantic versioning is required.

Not every definition requires every property.

Canonical Definition vs Source Definition¶

The dictionary separates three layers:

Canonical Meaning
        ↓
Source Representation
        ↓
Physical Implementation

For example:

Canonical
social.follower_count

        ↓

Instagram
followers_count

        ↓

Physical
API response field / database column

Multiple source fields may map to one canonical definition, and one source field may contribute to multiple derived metrics.

Naming¶

Definitions should use stable, domain aware identifiers.

Examples:

social.follower_count
social.impressions
social.engagement_rate
finance.revenue
observability.error_rate

Names should describe organizational meaning rather than reproduce source system terminology.

Source specific names belong in source mappings.

Lifecycle¶

Definitions should have a lifecycle status such as:

draft
active
deprecated
retired

Definitions with historical or downstream significance should normally be deprecated or retired rather than deleted.

Ownership¶

Every governed definition should eventually have an accountable owner.

Ownership represents accountability for the meaning and use of the definition.

Stewardship represents responsibility for maintaining the definition and associated metadata.

These responsibilities may belong to different people or teams.

Governance¶

The data dictionary forms part of the organization's broader data governance framework.

As the model matures, definitions may additionally include:

Data classification
Quality requirements
Retention requirements
Access requirements
Regulatory considerations
Lineage
Certification status
Approval history

These attributes should only be introduced when they have a defined organizational purpose.

Evolution¶

The dictionary is a living model.

New definitions should reuse existing concepts where their meaning is genuinely shared. Domain specific definitions should remain within their domain until there is sufficient evidence that they belong in the common vocabulary.

The machine readable definitions in the repository are the canonical source of truth. The documentation site provides the human facing representation of those definitions.