Parse numbers only after specifying their units

Declare the accepted input grammar

A provider may encode a numerical observation as a JSON number or a string. The FRED V1 observations documentation illustrates string-valued observations. An adapter should accept the documented representation and reject unexpected text rather than relying on a permissive parser that accepts the beginning of a malformed token.

For a synthetic fixture, decide whether spaces, exponent notation and leading plus signs are allowed. A token such as 12.3abc must not become 12.3 simply because a language utility reads its prefix. Keep the original token in the retained raw artifact, referenced by its source_record locator, and return a field-specific error when the token violates the declared numeric grammar.

Distinguish numerical value from display format

Suppose a synthetic series reports a rate of 4.5 in percent units. Its fractional representation is 0.045. Multiplying a USD 2 million amount by 4.5 would produce USD 9 million; multiplying by 0.045 produces USD 90,000. Both operations are valid arithmetic, but only one matches the intended rate convention.

The normalized record can preserve value 4.5 and unit percent, leaving conversion to an explicitly named calculation. Alternatively, a derived record can store 0.045 with unit fraction and a transformation note. Do not silently change the number while leaving the original unit label, or change the label while leaving the number unchanged.

Keep magnitude, currency and adjustment separate

An invented GDP-like value of 250 in USD billions represents USD 250,000,000,000. Another value of 250 in local-currency millions is neither numerically comparable nor directly convertible without an exchange-rate convention. Real versus nominal treatment and seasonal adjustment add further distinctions that a generic unit string may need metadata to explain.

A synthetic conversion test can start with 2.5 USD millions and expect 2,500,000 USD exactly under a decimal convention. Then test that the same transformation refuses EUR millions unless the caller supplies a declared currency conversion. Avoid treating all monetary series as interchangeable just because a chart displays the same currency symbol.

Choose numerical precision deliberately

RFC 8259 permits JSON numbers but does not give every implementation unlimited numerical precision. Its interoperability discussion identifies the familiar integer range that binary64 implementations can represent exactly. JSON Schema’s numeric constraints describe allowed values, while the application still needs a numerical representation suitable for its calculations.

For large integer identifiers, use strings because arithmetic is not their purpose. For exact financial decimal operations, specify a decimal or scaled-integer approach where needed. If the fixture tool uses ordinary finite numbers, state that limit. A demonstration adapter must not be advertised as an exact accounting system merely because its sample values happen to round cleanly.

Test conversions as reversible operations

Use independent examples for zero, negative values where permitted, very small magnitudes and boundary sizes. A rate-to-fraction conversion followed by its inverse should recover the source rate within the declared tolerance. A unit conversion should retain a trace of the source scale so a reviewer can reproduce it without guessing.

Reject non-finite computed results and impossible unit combinations before they reach a chart or export. Display rounding belongs at the presentation boundary; analytical records should retain the agreed precision. These checks establish consistent transformation of synthetic inputs. They do not establish that a provider’s original measure is economically appropriate for a particular investment decision.

Keep in the decision record

• Validate the whole numeric token, not only its parseable prefix.
• Preserve percentage, scale, currency and adjustment conventions.
• Declare precision and test conversions independently.

Source notes

1. FRED API V1 — Series observations
2. RFC 8259 — The JavaScript Object Notation Data Interchange Format, December 2017
3. JSON Schema — Numeric types

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