Volume-to-Weight Conversion Is a Recipe Data Contract

The trend: recipes are forcing product databases to understand kitchen units

A quiet but important Open Food Facts change landed on August 6: the project added early support for ingredient density so volume quantities can be converted to grams, specifically noting recipe ingredients such as "500ml of milk" as the use case. The same day, Open Food Facts Server release 2.100.0 listed that work as a feature. Two nearby taxonomy changes make the point sharper: August 4 edits introduced a "Condiment pastes" category, added "Masala pastes," and marked "Spice blends" and "Condiment pastes" as incompatible; August 5 edits added a "Pad Thai sauce" category and an agribalyse_food_code property to Asian sauce categories.

Individually, these look like ordinary taxonomy and parser maintenance. Together, they describe a data-contract problem that recipe API builders cannot solve with a single quantity: 500, unit: "ml" field. Meal planning, nutrition analysis, grocery fulfillment, and cost-per-serving features all eventually need to answer: how much edible matter is this ingredient, what state is it in, which food identity should receive the nutrition profile, and how confident are we that the conversion applies?

The thesis for this post: volume-to-weight conversion should be a first-class, evidence-backed API contract that combines unit parsing, ingredient identity, density provenance, preparation state, category compatibility, and downstream use-case boundaries. If it is treated as hidden math inside a nutrition calculator, the failures will surface as wrong nutrients, wrong grocery quantities, bad substitutions, and hard-to-debug customer disputes.

Source map

Fresh primary evidence from the last seven days:

• Open Food Facts Server commit b5ac5de, August 6, 2026: "add density to ingredients for volume quantity conversions to g - WIP," explicitly calling out recipe ingredients listed by volume and noting that common recipe units still need support.
• Open Food Facts Server release 2.100.0, August 6, 2026: includes the density feature in the release notes, alongside a Forest Footprint matching fix.
• Open Food Facts taxonomy commit 8ca12b8, August 4, 2026: adds "Condiment pastes" and "Masala pastes," and declares "Spice blends" and "Condiment pastes" incompatible.
• Open Food Facts taxonomy commit 15ae2dc, August 5, 2026: adds a "Pad Thai sauce" category and agribalyse_food_code metadata to Asian sauce categories.

Why density is not just a unit-conversion table

Most recipe systems start with a simple model:

{
  "name": "milk",
  "quantity": 500,
  "unit": "ml"
}

That is adequate for display. It is not adequate for computation. Nutrition databases, carbon datasets, cost-per-serving engines, and many grocery matching systems usually normalize to mass. Turning 500 ml of milk into grams requires more than recognizing ml:

1. The parser must know that the unit is volume, not count or weight.
2. The ingredient resolver must choose an identity, such as whole milk, oat milk, condensed milk, or powdered milk reconstituted with water.
3. The density record must apply to that identity and preparation state.
4. The API must expose whether the conversion was exact, inferred, defaulted, or impossible.
5. Downstream features must know whether they may use the converted mass for nutrition, grocery purchasing, or regulatory-style display.

The Open Food Facts note that the feature is WIP and still needs common recipe units is important. Kitchen volumes are not only milliliters and liters. They include teaspoons, tablespoons, cups, fluid ounces, cans, jars, bunches, cloves, slices, sticks, packets, and "to taste." Some are formal volumes; some are packaging or culinary conventions; some are ingredient-specific aliases. A tablespoon of oil can be normalized by volume. A tablespoon of chopped parsley combines volume, cut size, packing density, and user behavior. "One cup grated cheese" is not the same operational problem as "one cup milk."

For Recipe API customers building apps, this means density support should not be sold as a universal solve. It should be exposed as a capability with scope.

A practical schema sketch

A robust ingredient quantity object can separate the observed recipe text from normalized computation fields:

{
  "ingredient_line": "500 ml milk",
  "parsed_quantity": {
    "value": 500,
    "unit": "ml",
    "unit_dimension": "volume",
    "parser_version": "2026-08-06"
  },
  "ingredient_identity": {
    "id": "ingredient:milk",
    "label": "milk",
    "match_confidence": 0.92,
    "matched_terms": ["milk"]
  },
  "preparation_state": {
    "form": "liquid",
    "temperature": null,
    "processing": null
  },
  "density_conversion": {
    "status": "converted",
    "grams": 515,
    "density_g_per_ml": 1.03,
    "source": "ingredient-density-table",
    "source_version": "2026-08-06",
    "confidence": "standard",
    "warnings": []
  },
  "allowed_uses": {
    "nutrition_estimate": true,
    "grocery_quantity": true,
    "label_claim": false
  }
}

The values above are illustrative, but the fields are the point. The conversion result needs status, provenance, confidence, and allowed use. Without those fields, a client cannot tell the difference between a known density, a category-level default, a guessed substitution, and a failed conversion masked as zero.

Category compatibility matters for conversion

The August 4 Open Food Facts taxonomy change that distinguishes condiment pastes from spice blends is directly relevant. Consider these two recipe lines:

• 2 tbsp masala paste
• 2 tbsp garam masala

They share a cuisine-adjacent term and a spoon measure, but they do not share a density model. A paste is a wet or semi-solid preparation. A spice blend is usually dry. If a taxonomy treats both as near synonyms, a recipe API may apply an inappropriate density, produce inflated nutrient estimates, or map the item to the wrong grocery product.

