Label Grammar Rules Belong in Food API Contracts

The fresh signal: tiny label phrases changed structured food data

Two small Open Food Facts changes from the last few days point to a large design issue for recipe and food-data APIs.

On July 20, 2026, Open Food Facts merged a parser change to handle Swedish jam label wording such as fruktmängd Xg $fruit per 100g, with product examples for cloudberry and strawberry jam in the pull request notes. The change is narrow, but the implication is broad: a localized phrase on a label can encode a structured quantity, an ingredient identity, and a nutrition or composition basis at the same time. If an API treats that phrase as ordinary ingredient text, it loses the field builders actually need.

One day earlier, on July 19, Open Food Facts merged a taxonomy update for plural German ingredient forms to improve allergen detection. That is not just a translation improvement. It changes whether an ingredient mention can be connected to an allergen-relevant concept. On July 20, the project also restored nutrient taxonomy loading for Open Products Facts nutrition tables, after nutrient names failed to render because the relevant taxonomy was not included in the configured taxonomy fields.

The repeated angle this blog has already covered is taxonomy drift, stable localized IDs, allergen evidence, and nutrition validation. The new angle is lower in the stack: before an API can return stable entities, warnings, or nutrient totals, it must parse label grammar. Language-specific patterns such as "fruit content X g per 100 g," plural ingredient morphology, and taxonomy-backed nutrient labels should be versioned extraction rules with test coverage and client-visible provenance.

Thesis: recipe, nutrition, grocery, and food-AI APIs should expose the grammar rules that turn label text into structured facts as governed data assets, because these rules determine ingredient quantities, allergen matches, nutrition display, confidence, and regression risk.

Why label grammar is different from keyword extraction

Keyword extraction asks, "Did the text mention strawberry?" Label grammar asks, "What fact did this phrase assert, and on what basis?" That difference matters for API builders.

Consider a Swedish jam label phrase like fruktmängd 45g jordgubbar per 100g. A naïve text pipeline might extract jordgubbar as strawberries and stop. A better pipeline recognizes at least four structured facts:

• the phrase is a fruit-content declaration, not just an ingredient list item;
• the ingredient is strawberry, expressed in Swedish and possibly inflected;
• the quantity is 45 g;
• the basis is per 100 g of product.

Those facts can drive product features that a keyword match cannot support: fruit percentage filters, jam quality comparisons, ingredient-ratio displays, substitution logic, and nutrition plausibility checks. If a meal-planning app recommends a jam for baking, fruit-content data can be a useful quality signal; if it only stores free text, that signal disappears.

The German plural ingredient change points to the same problem from the safety side. An allergen detector that recognizes a singular canonical term but misses common plural forms does not merely reduce search recall. It can under-detect risk. Morphology, compound words, punctuation, and localized wording are part of the data contract whenever the API promises ingredient normalization, allergen flags, or dietary exclusion.

The API consequence: extraction rules need identities

Most food APIs expose extraction output but not the extraction rule. That is convenient until a rule changes. When a new localized pattern lands, historical records may suddenly produce different quantities, ingredient entities, allergens, or display labels. Without rule identity, clients cannot answer basic operational questions:

• Did this product change because the source label changed or because the parser improved?
• Which records were affected by a new grammar rule?
• Can we reprocess only products whose language and field patterns match the rule?
• Should a frontend show a newly extracted value as high confidence or pending review?
• Did a safety-related allergen flag appear from a declared allergen field, an ingredient morphology rule, or a model guess?

A practical API need not expose every internal expression. It should expose enough provenance for downstream teams to reason about changes. The extraction layer should have named rules, versions, input fields, locale scope, output facts, confidence, and review state.

{
  "sourceText": "fruktmängd 45g jordgubbar per 100g",
  "sourceLocale": "sv-SE",
  "extractedFacts": [
    {
      "factType": "ingredient_quantity",
      "ingredient": {
        "entityId": "ingredient:strawberry",
        "label": "jordgubbar",
        "matchType": "localized_plural"
      },
      "amount": 45,
      "unit": "g",
      "basis": {
        "amount": 100,
        "unit": "g",
        "scope": "product"
      },
      "evidence": {
        "field": "ingredients_text",
        "span": "fruktmängd 45g jordgubbar per 100g",
        "ruleId": "sv-fruit-content-per-100g",
        "ruleVersion": "2026-07-20",
        "sourceUrl": "https://github.com/openfoodfacts/openfoodfacts-server/pull/14026"
      },
      "confidence": 0.93,
      "reviewStatus": "parser_rule"
    }
  ]
}

The important design choice is that the structured value and the rule that produced it travel together. Clients can still request a simple view, but the detailed view lets teams debug, audit, and selectively reprocess.

Failure modes when grammar is hidden

Hidden grammar rules create bugs that look random to product teams. In practice, they cluster into predictable failure modes.

Failure mode	Example symptom	API design fix
Quantity becomes text	Fruit content appears only in the ingredient string	Extract quantity facts with basis and source span
Locale-specific wording is ignored	Swedish or German products normalize worse than English products	Scope rules by locale, field, and taxonomy version
Morphology breaks safety matching	Plural ingredient forms miss an allergen concept	Store match type and vocabulary evidence for allergen decisions
Parser changes look like source changes	A product appears to change even though the label did not	Include rule IDs and extraction timestamps
Frontends over-trust inferred values	UI displays "contains 45% strawberry" with no caveat	Return confidence and review status
Reprocessing is all-or-nothing	A small rule update requires a full catalog rebuild	Index records by candidate rule scope
Tests miss local label grammar	English examples pass while regional labels fail	Maintain multilingual fixture sets tied to rules

