Key takeaway
A validator can check the representation. The field contract must explain why a value is absent and what the reader may infer from it.
A blank cell is not a business definition
A spreadsheet can render a missing measurement, an empty string and a suppressed field as equally blank cells. A later export may replace all three with zero. The result is easy to calculate and impossible to interpret correctly. Before preparing it, decide which source states must remain distinguishable for the intended question.
JSON Schema’s documentation distinguishes null from an absent property, and shows that false, zero and an empty string are different values. Its object reference also explains that defining a property does not make it required. These rules can enforce a declared representation; they cannot decide what an unknown business value means.
A hypothetical field-state contract
A fictional service export contains a numeric downtime_minutes field. The recipient wants to compare recorded durations while retaining cases that have no approved duration evidence. The owner uses a value plus a reason, rather than reserving zero as a catch-all missing marker.
The following contract is an original illustration. The source system and proposed task must justify the states; they are not a universal standard. A redacted value remains a redacted value even when the actual number is known internally.
| Business state | Export representation | Permitted inference | Validation decision |
|---|---|---|---|
| Observed zero | 0; duration_status observed | Recorded duration is zero in stated unit | Accept numeric zero |
| Not recorded | null; duration_status not_recorded | Source has no duration evidence | Accept declared unknown |
| Outside scope | null; duration_status out_of_scope | No duration claim; outside stated population | Accept declared out-of-scope state |
| Withheld by review | null; duration_status withheld | No released duration claim | Do not impute zero |
| Accidental empty text | Empty string | No defined numeric meaning | Reject or route to correction |
Test presence and value type independently
If every record must explicitly state whether duration was supplied, make the status field required. If the numeric field permits unknowns, its schema must allow the chosen representation. A required numeric property can still reject null if null is not an allowed type. Presence alone does not establish a valid measurement.
Create a small fixture set with an observed zero, positive value, null with each permitted reason, omitted property, empty string, false and a number encoded as text. Record the expected result for each fixture before running a validator. If a CSV step changes the states, test the full path rather than only the final JSON object. The fixture documents a contract someone else can challenge.
For the illustrated contract, require both downtime_minutes and duration_status. Allow a number when status is observed; allow null only with a stated unknown, withheld or out-of-scope reason. Reject observed plus null and unknown plus zero. Write those cross-field conditions explicitly: allowing two field types independently would still admit contradictory combinations.
W3C’s tabular-data model separates a cell’s original string from its semantic value and lets metadata identify null markers. That distinction matters when a JSON object passes through CSV. Confirm that the actual exporting and importing tools preserve your conventions; citing the model does not make every spreadsheet or parser follow it.
Report missingness on a defined population
In a hypothetical review of 100 jobs, 70 have observed durations, 15 are not recorded, 10 are withheld and five are outside the stated duration scope. All 95 in-scope jobs belong in an in-scope completeness measure: 70/95, or about 73.7%. If the review instead covers only the 85 jobs eligible for the proposed release, excluding the 10 withheld jobs as well, 70/85 is about 82.4%. Name that narrower population and report both exclusions. Neither statistic is a repair-success rate.
Reason codes also prevent an unhelpful remediation plan. Investigating an absent source value differs from seeking permission for a withheld value. A documented out-of-scope field may need no repair at all. Assign each category to the owner who can actually resolve it and keep unknown reasons visible where the system cannot supply an explanation.
Preserve meaning through the handoff
For this example, zero remains a valid recorded number; unknowns remain null with reasons; empty text fails the numeric contract. The release dictionary states those choices and includes synthetic fixtures. A recipient can inspect the structure without receiving actual job records. That is a useful first evaluation of representation, not evidence of real archive completeness.
Use inventory to document the field states and readiness to assign undefined conventions. Before delivery, rerun the fixtures across extraction, transformation and serialization and preserve the package version. Do not silently fill gaps to improve a completeness percentage. If a later buyer use needs different states, review that change and its permissions instead of relying on an old dictionary.