Field note
What makes a field definition useful?
A definition should identify the concept, relevant scope, timing or event, and important exclusions. Repeating a label or writing ‘status value’ gives a new reader almost no interpretive help.
Avoid circular wording
A useful definition answers what the concept is and what distinguishes it from the adjacent concepts a reader might confuse it with. Repeating the label back, as in tree identifier for tree_id, teaches nothing and can leave a reader concluding there was nothing to learn. Add the event or time basis wherever the value can change, because a status without a moment attached is ambiguous.
Add scope and timing
Labels such as status, value, code, date, or details are navigation aids, not definitions. The lint flags circular and very short text so an author can reconsider it.
Separate definition from procedure
Collection instructions belong in the source method, and formulas belong in the derivation, not in the definition. Keeping them apart lets a reader scan what the field means without wading through how it was produced, and lets an analyst find the calculation without reading prose. It also makes the definition survive a change of process, which is the part that usually changes first.
Worked example from the sample project
The sample's tree_id definition says it is a stable identifier assigned to one inventoried tree and then says what it is not, which is the part most definitions omit. Compare that with what a circular definition would look like: tree identifier. A reader learns nothing, and worse, they may conclude there was nothing to learn.
The trunk_cm definition does the other useful thing: it names the measuring basis, the circumference around the trunk at the survey team's stated height. A number labelled trunk_cm without that basis is ambiguous between at least two common measurements, and the ambiguity is invisible in the data itself.
What this does not do
- The lint flags circular and very short definitions; it cannot judge whether a definition is true.
- The studio never drafts, completes or rewords a definition for you.
- A well-written definition is still an authored claim, not a verified fact about the data.
Do this in the studio
Write what the concept is, what scope and timing apply, and what it excludes.
- Open the Field folios station and read your definition without the field name.
- Add the event or time basis wherever values can change.
- Move collection instructions to source or method and formulas to derivation.
Open the studio at the Field folios station