Nutrition API contracts: unknown nutrients should not become measured zeros

An unknown nutrient should not become a measured zero merely because the API needs a number. Preserve availability separately from numeric validity, then carry that distinction through editing, saving and aggregation. A zero can be a legitimate supplied value; null should identify a value that is not known under the contract.

Start by documenting each field’s unit and measurement basis. A nullable fiber value per serving is not equivalent to zero fiber per 100 grams. This guide addresses data fidelity, not nutrition recommendations. Use fictional foods when testing and preserve whether a number came from a label, catalog or application estimate.

Inspect coercion before trusting the type

USDA FoodData Central documents several data types with different origins, including analytical data and manufacturer label information. That provenance matters when interpreting coverage. A uniform application shape should not imply that every provider supplies every nutrient at the same precision or through the same method.

USDA: FoodData Central data-type documentation

The reviewed UltraFit360 serializer has finite-number and nullable-number paths. A safe isolated execution of that source showed a fictional payload with calories 120, protein_g null and fiber_g null becoming protein 0 while fiber remained null. The result is a concrete boundary to review; it does not support claiming that the current contract preserves every unknown nutrient.

Separate missing input from invalid input

JavaScript Number coercion can accept values the product did not intend. A nullable type annotation does not make blank strings or whitespace unknown. Define an explicit empty-input rule before numeric conversion, reject nonfinite values and decide whether numeric strings are permitted. Keep a validation error distinguishable from a legitimate absent provider field.

Proposed value contract:
{ "value": null, "unit": "g", "availability": "unknown" }
{ "value": 0, "unit": "g", "availability": "supplied" }

The proposed contract can be represented with nullable columns or a richer object; the important point is retained meaning. An explicit zero alcohol value, for example, should remain numeric zero rather than becoming absent through a truthiness check. That example is illustrative; the executed current helper fixture did not include an alcohol field.

A partial total needs its coverage

If two fictional ingredients have known fiber and a third has unknown fiber, adding only known values yields a known subtotal. It is not proof of the recipe’s complete fiber total. Store or derive the number of contributing ingredients and an incomplete flag. The UI can show a subtotal with coverage or an unavailable full total according to the feature’s needs.

Scaling a portion should keep unknown multiplied by a factor unknown. Do not let a generic arithmetic helper convert it to zero before saving. Reopen the editor after serialization and verify that unknown fields remain correct; testing only the first preview screen misses persistence defaults.

Make corrections reversible and inspectable

When a user supplies a missing value, record the correction and its measurement basis. Distinguish a user-entered zero from clearing the field back to unknown. If the original catalog record changes later, decide whether existing logs keep their saved snapshot or adopt the correction explicitly.

The executed fixture loads only the pure TypeScript serializer, with its type import erased, and uses no APIs or real records. It establishes the outputs in the table, not complete app behavior. Acceptance still needs UI blanks, explicit zeros, numeric strings, nonfinite inputs, portion edits and partial totals tested across the actual API boundary.

Coverage also belongs in exports. An empty CSV cell, a literal zero and a textual unavailable marker can be interpreted differently by downstream tools. Define the export contract and verify a round trip with a fictional row before offering it to another system. If the destination cannot represent unknowns, disclose that loss explicitly or choose a different field representation. Avoid allowing a spreadsheet default or database coercion to decide nutrient meaning after the application preserved it correctly.

Ai food logging accuracy ux

Building ultrafit360

Bring one client-to-coach workflow, current data contract and acceptance constraint to discuss a bounded fitness product build or integration pilot.

Explore health fitness app development