How Can Documentation Distinguish Required and Optional Fields?
From the earlier reference collection. Read the current software blog.
Presence labels help readers validate data only when they are explicit, consistent, and accompanied by conditions that explain when a field is necessary.
Choose clear presence labels
Mark each field as required, optional, or conditionally required in a predictable place, such as a table column. Define those labels once. “Required” should mean the field must be present for a valid record; “optional” should mean it may be absent without invalidating that record. Avoid relying on typography, ordering, or an unspoken convention that experienced users are expected to infer.
Distinguish an absent field from a present field with an empty value. A format may require a column header while allowing some rows to leave its cells blank. Document both rules. For example, “The station_id column must exist; its value may be empty only for records marked as unassigned.” This precision helps validators avoid rejecting valid input or accepting incomplete records.
Write down the conditions
For a conditionally required field, state the condition in testable terms. “Required when relevant” merely restates the uncertainty. Better: “end_time is required when interval_type is bounded; it must be omitted when interval_type is open.” If the condition depends on another field, identify that field and its allowed values. If several conditions apply, use a decision table or short examples.
Also explain dependencies between fields. A coordinate may be optional for a general record but required when a location is classified as geographic. A unit may be mandatory when a numeric measurement appears, even if the measurement itself is optional. These relationships belong in field documentation as well as in any schema or validation rules, so readers can understand why a record fails.
Show valid and invalid cases
Pair the labels with compact examples. Show a complete record, a valid omission, and a condition that makes the field necessary. Mark examples as illustrative if they do not represent real records. If a value can be null, blank, omitted, or a sentinel, define each behavior rather than treating the words as interchangeable. State how clients should handle unknown or not-applicable values.
Consider a contact field required only for organizations that accept public inquiries. The reference should say which organization types trigger that condition and what representation is valid when contact details are unavailable. A validator can then produce a useful error such as “contact_url is required when audience is public,” rather than a generic missing-field message. Review labels whenever the schema changes; a stale table can contradict the software and create inconsistent implementations.