Field note

How should categorical codes be documented?

List each code, a readable label, and enough meaning to distinguish nearby categories. State whether the list is descriptive or intended as a constraint and preserve important ordering in the prose.

Code plus label is the minimum

Every allowed value needs the code exactly as it appears in the data, and a readable label. A bare list of codes forces the reader to guess, and a bare list of labels leaves them unable to match a label to a row. The review flags a value with no code as an error and a value with no label as a warning.

Meaning prevents false equivalence

A label alone still leaves the boundary between neighbouring categories to the reader's imagination, so record what each code means and, where it matters, when it applies. Two categories that sound close are the ones most often applied inconsistently in the field. Say in the folio whether the list describes what was observed or is intended as a constraint, because the studio validates nothing against your data.

Reused value sets need review

A value set is a shared object: editing it reaches every field bound to it at once. Bind a set from a second field only when the codes genuinely carry the same meaning there, not because the names look similar, and re-read every bound field after you change one. Keep missing-value states out of the shared set, because what counts as absent is usually specific to how one field was collected.

Worked example from the sample project

The sample binds condition to a shared value set called Tree condition categories, holding good meaning no issue recorded during the bounded visual observation, watch meaning a follow-up observation was requested, and unknown labelled Not rated. Notice that each code carries both a label and a meaning. Good and Watch alone would leave a reader guessing at the threshold between them, and the guess would differ per reader.

Value sets are shared objects, which is a convenience and a hazard in the same feature. Binding two fields to one set is right when the codes genuinely mean the same thing in both places, and wrong when two similarly named statuses have different lifecycles, owners or effective dates. Reuse also means a later edit reaches every bound field at once, so a change should be reviewed at each of them rather than only where it was made.

Missing codes stay outside the shared set on purpose. What counts as absent is often specific to how one field was collected, even when the valid categories are shared.

What this does not do

A listed value set is descriptive documentation; it enforces nothing and validates nothing.
The studio does not check that the source data only contains the codes you listed.
Sharing a set does not make two fields semantically equivalent.

Do this in the studio

Give every code a label and a meaning, and share a set only when the semantics are genuinely identical.

Open the Value sets station and create the set with codes, labels and meanings.
Bind it from the field folios that truly share those semantics.
Re-read every bound field after editing a shared set.

Open the studio at the Value sets station