Standard / core

OGS Core Specification

Open Gastronomy Standard — Core v0.2

1. Scope

1.1 What OGS Covers (v0.2)

The Open Gastronomy Standard (OGS) provides a machine-readable, JSON-based vocabulary for describing:

• Ingredients — sensory profiles, categories, and provenance
• Dishes — composition, cooking methods, and resulting sensory characteristics
• Beverages — structural attributes, aromatics, and typological classification
• Pairings — scored, explainable matches between dishes and beverages
• Cuisines (new in v0.2) — culinary traditions with endonym-first naming and optional sub-cuisine hierarchy

v0.2 also introduces a full internationalization layer (LString, BCP 47, multilingual thesauri, translation provenance). See ogs-i18n.md. The i18n additions are fully backwards-compatible with v0.1 documents: bare strings remain valid as LString Form 1.

1.2 What OGS Does NOT Cover (v0.2)

• Recipe instructions or step-by-step preparation methods
• Nutritional data or allergen information
• Pricing, availability, or supply-chain data
• Cocktail or non-alcoholic beverage mixing specifications
• Multi-course meal sequencing
• Cultural or religious dietary classifications
• Locale-aware number/date formatting, pluralization, grammatical gender (see ogs-i18n.md §13 for the full out-of-scope list for i18n)

2. Design Principles

3. Versioning

OGS uses Semantic Versioning:

• MAJOR — breaking changes to schema or vocabulary
• MINOR — backwards-compatible additions (new entity types, new explanation codes)
• PATCH — corrections, clarifications, example fixes

Every OGS document MUST include a top-level field:

"ogs_version": "0.2.0"

Schemas currently accept 0.1.x and 0.2.x versions. Consumers SHOULD reject documents whose MAJOR version they do not support.

v0.2 is a MINOR release relative to v0.1: every v0.1 document remains valid against v0.2 schemas.

4. Entity Types

OGS v0.2 defines five entity types:

5. Identifier Format

All OGS entities use a namespaced URI-style identifier:

ogs:<namespace>:<type>:<id>

Examples:

• ogs:core:ingredient:black-truffle
• ogs:core:dish:seared-wagyu-truffle
• ogs:core:beverage:barolo-2018
• ogs:core:pairing:wagyu-barolo

5.1 ID Rules

• Namespace, type, and id segments MUST use lowercase ASCII alphanumeric characters and hyphens only.
• The core namespace is reserved for the OGS project's own reference data.
• Third parties SHOULD use a recognizable namespace (e.g., organization name).

6. Provenance Model

Any data point in OGS MAY carry provenance metadata:

When provenance is not specified, consumers SHOULD treat the data as estimated with confidence: 0.5.

7. Conformance Levels

OGS defines three conformance levels so that producers can adopt the standard incrementally:

Level 1 — Structural (L1)

• The document is valid JSON.
• The document is UTF-8 encoded and Unicode NFC-normalized.
• The document passes validation against the appropriate OGS JSON Schema.
• Required fields (id, ogs_version, name, entity-specific required fields) are present.
• Bare-string LString values are permitted (LString Form 1 — see ogs-i18n.md).

Level 2 — Vocabulary (L2)

• Meets all L1 requirements.
• All enumerated fields use terms from the OGS controlled vocabularies (sensory terms, component roles, cooking methods, match types, aromatic families, cuisines).
• No unknown terms appear in vocabulary-controlled fields.
• All BCP 47 language tags appearing in the document parse validly.
• Entities SHOULD declare primary_language.

Level 3 — Semantic (L3)

• Meets all L2 requirements.
• Sensory profiles are fully populated (all basic tastes and structural attributes present).
• Explanation codes are provided for all pairings.
• Provenance metadata (source, confidence, method) is present on sensory values and pairing scores.
• Entities MUST declare primary_language. Human-readable fields SHOULD use LString Form 2 or Form 3. Non-primary-language labels of role preferred / descriptive / loan SHOULD carry translation provenance (see ogs-i18n.md §7).

8. Document Structure

Every OGS document shares a common envelope:

{
  "id": "ogs:<namespace>:<type>:<id>",
  "ogs_version": "0.1.0",
  "name": "Human-readable name",
  "description": "Optional longer description",
  "metadata": {
    "created": "ISO-8601 datetime",
    "updated": "ISO-8601 datetime",
    "source": "Origin description",
    "license": "Apache-2.0"
  }
}

Entity-specific fields are defined in their respective specifications:

• Ingredients: See ogs-sense.md for sensory profile structure
• Dishes: See ogs-comp.md for composition model
• Beverages: See ogs-sense.md for sensory and structural attributes
• Pairings: See ogs-match.md for matching and scoring model

9. Extension Mechanism

Producers MAY add custom fields to any OGS document by prefixing the field name with x-:

{
  "id": "ogs:mycompany:ingredient:custom-spice",
  "ogs_version": "0.1.0",
  "name": "Custom Spice Blend",
  "x-internal-sku": "SPB-2024-001",
  "x-supplier-rating": 4.5
}

Conformance validators MUST ignore x- prefixed fields. Consumers SHOULD NOT rely on x- fields for interoperability.

10. References

• ogs-sense.md — Sensory Model Specification
• ogs-comp.md — Composition Model Specification
• ogs-match.md — Pairing/Matching Model Specification
• ogs-i18n.md — Internationalization Specification (v0.2)
• ogs-bench.md — Benchmark Specification for evaluating AI systems
• vocab/explanation_codes.json — Explanation Code Vocabulary
• vocab/{cooking_methods,component_roles,match_types,aromatic_families,cuisines}.json — Controlled vocabularies
• vocab/translations/{lang}.json — Multilingual label bundles
• schema/ — JSON Schema definitions for all entity types (+ lstring.schema.json)
• bench/ — OGS-Bench reference runner and official task set