Conformance

This page states what a producer and a consumer of ORDER documents must do, and documents every warning the reference validator can emit.

Producers

An ORDER producer — an export from a booking platform, a CRM, a POS — MUST:

• Emit a document that validates against the ORDER 0.1 schema: order_version, modules, generator, and restaurant present, and every included entity matching its schema.
• Declare, in modules, every module whose data the document actually carries — in particular reservations, whenever the reservations array is non-empty.
• Not emit credentials, cancellation or confirmation tokens, or vendor-internal identifiers — see The specification § Security.

A producer SHOULD:

• Carry proprietary data it cannot express in the schema as an x_<vendor> extension, rather than repurposing an existing field for something it was not specified to mean.
• Supply pixels_per_meter on any pixel-unit coordinate_system whose real-world scale it can measure.

Consumers

An ORDER consumer — an import into a different platform, a reader of a published core document — MUST:

• Ignore any property it does not recognise, at any depth, rather than rejecting the document because of it. This is what makes a 1.0 reader forward-compatible with a 1.1 producer.
• Ignore any module name in modules it does not recognise, while still consuming the modules it does recognise.
• Not treat ref as globally meaningful — see The specification § Identity.

A consumer SHOULD surface the reference validator’s warnings to whoever is reviewing an import: a warning usually means the data is technically valid but probably not what the producer intended.

Errors versus warnings

The reference validator (validate(), in the order package) returns three things: valid, errors, and warnings. Only errors affects valid. A document with warnings and no errors is a valid ORDER document, valid: true, full stop.

This two-tier design is deliberate, not an oversight. Forward compatibility requires that most unrecognised data be tolerated — a warning. A small number of structural rules are enforced strictly regardless — an error — because tolerating them would make the format ambiguous rather than merely larger than one reader expects. One such rule is ref uniqueness: two entities sharing a ref (duplicate_ref) makes the entity graph ambiguous, so the document fails validation outright rather than merely warning — see The specification § Identity.

Two different keywords, two different outcomes

The published schema does not reject an unrecognised property: it declares no additionalProperties: false, so any validator accepts unknown and future-minor fields (this is the forward-compat guarantee). The reference validator separately reports each one as an unknown_property warning — it checks the document against a private, strict copy of the schema — so a likely typo still surfaces without failing the document. A handful of fields behave differently: those whose keys are constrained by JSON Schema’s propertyNames keyword — most notably translations, whose keys must be a BCP-47 tag. A propertyNames violation is a hard error on any validator, not a warning: a translations key like eighty-six’s reserved __ai marker (not a valid BCP-47 tag) fails validation outright. propertyNames and additionalProperties are different keywords with deliberately different outcomes. See The specification § Translations.

Warning codes

The reference validator emits five warning codes, defined in packages/order-spec/src/warnings.ts in the monorepo (the reference implementation is not published to npm during the 0.x line — see Examples).

Code	Meaning	Remedy
unknown_property	A property the 0.1 schema does not define was found, and it is not an x_ extension.	Check it isn’t a typo of a real field. If it’s genuinely new data, either wait for the next ORDER minor version to define it, or move it under an x_<vendor> key.
unknown_module	modules names a module this reader does not know — neither core nor reservations.	Nothing to fix on the document; this is informational. A reader that does not understand a module simply cannot use the data that module would have carried.
floor_plan_unscaled	A room’s floor_plan.coordinate_system uses units: "pixels" with no pixels_per_meter.	Supply pixels_per_meter if the real-world scale is known. If it genuinely is not, the warning is expected — leave it.
bookable_outside_public_hours	A service_period is bookable at a time, or on a day, not covered by any restaurant.public_hours window.	Usually configuration drift between the two — widen public_hours to match, or narrow the service period. If the restaurant genuinely takes bookings outside its advertised hours, the warning is expected — leave it.
dangling_ref	A pointer field (room_ref, a *_refs entry, turn_ref, item_ref, or an anchor ref) names a ref no entity in the document carries.	If the target was dropped, drop the pointer too — or omit the referring entity. If the target lives in a collection this export deliberately omits (tables in a reservations-only export, say), the warning is expected — leave it. See The specification § Referential integrity.

Related

• The specification
• Schema reference
• Examples