# Menu Interchange Format 1.0

> A vendor-neutral JSON format (JSON Schema draft 2020-12) for exchanging
> restaurant and cafe menus between systems. One document describes one venue and
> any number of menus, each with nestable sections of items. The schema is
> normative; the rules below are conformance requirements it cannot itself encode.

## Machine-readable files

- [JSON Schema](/menu.schema.json): the normative definition (draft 2020-12).
- [Example document](/menu.example.json): a complete, schema-valid menu.
- [Human-readable spec](/spec): full prose specification and conformance rules.

## Key conventions

- Money is integer minor units of its currency (ISO 4217 exponent): amount 450 = USD 4.50, 120 = JPY 120. Never floating point. PriceDelta may be negative.
- Every display string is LocalizedText: a plain string (in defaults.language) or a map of BCP-47 tags to strings.
- currency resolves as price.currency then defaults.currency; language as requested tag then defaults.language then any available translation.
- Vendor data lives only under extensions with x- prefixed keys; ignoring all extensions must not change meaning.
- additionalProperties is false everywhere: unknown or misspelled fields fail validation.

## Conformance — producers (MUST)

- Emit documents that validate against menu.schema.json.
- Express every price in integer minor units; never floating-point money.
- Ensure every price resolves to a currency (inline currency or defaults.currency).
- Ensure every modifierGroupIds entry references an id in the top-level modifierGroups array.
- Keep id values unique within their collection and stable across exports; use sku for external POS identifiers.
- Put vendor data only under extensions with x- prefixed keys; extensions MUST NOT change core meaning.

## Conformance — producers (SHOULD)

- Set defaults.language when plain strings are used, and venue.timezone when any availability uses times of day.
- Omit the base price when an item has variants (variants replace it).
- Omit optional fields entirely rather than emitting empty arrays/objects/strings.
- Use available:false for temporary unavailability; remove items no longer sold. List allergens the item contains or may contain.

## Conformance — consumers (MUST)

- Resolve currency and language via the fallback chains above; if a price resolves to no currency, treat the item as invalid rather than guessing.
- Treat variants as replacing the base price when both are present. Absence of an allergen is no claim, never a guarantee of absence; dietaryLabels are positive producer claims.
- Interpret schedules in venue.timezone: startTime inclusive, endTime exclusive; endTime at or before startTime wraps past midnight. Omitted availability means always; item availability narrows its menu's.
- Exclude available:false items from ordering flows (they MAY be shown as sold out).
- When re-emitting, preserve extensions and translations in languages you do not handle — round-tripping loses nothing.

## Conformance — consumers (SHOULD / MAY)

- SHOULD validate incoming documents and reject failures rather than repairing silently. Apply shared modifier groups (in modifierGroupIds order) before inline groups; skip a dangling reference with a warning.
- SHOULD, on duplicate ids within a collection, either reject or keep the first occurrence consistently; do not merge duplicates.
- MAY ignore fields irrelevant to the consumer's purpose, provided ignored data survives round-tripping.

## Versioning

schemaVersion is semver. Within a major version, releases only add optional fields or enum values, so a valid 1.0 document is a valid 1.x document. Consumers MUST reject unsupported major versions and SHOULD validate against the newest 1.x schema available. Producers MUST declare the version whose features they use.