For developers

    Nutrition Record — Integrator Guide (v1)

    This app stores one nutrition record per product (or per facet value). A third-party tool — for example, an AI assistant generating nutrition data from a product description — can write records that the app will render natively, provided it follows this contract.


    1. Where records live

    Records are stored via the SmartLinks SDK in SL.app.records with:

    • recordType: 'nutrition'
    • ref: one of
      • product:<productId> — per-product nutrition (takes precedence)
      • facet:<facetKey>:<facetValue> — fallback for a facet bucket (e.g. all "Cabernet Sauvignon" wines)

    Resolution order at render time: per-product wins over per-facet.

    Never write nutrition data to appConfiguration.products[productId] — that path is unsupported.

    2. The payload

    The record body is a single JSON object validated by nutrition-record-v1.json. Top-level shape:

    {
      "productType": "food" | "beverage",
      "serving":    { "servingSize": 30, "servingSizeUnit": "g", ... },
      "nutrients":  { "energyKcal": 480, "fat": 25, ... },     // per 100 g/ml
      "vitaminsAndMinerals": { "calcium": 120, ... },           // optional, per 100 g/ml
      "healthClaims": [ ... ],                                  // optional
      "lastUpdated": "2026-05-17T10:00:00Z"                     // optional
    }
    

    3. Rules an AI must follow

    These are the rules that trip up most generators. Bake them into your prompt or post-processor.

    1. Per-100 only. Every value in nutrients and vitaminsAndMinerals is per 100 g for productType: food or per 100 ml for productType: beverage. If the source label is per-serving, convert it: per100 = perServing * (100 / servingSize).
    2. Use null for unknown. Do not invent values, do not use 0, do not omit the key — emit null.
    3. Salt vs sodium. salt is grams per 100; sodium is milligrams per 100. Conversion: salt(g) = sodium(g) * 2.5, i.e. salt(g) = sodium(mg) / 1000 * 2.5. Provide whichever the source gives; both is fine.
    4. Energy. Provide both energyKj and energyKcal when possible. Conversion: 1 kcal = 4.184 kJ.
    5. EU vs US sugar fields. sugars is the EU "of which sugars" line. totalSugars and addedSugars are the US lines. Populate whichever applies — extras are ignored, never rejected.
    6. Units for vitamins/minerals are fixed per field (see schema descriptions). µg means micrograms.
    7. productType drives traffic-light thresholds (different cutoffs for beverages). Pick the right one or the UK label will misrender.
    8. healthClaims[].validated must be true only if your generator actually checked the regulator's threshold for that claim. When in doubt, set false.

    4. Writing a record (SDK)

    upsert takes positional (collectionId, appId, body, admin). Pass a scope (server derives the ref) or a facetRule — they are mutually exclusive — and put the nutrition payload under data:

    import * as SL from '@proveanything/smartlinks';
    
    // Per-product record (most specific — wins over any matching rule)
    await SL.app.records.upsert(
      collectionId,
      appId,
      {
        recordType: 'nutrition',
        scope: { productId },          // server derives ref `product:<id>`
        data: nutritionRecord,         // matches nutrition-record-v1.json
      },
      true,                            // admin write — required
    );
    

    Rule variant — target a group of products by facets (do not hand-build facet:key:value refs; pass a facetRule):

    await SL.app.records.upsert(
      collectionId,
      appId,
      {
        recordType: 'nutrition',
        facetRule: { all: [{ facetKey: 'varietal', anyOf: ['cabernet-sauvignon'] }] },
        data: nutritionRecord,
      },
      true,
    );
    

    Read back with SL.app.records.match(collectionId, appId, { target: { productId, facets }, strategy: 'best', recordType: 'nutrition' }).

    5. Validating before you write

    Any Draft-07 JSON Schema validator works. Example with Ajv:

    import Ajv from 'ajv';
    import addFormats from 'ajv-formats';
    import schema from './nutrition-record-v1.json' assert { type: 'json' };
    
    const ajv = addFormats(new Ajv({ allErrors: true }));
    const validate = ajv.compile(schema);
    if (!validate(record)) throw new Error(JSON.stringify(validate.errors, null, 2));
    

    6. Versioning

    This is v1. Breaking changes will ship under a new file (nutrition-record-v2.json); the v1 schema URL will keep working. New optional fields may be added to v1 without notice — additionalProperties: false blocks unknown keys, so generators should ignore (not echo) fields they don't recognise.