How Can a Schema Describe Optional Data?
From the earlier reference collection. Read the current software blog.
A useful schema says which fields may be absent and gives omission and null distinct, predictable meanings.
Optional should answer a real question
A field is optional when a valid record may leave it out under stated conditions. This is different from saying the field is optional for the publisher to document. For a station record, platform_accessibility might be absent for older records because the property has not been collected, while the rest of the record remains valid.
The schema should make that condition visible to both people and validators. If a field is always expected but its value may be unknown, the field may be required while its value is allowed to be null. These choices produce different client behavior.
Define omission and null separately
In JSON, omission means the key does not appear. Null means the key appears with an explicit null value. A practical contract might say omission means the property is outside the scope of this record, while null means it applies but the value is not known. Another API may use these states differently; consistency and documentation matter more than one universal interpretation.
For example, a reading may always include quality_code, but use null when the instrument has not supplied a code. If the API omits quality_code entirely for a class of devices, clients can recognize that the field is unsupported for those records.
Help clients validate safely
For every optional property, describe its type, when it may be missing, whether null is allowed, and what a client should infer in each case. Provide examples of both a record with the property and one without it. Do not rely on clients to infer omission rules from a few observed responses.
Consumers should check for key presence before reading a value and handle null before applying operations. A numeric calculation that assumes a missing value is zero may produce a plausible but false total.
Treat changes as compatibility work
Making a previously required field optional can affect client assumptions, even if existing records still contain it. Adding a field is often manageable, but some strict clients reject unknown properties. Explain how the schema evolves and provide advance notice for changes that alter existing meanings.
A good optionality rule lets publishers represent incomplete reality without disguising it. It also gives clients a clear path to preserve uncertainty, show an appropriate message, and avoid fabricating a value.