The Data Dictionary

How these docs are layered

Platform Data Contract — Field-by-Field Data Dictionary

Contract: biology-as-code/platform-data/v1 (JSON Schema draft-07) — the single payload shape all four views read.

Top-level required sections: manifest, outcomes. additionalProperties: false at the root — no unknown top-level keys.

Optional sections: lexicon, records, associations, feed, mechanisms, promises.

How this schema is generated (and why it cannot drift): export_contract.py builds platform-data.schema.json programmatically. Enums are pulled live from outcome_schema.py (enum = lambda E: sorted(e.value for e in E)), and the full-fidelity StudyRecord shape is embedded verbatim from pydantic's own StudyRecord.model_json_schema(ref_template="#/$defs/{model}") into $defs. Because the contract is emitted from the same code that validates the data, the documented shape and the enforced shape are the same artifact — docs cannot drift from code.

1. manifest — provenance header (FDP-1 spirit: version, date, counts, gate rate)

Single object. Required.

2. lexicon — definition meter + dossier band machinery

Array of term objects.

3. records — full-fidelity StudyRecords (pydantic-generated shape, gate-audited)

Array of StudyRecord objects ($ref: #/$defs/StudyRecord). The design atom is the effect estimate, not the study: one StudyRecord holds N ExtractedOutcomes.

3.1 StudyRecord

3.2 Population

3.3 ExposureContrast — the contrast is first-class

"per 50 g/day" and "Q5 vs Q1" are different objects; per-unit slopes are impossible without typed contrasts.

3.4 EffectEstimate — every number is span-grounded

Values here are raw (as published) — value, ci_low, ci_high are on the metric's natural scale (e.g. an RR of 1.14, not ln 1.14). The ln transform happens downstream in the flat outcomes rows.

3.5 ExtractedOutcome

3.6 ExtractionMeta

4. outcomes — flat per-effect rows the UIs consume directly (log scale)

Array of rows derived from records; feeds the hub ledger and dossier. Required top-level section.

Scale note: y (and dose-point y) are ln(effect) for ratio metrics (RR/OR/HR/IRR/PR); se is on that same ln scale. By contrast, effect, ci_lo, ci_hi are the raw published values for display.

5. associations — ledger row spine (also in the contract)

One graded claim per row, with a lead estimate only when effect_question is homogeneous across contributing rows.

6. feed — activity/update feed (also in the contract)

7. mechanisms — typed edges (dossier inner-workings, mermaid/graph exports)

8. promises — 2030 tracker register (non-literature source: NCHS/ODPHP)

Appendix A — Complete enum reference

Appendix B — ln-scale vs raw-scale fields

Appendix C — Generation pipeline

export_contract.py (in files (12)/) imports StudyRecord, EffectMetric, StudyDesign, ContrastType, ModelTier, EffectQuestion, and EnergyScale directly from model set 2/outcome_schema.py, builds the contract dict with enum lists computed live from those Python enums, then embeds StudyRecord.model_json_schema(ref_template="#/$defs/{model}") into $defs (pulling in Population, ExposureContrast, EffectEstimate, ExtractedOutcome, ExtractionMeta, and the enum defs). Running it writes platform-data.schema.json. Because every enum and the entire record shape are emitted from the enforcing code, regenerating the schema after any model change keeps this dictionary's source of truth in lockstep — the contract cannot drift from the code that enforces it.

Source files:

• /Users/morf/Downloads/morf-engineering/mealcoachai/dev/NUTRI-COLLECTIVE_0/nutri-collective/model test evidence tool 2/files (12)/platform-data.schema.json
• /Users/morf/Downloads/morf-engineering/mealcoachai/dev/NUTRI-COLLECTIVE_0/nutri-collective/model test evidence tool 2/files (12)/export_contract.py
• /Users/morf/Downloads/morf-engineering/mealcoachai/dev/NUTRI-COLLECTIVE_0/nutri-collective/model test evidence tool 2/model set 2/outcome_schema.py

Hub-side registers (client JS, demo-labeled)

The dashboard's own small registers live inline in evidence-hub-v2.html; each is one array or map, designed for real data to drop in without touching rendering.

Every register is demo-labeled in the UI and routes through the verification queue before public claims.

ONTOLOGY

How NutriCollective grounds its data in public biomedical ontologies: a five-layer causal spine of curated OBO terms, a small RO relation vocabulary, a SEPIO-profiled evidence-tie schema, and per-row CURIE stamps on principle records.

Sources: nutri-collective/backend/bfo_stack_ontology.json, nutri-collective/ontology.md, nutri-collective/fim-evidence-tool/src/schemas/fim.tie.sepio-profile.json, nutri-collective/backend/principles.json.

The L1–L5 causal spine

Defined in backend/bfo_stack_ontology.json (method: "BFO-grounded 5-layer stack terms (FOODON→ChEBI→GO/Reactome/Rhea→GO:BP/PATO→MONDO/DOID/HPO) + RO relations + expert-priority nutrition mechanisms. Curated seeds for graph/DB — not a full OWL import.").

Curation posture (from the file's expert_recommendations): MONDO is primary at L5 (HPO for signs, DOID as crosswalk); prefer specific ChEBI IDs (EPA CHEBI:28364 / DHA CHEBI:28125) over class proxies; do not bulk-load GO — ~50–200 curated terms on causal paths, not a 40k dump; Reactome for multi-step human pathway "story," Rhea for single-reaction stoichiometry.

License posture (from ontology.md)

ontology.md records the L3 pathway-source decision for a commercial product:

• Reactome — CC0 / public domain. Already wired in (the R-HSA-… CURIEs in principles.json). Keep and deepen.
• Rhea — CC-BY, free; natively ChEBI-keyed. Scoped as the next L3 integration ("Reactome for story, Rhea for stoichiometry").
• KEGG — subscription required for bulk/commercial use; avoid embedding content. At most a nullable crosswalk xref (identifiers only, never the maps), per the G2 guardrail "No full-text redistribution unless the license allows."
• BioCyc / HumanCyc — subscription (paywalled) and redundant with Reactome+Rhea for human metabolism. Skip.
• Pathway Commons — free but inherits member licenses; Reactome-heavy aggregator. Curation-time lookup tool only, never ingested.
• Noted gap: no LICENSE file or per-source license manifest exists yet; a data/SOURCES.md (source → license → redistribution posture) is flagged as the prerequisite for mixing CC0 and CC-BY sources.

Relation vocabulary (RO)

Eight RO object properties are seeded in bfo_stack_ontology.json (obo_layer: "RO"), all in_demo_stack: true:

Edge-strength rule (expert rec #6): the same relation type carries different evidence strength per outcome — RO:0002326 contributes to can be strong for CVD and contested for depression — so strength lives as a graph-edge attribute, never as a global grade on the relation type.

The SEPIO tie profile

fim-evidence-tool/src/schemas/fim.tie.sepio-profile.json ($id: bac.fim.tie.sepio-profile/v0, title FimTie) is a SEPIO profile for a Food-is-Medicine isolate↔claim tie: match is GRADE indirectness over four FIM axes, design is a NutriGRADE-shaped quality composite, and sure = match × design. A match of 0 means unlinkable, not a low weight.

SEPIO anchor fields (required unless noted):

• schema — const "fim.tie/v0"; id (optional) — stable tie id, usually tie:{claim_id}:{study_id}
• assertion_id — the sepio:Assertion (workspace Claim.id)
• evidence_item_id — the sepio:EvidenceItem (workspace StudyOutcome.id)
• evidence_line_id (optional) — the sepio:EvidenceLine (workspace WeightedEvidence.id once the tie is saved)

pico — closed codes on both sides of the tie (OPEN if a side is uncoded; "never invent a match"): study_endpoint/claim_endpoint (enum EndpointCode: EnergyIntake, BodyWeight, HbA1c, FoodInsecurity, CVDMortality, CVDEvent, ObesityPrevalence, AllCauseMortality, SupplyPrevalence, TissueBurden, Type2Diabetes, Hypertension, Anxiety), study_exposure/claim_exposure (enum ExposureSystem: NOVA, HPF, SIGA, UNC, IARC, CHIPS, MNP, UNSTATED), study_layer/claim_layer (enum BindLayer: PACKET, INGESTION, HOST, CLINICAL, ORGANISM, SURFACE), plus free-text contrast.

match (required) — GRADE indirectness over the four FIM axes endpoint, contrast, exposure, layer, each a MatchLevel (0 | 0.5 | 1 — "1 same strain · 0.5 OPEN/partial · 0 no edge"); value is the min of the axes; a why object holds per-axis rationale strings. value = 0 ⇒ no sepio:EvidenceLine is emitted.

design (required) — NutriGRADE-shaped quality: value (0–1), edp_grade (A/B/C/D/OPEN), n_factor, deviation_penalty, provenance (high/moderate/low/unknown), causal_tier (1 ward/interventional · 2 cohort/umbrella), structure_layer (ANALYTE/MATRIX/TELEMETRY), gated + gate_why; optional full nutrigrade card (risk_of_bias, precision, heterogeneity, directness, publication_bias, funding_bias, study_design, effect_size, dose_response, total 0–10, band high/moderate/low/very_low) when a meta-analysis is the isolate.

sure (required, 0–1) — match.value × design.value, the posterior that this isolate belongs on this assertion. unlinkable — true iff match.value === 0. contribution — the sepio contribution: direction (supports/refutes/neutral), weight, and score (= weight × sure; 0 if unlinkable).

Companion packet schemas in the same directory (fim-evidence-tool/src/schemas/) define the workspace objects the ties bind: food.packet.schema.json (bac.fim.packet.food/v1 — id, kind, label, processing "whole vs extruded is the difference Hall measured", amount, nutrients "Analyte layer. Useful, never sufficient.", matrixNotes, provenanceId), provenance.packet.schema.json (bac.fim.packet.provenance/v1 — source, quality enum high/moderate/low/unknown, collectionMethod, collectedAt; "Downstream packets inherit this join"), plus env.packet, meal.packet, user.packet, food_packet.bac, and the runtime schemas PacketLoad, IngestionEvent, HostState, DigestRun.

How principles.json rows carry CURIEs

Each principle in backend/principles.json is a curated physiological pathway statement (with pillar PMIDs) that carries an ontology block mapping it onto the spine:

```json

"ontology": {

"mapped": true,

"method": "human-seed-v1+bfo-stack",

"terms": [

{ "curie": "GO:0019825", "label": "oxygen binding", "source": "go_mf", "obo_layer": "L3", "iri": "http://purl.obolibrary.org/obo/GO_0019825" },

{ "curie": "GO:0015671", "label": "oxygen transport","source": "go_bp", "obo_layer": "L4", "iri": "http://purl.obolibrary.org/obo/GO_0015671" },

{ "curie": "R-HSA-1237044","label": "Erythrocytes take up oxygen and release carbon dioxide", "source": "reactome", "obo_layer": "L3", "iri": "https://reactome.org/content/detail/R-HSA-1237044" },

{ "curie": "CHEBI:18248", "label": "iron atom", "source": "chebi", "obo_layer": "L2", "iri": "http://purl.obolibrary.org/obo/CHEBI_18248" },

{ "curie": "UBERON:0002107","label": "liver", "source": "uberon", "obo_layer": "ANATOMY", "iri": "http://purl.obolibrary.org/obo/UBERON_0002107" }

]

}

```

Every term entry has four required stamps plus the IRI: curie (the compact identifier), label (human-readable name), source (lowercase provider slug: foodon, chebi, go_mf, go_bp, go_cc, reactome, rhea, pato, mondo, doid, hpo, ro, uberon), obo_layer (which spine layer the term occupies: L1–L5, RO, or ANATOMY), and iri (OBO PURL, or the provider's detail URL for Reactome/Rhea). The mapped: true / method: "human-seed-v1+bfo-stack" pair records that the mapping was human-curated against the BFO stack, not machine-generated — the same shape used by the master term list in bfo_stack_ontology.json, where entries additionally carry id, optional stack_node, in_demo_stack, priority: "expert", and notes.

Generated from the living contract (export_contract.py → platform-data.schema.json) and the repository's ontology sources. Regenerate this page whenever the contract version bumps.