Field note
How should a data dictionary change over time, and how do I keep it from going stale?
Give each handoff a version, freeze a point-in-time edition, record subsequent changes, and keep a steward or review cadence visible. An undated spreadsheet quickly loses authority.
Freeze a review point
A frozen edition captures dataset context, fields, value sets, and reader evidence with a digest. It remains read-only while the working project continues.
Compare amendments
Comparison against a frozen edition lists fields added and removed, and the authored properties that now differ: label, definition, declared type, role, unit, required, status, value set, universe or derivation. That is documentation evidence, not a source-data or schema migration diff. It tells you the definition of a field changed between the handoff and today; it does not tell you whether the data changed with it.
Keep ownership visible
Name a steward as a role rather than a person, and set a cadence tied to something that actually happens, such as the end of a collection cycle or a scheduled handoff. A reader can then judge how old the document is and whom to ask, which is most of what ownership is for. Recording a cadence does not create organizational review, and nothing in the studio chases anybody to perform one.
Worked example from the sample project
The sample project carries version 0.9, a named steward and a review cadence of once per field season, and that cadence is the part most dictionaries lack. A dictionary goes stale between handoffs, not during them, so tying review to a real event, the end of a field season, a collection cycle, a scheduled handoff, is more reliable than tying it to a date somebody has to remember.
Freeze an edition and the studio takes a digest over the dataset context, the fields and the value sets as they stand. The edition is read-only afterwards while the working project continues, so the comparison view can list exactly what changed: fields added or removed, and authored properties such as label, definition, declared type, role, unit, required, status, value set, universe or derivation that differ from the frozen copy.
That comparison is documentation evidence, not a schema migration. It tells you the definition of condition changed between the handoff and today. It does not tell you whether the underlying data changed with it.
What this does not do
- An edition digest detects modification. It is not a signature and proves no approval.
- The comparison covers authored documentation properties, not source data or a full schema diff.
- A review cadence in the record does not create organisational review.
Do this in the studio
Freeze at handoff points, then let the comparison show what moved afterwards.
- Open the Editions station and freeze an edition when the documentation is ready to hand on.
- Keep the frozen edition rather than editing it; the working project carries on beside it.
- Compare a later state against it before the next handoff and record the differences.
Open the studio at the Editions station