Field note
What is the complete workflow for creating a data dictionary readers can use?
To create a data dictionary readers can use, settle what one row represents, then import the file's structure and write each field's meaning, unit, allowed values and missing codes. Run the deterministic review, test a few fields with a real reader, freeze an edition, and export a passive packet that opens without the studio.
Begin with the dataset, not the columns
Open the Dataset context station before anything else and settle what one row is, why the dataset exists, when it was collected, who stewards it and how often it is reviewed. Every folio written afterwards quotes that settlement. A definition written before it is fixed quietly assumes one answer, and the reader cannot tell which.
Write field folios in reader order
Document the fields a reader is most likely to misread first, rather than the order the file happens to list them. Each folio holds the label, definition, role, declared type, unit, universe, source method, derivation, owner, review status and an optional authored example. Leave the properties you cannot answer visibly empty; an honestly unfinished folio is more useful than a filled one that is guessing.
Use review and editions deliberately
The deterministic review reports gaps a rule can see, such as a missing label, a circular definition, a measure without a unit, or a code listed as both valid and missing. Freeze an edition only at a real handoff point, because the frozen copy is read-only and becomes the thing you can later compare against. Export a checkpoint for your own continuity and a passive packet for the reader.
Worked example from the sample project
Open the sample and the studio holds the fictional Neighbourhood tree inventory: one record per observed street tree inside an invented Northbank survey boundary, collected between 1 and 14 April 2026, version 0.9, with a documentation steward and a review cadence of once per field season. Six fields are documented: tree_id, observed_on, species_code, trunk_cm, condition and access_note.
Walk them in the order the workflow suggests and you can see why the order exists. The dataset context is written first, so the phrase one record represents one observed tree is fixed before anybody argues about a column. Then the field folios: tree_id declared as text with the identifier role, because a numeric-looking key is still a key; trunk_cm declared as a number measure with the unit centimetres, because a bare number named trunk_cm is a guess; species_code carrying a missing code UNK; condition bound to a shared value set of good, watch and unknown; access_note left as free text and marked needs-review, which is an honest state rather than a gap.
What this does not do
- It does not write or infer a definition. Every sentence in a field folio was typed by a person.
- It does not decide whether a dataset is fit for an analysis, a repository, a regulation or a decision.
- It does not classify sensitivity or make a disclosure judgement on your behalf.
Do this in the studio
Write the dataset context before the first field folio, because everything downstream quotes it.
- Open the Dataset context station and record purpose, population, collection period, steward and version.
- Import structure only after that, so observed shape lands beside a stated purpose instead of replacing one.
- Freeze an edition at the Editions station when the documentation is ready for a point-in-time handoff.
Open the studio at the Dataset context station