# Data dictionary template with meaning, ownership, and lifecycle

Canonical: https://githtml.com/guides/data-dictionary-template
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

A data dictionary should explain what a field means, not merely repeat its storage type. Capture its source, units, allowed values, null behavior, ownership, and lifecycle references. Include illustrative values that cannot be mistaken for real customer data, and identify which schema or contract the dictionary describes.

## Begin with meaning and scope

Name the dataset or interface and state whether the dictionary describes stored records, an API payload, or an analytical view. The same label may mean different things across these boundaries. An illustrative created_at field might mean request acceptance time rather than processing completion time; readers need that distinction to interpret a delay correctly. Link the relevant schema at a reviewed revision. OpenAPI's schema vocabulary can help describe API fields, but business meaning still needs plain language that a type declaration cannot provide by itself.

## Give each field a complete entry

For the illustrative field export_status, document its purpose, known values, transition owner, and whether a missing value is valid. For a duration, state the unit and the interval being measured. For an identifier, explain which entity it refers to and whether it can be exposed to users. Use synthetic values and avoid copying a production row as a convenient example. A glossary entry should resolve ambiguity rather than bury it beneath a technically accurate but unhelpful phrase such as string or nullable integer.

1. Meaning: state the real-world event, entity, or quantity represented.
2. Shape: record type, units, allowed values, and absence semantics.
3. Lifecycle: link the responsible owner and approved retention or deletion policy.

## Make changes discoverable

Review the dictionary when a field is added, renamed, repurposed, or removed. A type-compatible change can still alter meaning, so schema validation is not the only maintenance signal. Preserve a clear record of deprecated values and explain what consumers should do when encountering an unfamiliar value according to the actual contract. In HTML, short field sections often read better on a phone than a very wide table. If a table is appropriate, use real headers and a caption, following W3C guidance, so relationships are available to assistive technologies.

## Sources and further reading

- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [W3C WAI: Tables Tutorial](https://www.w3.org/WAI/tutorials/tables/)

## Related guides

- [Operational runbook template with safe stop conditions](https://githtml.com/guides/operational-runbook-template)
- [Developer onboarding guide template for a first useful change](https://githtml.com/guides/developer-onboarding-guide-template)
- [Software migration plan template with exit and rollback gates](https://githtml.com/guides/software-migration-plan-template)
- [Release notes template that explains user impact](https://githtml.com/guides/release-notes-template-for-users)

Editorial approach: https://githtml.com/guides/about