The incompatible_with relationship is useful because it gives API designers a pattern: do not only create parent-child categories; also model negative constraints. Negative constraints help when names overlap, when translations blur distinctions, or when a large language model proposes a plausible but wrong normalization.

A recipe API can expose category constraints like this:

Signal	Example	API consequence
Parent category	condiment pastes	Eligible for wet/semi-solid density defaults
Incompatible category	spice blends	Do not inherit dry spice conversion rules
Cuisine-specific child	masala pastes	Prefer paste grocery matches over powder blends
Evidence	taxonomy version and matched text	Let clients audit why the rule fired

This becomes especially important in grocery workflows. A shopping list that turns 2 tbsp masala paste into a jar of curry paste is useful. One that turns it into a dry spice jar because of a shared word is a product failure.

Metadata links turn identity into computation

The August 5 Asian sauce taxonomy edit added an agribalyse_food_code property. That kind of property is not merely editorial metadata. It is a bridge from an ingredient or product category to an external food-composition, environmental, or reference dataset. Once a recipe API follows that bridge, category identity affects more than search filters. It affects emissions estimates, nutrition fallback, sustainability labels, and product comparison.

That raises an API design requirement: reference-code mappings should be versioned and scoped. A sauce category with an external code may be suitable for a sustainability estimate, but not precise enough for sodium calculation or allergen handling. A Pad Thai sauce category may group products with fish sauce, soy, peanuts, tamarind, sugar, and stabilizers. The category can help rank grocery matches; it should not silently replace product-level composition when exact branded data is available.

Good APIs distinguish:

• product-specific nutrient facts;
• ingredient-level generic nutrition;
• category-level fallback nutrition;
• external reference-code mappings;
• computed recipe totals derived from any of the above.

Each layer should carry provenance. Otherwise, customers cannot explain why the same recipe changed after a taxonomy release.

Failure modes to design for

Volume-to-weight normalization tends to fail in predictable ways:

1. Wrong identity: "cream" could mean dairy cream, coconut cream, cream cheese, or a cosmetic product in product datasets.
2. Wrong form: chopped, packed, melted, sifted, dried, powdered, and reconstituted forms can have different densities.
3. Wrong unit semantics: "cup" may be a formal volume, a serving vessel, or a package count depending on context.
4. Locale drift: tablespoons, cups, decimal punctuation, and ingredient names vary by region and language.
5. Category collision: pastes, sauces, powders, blends, and condiments often share cuisine terms but not physical behavior.
6. Overconfident fallbacks: category-level density may be fine for meal-planning estimates but not for clinical nutrition or compliance-heavy products.
7. Invisible model updates: a taxonomy or density table change can alter historic recipe nutrition unless results are pinned to versions.

The operational trade-off is between convenience and auditability. Product managers want automatic nutrition totals. Developers need deterministic behavior. Technical buyers want to know whether numbers are stable enough for their use case. The API should support all three by making uncertainty explicit.

Implementation checklist for API builders

Before exposing density-backed conversions, ask these validation questions:

• Do ingredient quantity responses preserve the original text, parsed unit, normalized unit, and parser version?
• Are mass, volume, count, package, and informal units represented as different dimensions?
• Can density be attached at ingredient, product, category, and preparation-state levels?
• Does each conversion include provenance, version, confidence, and warnings?
• Are category incompatibilities represented, not just category hierarchies?
• Can clients request strict behavior, such as fail_on_inferred_density=true?
• Are converted totals pinned so historic recipes do not change silently after taxonomy updates?
• Do nutrition, grocery, cost, and sustainability endpoints expose different allowed-use rules?
• Is there a review workflow for high-impact density or taxonomy changes?
• Can support teams trace a surprising total back to the ingredient line, density source, and category mapping?

The strict-mode option is worth emphasizing. Some applications would rather return "nutrition unavailable for 3 ingredients" than publish a polished but misleading calorie number. Others, such as casual meal planners, can tolerate estimates if confidence is visible. One conversion engine can serve both if the contract separates result status from display formatting.

Product implications for recipe API evaluation

For founders and technical buyers comparing recipe APIs, density support should become a procurement question. Ask vendors for examples involving liquids, powders, chopped herbs, pastes, sauces, and ambiguous cuisine terms. Ask whether conversions are deterministic across versions. Ask how the API reports partial failure. Ask whether grocery quantities and nutrition quantities are derived from the same normalized ingredient record or from separate black boxes.

The strongest platforms will not claim perfect conversion. They will show their evidence model. They will expose why 500 ml milk became grams, why 2 tbsp masala paste did not inherit spice-blend rules, and why a sauce category can contribute a sustainability reference while product-level nutrition remains preferred.

That is the useful lesson in this week's Open Food Facts changes. Recipe data is becoming more computable, but computation increases the cost of vague contracts. Density, taxonomy compatibility, and external reference codes belong in the API surface because they change business outcomes: recipe recommendations, cart quantities, nutrition totals, sustainability estimates, and customer trust.

Sources

• Open Food Facts Server commit, August 6, 2026: feat: add density to ingredients for volume quantity conversions to g - WIP
• Open Food Facts Server release commit, August 6, 2026: release 2.100.0
• Open Food Facts taxonomy commit, August 4, 2026: taxonomy(food): condiment paste edits
• Open Food Facts taxonomy commit, August 5, 2026: taxonomy(food): Asian sauce category edits