These issues are especially costly for recipe APIs because recipe products often blend unstructured recipe text, packaged product records, grocery catalogs, user pantry items, and AI-generated substitutions. The extraction grammar determines whether those sources can be compared on the same axis.

Product decisions for API builders

1. Separate declared composition from inferred ingredients

A fruit-content declaration is not the same as an ingredient mention. If a label says a jam contains 45 g strawberry per 100 g, the API should not flatten that into a generic ingredient quantity without preserving the declaration type. In recipe search, "has strawberry" and "contains at least 40% strawberry by product weight" are different filters.

A useful model distinguishes:

• ingredient_mentions: what the text says;
• normalized_ingredients: canonical entities matched from the text;
• composition_claims: declared ratios, percentages, or per-basis quantities;
• nutrition_values: nutrient amounts on a defined basis;
• quality_flags: parser or validation warnings.

That separation lets product managers decide whether to expose composition as a premium filter, a ranking feature, a grocery-quality badge, or an internal matching signal.

2. Treat grammar updates as data migrations

When a new rule extracts more structure from existing labels, it is tempting to deploy it like a bug fix. For downstream API consumers, it behaves more like a data migration. Search results can change. Allergen flags can appear. Facets can gain counts. Recommendation features can shift.

A safer rollout pattern is:

1. add the rule behind a versioned extractor;
2. run it against a sample of historical records;
3. measure changed facts, not just parser success;
4. review high-impact categories such as allergens and health claims;
5. publish the rule version in metadata;
6. reprocess eligible records with an audit trail.

For API customers, the most useful changelog is not "improved Swedish parsing." It is "added sv-fruit-content-per-100g, which may create composition_claims for Swedish fruit products when label text matches fruktmängd ... per 100g."

3. Keep taxonomy and grammar coupled, but not identical

The Open Products Facts nutrition-table fix is a reminder that taxonomy configuration is infrastructure. If nutrient taxonomy fields are not loaded, display and interpretation can break even when numeric data exists. Grammar rules need taxonomy concepts to produce useful facts, but taxonomy availability and parser behavior should remain separately observable.

A parser might correctly detect a nutrient phrase but fail to resolve the nutrient concept because a taxonomy is missing, outdated, or not loaded in a specific product context. The API should represent that as a partial extraction, not silently drop the fact:

{
  "factType": "nutrient_label",
  "rawLabel": "fiber",
  "entityId": null,
  "status": "unresolved_taxonomy",
  "taxonomy": {
    "name": "nutrients",
    "loaded": false
  }
}

This is more useful than returning nothing. It tells operators whether to fix parser grammar, taxonomy coverage, or deployment configuration.

4. Design client behavior for confidence tiers

Not every extracted fact deserves the same UI treatment. A human-declared nutrition table, a rule-based composition claim, an inferred plural ingredient match, and an AI guess have different risk profiles.

A simple decision framework:

Confidence tier	Example source	Suggested product behavior
Declared	Nutrition table or explicit composition claim on the package	Display normally with source attribution
Rule-extracted	Locale-specific grammar rule with tests	Display with provenance in detailed views; use for ranking if validated
Taxonomy-inferred	Ingredient term or plural form mapped to canonical entity	Use for search and warnings; avoid absolute safety claims without stronger evidence
Model-inferred	OCR or LLM extraction without human review	Gate high-risk claims; queue review for allergens, medical filters, or compliance fields
Unresolved	Text recognized but taxonomy or basis missing	Preserve raw text and suppress strong claims

This gives API consumers a contract they can implement consistently instead of guessing from a single boolean.

Validation questions before shipping a food extraction feature

Use these questions when adding a parser, buying a food-data API, or exposing new normalized fields:

• Does each extracted fact include the original text span and source field?
• Are locale, script, and regional wording part of the rule scope?
• Can the API distinguish ingredient mentions, composition claims, nutrient labels, and allergen evidence?
• Does the response include rule ID, rule version, taxonomy version, and extraction timestamp?
• Are plural forms, compounds, abbreviations, and unit variants covered by fixtures?
• Can clients tell whether a value is declared, rule-extracted, taxonomy-inferred, model-inferred, or unresolved?
• Is there a targeted reprocessing plan when a rule changes?

Where Recipe API positioning is natural

For developers and technical buyers, the question is whether the provider can explain how messy food language becomes structured data. Locale-specific label grammar, taxonomy resolution, confidence, and provenance determine whether a product can safely support substitutions, nutrition filters, pantry matching, allergy-aware planning, and generated recipe validation.

A Recipe API integration should keep the default response clean while exposing enough evidence and version metadata to debug changes, write trustworthy UI copy, and decide when to reprocess data.

Sources

• Open Food Facts pull request, merged July 20, 2026: feat: handle sv:"fruktmängd Xg $fruit per 100g".
• Open Food Facts pull request, merged July 19, 2026: taxonomy: plural ingredients in German for better allergen detection.
• Open Food Facts pull request, merged July 20, 2026: fix: restore nutrition table in OPF.