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.
- Schema:
/schemas/nutrition-record-v1.json(JSON Schema, Draft-07) - Sample payload:
./nutrition-record.sample.json - Extraction prompt (reuse for your own AI pipeline):
../prompts/nutrition-extraction.md
1. Where records live
Records are stored via the SmartLinks SDK in SL.app.records with:
recordType: 'nutrition'ref: one ofproduct:<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.
- Per-100 only. Every value in
nutrientsandvitaminsAndMineralsis per 100 g forproductType: foodor per 100 ml forproductType: beverage. If the source label is per-serving, convert it:per100 = perServing * (100 / servingSize). - Use
nullfor unknown. Do not invent values, do not use0, do not omit the key — emitnull. - Salt vs sodium.
saltis grams per 100;sodiumis 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. - Energy. Provide both
energyKjandenergyKcalwhen possible. Conversion:1 kcal = 4.184 kJ. - EU vs US sugar fields.
sugarsis the EU "of which sugars" line.totalSugarsandaddedSugarsare the US lines. Populate whichever applies — extras are ignored, never rejected. - Units for vitamins/minerals are fixed per field (see schema descriptions). µg means micrograms.
productTypedrives traffic-light thresholds (different cutoffs for beverages). Pick the right one or the UK label will misrender.healthClaims[].validatedmust betrueonly if your generator actually checked the regulator's threshold for that claim. When in doubt, setfalse.
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.