Skip to content
Eighty-SixDocs

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

Section titled “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

Section titled “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

Section titled “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.

Warning codes

Section titled “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.
Section titled “Related”