A missing observation must survive normalization as missing

Define the parser before accepting flexible inputs

Consider three hypothetical observations from SYNTHETIC_INDEX, measured in index points. Their source values are the strings 100, a dot and 0. The adapter contract accepts numeric representations and the selected provider's missing marker. It maps the dot to null, preserves numeric zero, and attaches a source-record locator. These values are a small software fixture, not published economic data.

A general language conversion function does not supply a data contract. In some contexts, coercing an empty string or a null value can produce zero; a failed parse can become a non-finite number. Neither behavior should silently define the dataset. State which tokens are accepted as missing, which are accepted as numbers and which produce a validation error requiring the caller to inspect the input.

A three-row arithmetic check exposes the difference

With normalized values [100, null, 0], there are two numeric observations out of three expected rows. If the analysis explicitly computes an available-case mean, it is (100 + 0) ÷ 2 = 50, with numeric coverage two thirds. If a careless parser substitutes zero for the missing row, the same mean code returns 100 ÷ 3, approximately 33.3333, and falsely reports complete numeric coverage.

Neither average should be selected merely because it is convenient. A complete-case rule might withhold the statistic until all expected values exist. An imputation model might produce an estimate but must label it separately and retain the original null. This example demonstrates the consequences of the parsing choice; it does not recommend one universal statistical treatment for every economic series.

Retain absence, identity and availability together

A present row containing null is also different from a missing row. The former says the response supplied an observation identity without a numeric value. The latter may reflect a query filter, a missing page, an upstream omission or a different coverage universe. Reconcile expected periods and pagination separately; do not manufacture placeholder rows and then label them as provider observations.

Attach source, series, observation period, unit, available_date, availability_basis, retrieved_at and revision_key to the null just as to a numeric record. A later revision may replace an earlier missing value, but it must become eligible according to the declared availability rule. Filling the historical null with the newest value before applying a cutoff would hide a revision and contaminate the earlier snapshot.

Test export and downstream boundaries

JSON export should preserve null as a distinct type. A CSV representation needs an explicit missing-value convention because a blank cell can mean several things to spreadsheet software. Keep the original payload and schema with the download: source_record is a locator, not a copy of the source value. A successful round trip should recover numeric zero as zero and missingness as missingness, without relying on a spreadsheet's cell display.

Inject malformed numbers, unrecognized strings and duplicate observation identities in separate tests. The adapter should report those defects rather than treating every inconvenience as missing data. FRED's observations documentation defines the selected response fields; the lab's validation rules are an inspectable implementation choice. Passing these fixtures establishes that the local parser follows its declared contract, not that every external dataset has complete, accurate or economically comparable observations.

Keep in the decision record

• Missing, zero, absent row and invalid value are separate states.
• Keep the original missing value even if a later analysis imputes an estimate.
• Test exports and coverage counts as well as the parser.

Source notes

1. FRED API V1: observations response and parameters

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