Keep zero, null, absence and request failure distinct

Write a missingness decision table

JSON Schema distinguishes null from a property that is not present. That distinction supports a practical adapter design: require essential identity fields, permit null only where the normalized contract deliberately allows it, and preserve a missing-value reason in surrounding diagnostics or source evidence.

A provider-specific missing token should be handled before numeric conversion. For a synthetic fixture, define a dot token as missing only if that matches the selected provider shape. An empty string, the word unavailable and a malformed number must not automatically receive the same treatment unless the contract explicitly says they are equivalent.

See the statistical consequence

Take three synthetic observations with values 10, null and 20. The mean of the two observed values is 15, with observed coverage of two out of three. Replacing null with zero produces a mean of 10. Neither number is simply a formatting choice; the second calculation adds an invented observation.

A defensible display can show mean 15, observed count 2, expected count 3 and coverage 66.667%, while explaining that no imputation was performed. If an analysis requires a complete panel, it can decline to calculate instead. The important choice is to make the rule explicit and keep it consistent across entities and periods.

A missing record is not the same as a null record

Suppose an expected three-year panel contains records for 2023 and 2025 but no record for 2024. That gap might reflect the query, provider coverage, pagination failure or genuine absence. A record explicitly reporting 2024 with null value supplies different evidence. Do not infer the cause of either state without checking the response and request scope.

Build an expected-key set from the declared analysis universe rather than assuming every calendar period must exist for every series. A monthly series and an annual series need different expectations. Mark unknown coverage separately from verified missing values so an incomplete download cannot masquerade as a complete sparse dataset.

Keep transport failure outside the observation table

A timeout or HTTP error means the request did not produce an accepted response. FRED’s error documentation describes status codes and an error body. Neither an error message nor an empty result created by exception handling should be converted into a valid observation with null value.

Consider a synthetic run with two successful pages and a third page returning an error object. The run is incomplete even if the first pages contain valid records. Preserve those pages as staged evidence, but do not publish a complete dataset or advance a completion checkpoint. Retrying and partial-data handling belong to the ingestion state machine, not to numerical imputation.

Make null behavior visible to downstream users

Specify how charts, CSV exports and calculations represent null. A blank CSV cell can be ambiguous without a schema or accompanying status column. A chart that connects points across a gap can suggest continuity that the data do not establish. Choose presentation behavior consistent with the analysis rather than relying on a library default.

Tests should include zero, null, absent value, malformed numeric text, empty page and provider error payload. Each should lead to its declared result. The fixture workbench demonstrates these distinctions using invented inputs; a live deployment needs provider-specific evidence that its missingness interpretation matches the actual endpoint and selected dataset.

Keep in the decision record

• Never replace null with zero by default.
• Separate missing observations from incomplete retrieval.
• Export coverage and missingness meaning alongside values.

Source notes

1. JSON Schema — Null reference
2. JSON Schema — Object reference
3. FRED API V1 — Errors

Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.

Continue the analysis