Skip to main content
Machine-readable event & audit schemas for restaurants: sample JSON/Avro for POS, reservations and inventory (with idempotency & ordering fields)

Machine-readable event & audit schemas for restaurants: sample JSON/Avro for POS, reservations and inventory (with idempotency & ordering fields)

Copy-pasteable schemas, example payloads, and the field semantics that actually prevent double-counts and ghost inventory

If you've ever tried to reconcile a POS feed against your inventory depletion and found 14 phantom cocktails that "sold" but never came out of stock, you already know the problem this article solves. The issue is almost never the hardware or the kitchen. It's that your events don't carry enough information to be replayed, deduplicated, or ordered correctly when things go sideways — a dropped webhook, a POS terminal that reconnects after being offline for 40 minutes, a reservation system that fires an "updated" event before the "created" event lands.

This post gives you production-ready JSON Schema and Avro definitions for four event types — POS transactions, reservations, inventory movements (with reserved/committed/prepped semantics), and a lightweight immutable audit log. Each one carries the idempotency and ordering fields you need so downstream systems don't lie to you. At the bottom there's a downloadable bundle with the Avro files and example batches, plus an FAQ mapping fields to reconciliation checks and freshness targets.

If you haven't locked down which fields are required and how often you reconcile, start with the restaurant data governance checklist first — schemas without a reconciliation cadence just give you cleaner garbage.

The five fields that make or break every event

Before the schemas, understand the five fields that appear in all of them. These aren't decoration. In real operations, the vast majority of reconciliation pain traces back to one of these being missing or misused.

FieldPurposeWhat breaks without it
event_idGlobally unique ID for this specific event (UUID)You can't deduplicate. A re-delivered webhook gets counted twice.
source_sequenceMonotonic counter per source (per terminal, per reservation node)You can't detect gaps or reorder out-of-order deliveries.
partition_keyGroups related events so they stay ordered (usually locationid or orderid)Events for the same order process in random order across workers.
causal_idThe event_id of the event that caused this oneYou can't rebuild chains like "void references the original sale."
occurred_atWhen it happened at the source (not when you received it)Latency and clock drift make your ordering meaningless.

Worth internalizing: eventid answers "have I seen this exact event?", sourcesequence answers "did I miss anything between the last one and this one?", and partition_key answers "what else do I need to keep in order with it?" They solve different problems. Teams often implement one and assume it covers the others. It doesn't.

One more thing people consistently get wrong: occurredat must come from the source device or system, and you should carry a separate receivedat on ingest. When a terminal buffers offline and flushes, occurredat can be 30 minutes behind receivedat. If you order on receive time, your cash drawer timeline is fiction.

Always include both occurredat and receivedat to distinguish source time from ingest time when reconciling buffered terminals.

One more thing people consistently get wrong: occurredat must come from the source device or system, and you should carry a separate receivedat on ingest. When a terminal buffers offline and flushes, occurredat can be 30 minutes behind receivedat. If you order on receive time, your cash drawer timeline is fiction.

POS transaction events

This is the schema that feeds sales, cash reconciliation, and inventory depletion. The thing to get right is that a "transaction" is rarely one event. A sale, a partial refund, a comp, and a void are separate events that reference each other through causal_id. Don't try to mutate a transaction record — append.

JSON Schema

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.example.com/pos/transaction/v1.json", "title": "PosTransactionEvent", "type": "object", "required": ["eventid", "eventtype", "occurredat", "sourcesequence", "partitionkey", "locationid", "orderid", "terminalid", "payload"], "properties": { "eventid": { "type": "string", "format": "uuid" }, "eventtype": { "type": "string", "enum": ["sale", "refund", "void", "comp", "discountapplied", "tipadjustment"] }, "occurredat": { "type": "string", "format": "date-time" }, "receivedat": { "type": "string", "format": "date-time" }, "sourcesequence": { "type": "integer", "minimum": 0 }, "partitionkey": { "type": "string" }, "causalid": { "type": ["string", "null"], "format": "uuid" }, "locationid": { "type": "string" }, "orderid": { "type": "string" }, "terminalid": { "type": "string" }, "staffid": { "type": ["string", "null"] }, "payload": { "type": "object", "required": ["currency", "amountminor", "lineitems"], "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "amountminor": { "type": "integer" }, "taxminor": { "type": "integer" }, "tipminor": { "type": "integer" }, "paymentmethod": { "type": "string", "enum": ["cash", "card", "giftcard", "houseaccount", "external"] }, "lineitems": { "type": "array", "items": { "type": "object", "required": ["sku", "qty", "unitpriceminor"], "properties": { "sku": { "type": "string" }, "qty": { "type": "number" }, "unitpriceminor": { "type": "integer" }, "modifiers": { "type": "array", "items": { "type": "string" } } } } } } } } }

Note the amount_minor convention — store money as integer minor units (cents), never floats. Floating-point sums on a busy Saturday will drift by a few cents and you'll waste an hour chasing a variance that isn't real.

Example payload

{ "eventid": "f1c2d3e4-5a6b-7c8d-9e0f-112233445566", "eventtype": "sale", "occurredat": "2025-03-14T19:42:11.220Z", "receivedat": "2025-03-14T19:42:11.980Z", "sourcesequence": 48217, "partitionkey": "loc-5:ord-99812", "causalid": null, "locationid": "loc-5", "orderid": "ord-99812", "terminalid": "term-03", "staffid": "emp-214", "payload": { "currency": "USD", "amountminor": 8640, "taxminor": 640, "tipminor": 0, "paymentmethod": "card", "lineitems": [ { "sku": "ENTREE-SALMON", "qty": 1, "unitpriceminor": 3200, "modifiers": ["no-butter"] }, { "sku": "COCKTAIL-NEGRONI", "qty": 2, "unitpriceminor": 1600, "modifiers": [] } ] } }

A refund referencing this sale would carry "eventtype": "refund" and "causalid": "f1c2d3e4-...". That causal link is what lets you answer "how much of today's refunds trace to sales from last week" without a manual join.

Safe replay & dedup notes: Dedup on eventid. If you see the same eventid twice, drop the second — never re-apply. On replay, process in order of (partitionkey, sourcesequence). A sale and its void share a partition key, so they stay in the right sequence even if delivered out of order.

Minimal validation: reject if amount_minor doesn't equal the sum of line items plus tax minus discounts (for sale). A mismatch here is almost always a modifier-pricing bug, and it's far cheaper to catch at ingest than at month-end.

Reservation events

Reservations are a lifecycle, not a record. The common failure is treating the latest state as truth and losing the chain of how you got there — which matters a lot when you're investigating a no-show deposit dispute or a double-book.

JSON Schema (abbreviated to the parts that matter)

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.example.com/reservation/event/v1.json", "title": "ReservationEvent", "type": "object", "required": ["eventid", "eventtype", "occurredat", "sourcesequence", "partitionkey", "locationid", "reservationid", "payload"], "properties": { "eventid": { "type": "string", "format": "uuid" }, "eventtype": { "type": "string", "enum": ["created", "modified", "confirmed", "seated", "completed", "cancelled", "noshow", "depositcharged"] }, "occurredat": { "type": "string", "format": "date-time" }, "sourcesequence": { "type": "integer", "minimum": 0 }, "partitionkey": { "type": "string" }, "causalid": { "type": ["string", "null"], "format": "uuid" }, "locationid": { "type": "string" }, "reservationid": { "type": "string" }, "payload": { "type": "object", "required": ["partysize", "slotstart"], "properties": { "partysize": { "type": "integer", "minimum": 1 }, "slotstart": { "type": "string", "format": "date-time" }, "tableids": { "type": "array", "items": { "type": "string" } }, "channel": { "type": "string", "enum": ["web", "phone", "walkin", "thirdparty"] }, "guestref": { "type": ["string", "null"] }, "depositminor": { "type": ["integer", "null"] } } } } }

Example payload

{ "eventid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "eventtype": "seated", "occurredat": "2025-03-14T20:03:52.000Z", "sourcesequence": 10432, "partitionkey": "loc-5:res-77120", "causalid": "99aa88bb-...-confirmed-event-id", "locationid": "loc-5", "reservationid": "res-77120", "payload": { "partysize": 4, "slotstart": "2025-03-14T20:00:00.000Z", "tableids": ["T12"], "channel": "web", "guestref": "guest-3391", "deposit_minor": 2000 } }

The ordering trap: reservation systems are notorious for firing modified before created when a guest edits within seconds of booking. Because both share partitionkey loc-5:res-77120, you order on sourcesequence and the modified correctly waits for the created. If you only dedup on event_id and process on arrival, you'll create records out of nowhere.

Minimal validation: a seated event with no prior confirmed or created in the same partition is a red flag — either a lost event or a walk-in logged against a reservation ID it shouldn't have. Flag it, don't silently accept it.

Inventory events — reserved, committed, and prepped semantics

This is the one most POS-inventory integrations get wrong. They track a single "on hand" number and decrement it at sale time. That works fine until you take a 30-cover banquet reservation that needs 30 portions of short rib, and your line cook sees "40 on hand" and keeps selling it à la carte. By service you're 12 portions short.

The fix is modeling inventory as states, not just a count:

  1. reserved — soft hold. Allocated to a future order or banquet but not yet pulled. Can be released.
  2. committed — hard hold. The order is firing; the stock is spoken for and will deplete.
  3. prepped — physically transformed. 20 lbs of raw chicken became 60 portioned breasts. The raw count drops, a prepped count appears, with a yield factor.

Your "available to sell" = onhand − reserved − committed. Not just onhand.

Avro schema

{ "type": "record", "name": "InventoryEvent", "namespace": "com.example.inventory.v1", "fields": [ { "name": "eventid", "type": "string" }, { "name": "eventtype", "type": { "type": "enum", "name": "InvEventType", "symbols": ["received", "reserved", "released", "committed", "depleted", "prepped", "wasted", "counted", "adjusted"] } }, { "name": "occurredat", "type": { "type": "long", "logicalType": "timestamp-millis" } }, { "name": "sourcesequence", "type": "long" }, { "name": "partitionkey", "type": "string" }, { "name": "causalid", "type": ["null", "string"], "default": null }, { "name": "locationid", "type": "string" }, { "name": "sku", "type": "string" }, { "name": "qty", "type": "double" }, { "name": "unit", "type": "string" }, { "name": "reftype", "type": ["null", "string"], "default": null }, { "name": "refid", "type": ["null", "string"], "default": null }, { "name": "yieldfromsku", "type": ["null", "string"], "default": null }, { "name": "yieldfactor", "type": ["null", "double"], "default": null }, { "name": "actor", "type": ["null", "string"], "default": null } ] }

Process diagram

A reserved hold for the banquet:

{ "eventid": "b0b1b2b3-aaaa-bbbb-cccc-000111222333", "eventtype": "reserved", "occurredat": 1741977600000, "sourcesequence": 55012, "partitionkey": "loc-5:SHORTRIB-PORTION", "causalid": null, "locationid": "loc-5", "sku": "SHORTRIB-PORTION", "qty": 30, "unit": "portion", "reftype": "reservation", "refid": "res-77120", "yieldfromsku": null, "yieldfactor": null, "actor": "emp-118" }

A prep event converting raw to portions:

{ "eventid": "c4c5c6c7-dddd-eeee-ffff-444555666777", "eventtype": "prepped", "occurredat": 1741980000000, "sourcesequence": 55099, "partitionkey": "loc-5:SHORTRIB-PORTION", "causalid": "b0b1b2b3-aaaa-bbbb-cccc-000111222333", "locationid": "loc-5", "sku": "SHORTRIB-PORTION", "qty": 42, "unit": "portion", "reftype": "prepbatch", "refid": "prep-0314-02", "yieldfromsku": "SHORTRIB-RAW-LB", "yield_factor": 0.75, "actor": "emp-118" }

The yieldfactor of 0.75 means the portions were cut from raw at 75% yield — so the system should emit (or you should derive) a corresponding depleted event against SHORTRIB-RAW-LB. Keeping that raw depletion linked through causalid is how you later answer "why did raw short rib drop 14 lbs at 2pm" without guessing.

Why partitionkey is the SKU here: all movements for one SKU at one location must be ordered relative to each other, or your running balance goes negative mid-stream even though the final total is correct. Partitioning by locationid:sku keeps each SKU's ledger strictly ordered.

Safe replay: inventory events are a ledger — they must be idempotent on apply. Dedup on event_id religiously. Replaying a depleted event you already applied will silently drive your count negative, and nobody notices until a cycle count blows up.

The lightweight immutable audit log

This isn't your business-event stream. It's a thin, append-only record of who changed what and when for the actions that carry money or compliance risk: a manager void override, a price change, a comp above threshold, a deleted reservation. Keep it separate and keep it boring.

JSON Schema

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.example.com/audit/event/v1.json", "title": "AuditLogEvent", "type": "object", "required": ["eventid", "occurredat", "actorid", "action", "objecttype", "objectid", "locationid"], "additionalProperties": false, "properties": { "eventid": { "type": "string", "format": "uuid" }, "occurredat": { "type": "string", "format": "date-time" }, "actorid": { "type": "string" }, "actorrole": { "type": "string" }, "action": { "type": "string", "enum": ["create", "update", "delete", "override", "approve", "login"] }, "objecttype": { "type": "string" }, "objectid": { "type": "string" }, "locationid": { "type": "string" }, "before": { "type": ["object", "null"] }, "after": { "type": ["object", "null"] }, "reason": { "type": ["string", "null"] }, "prevhash": { "type": ["string", "null"] }, "hash": { "type": "string" } } }

The prev_hash/hash pair makes it tamper-evident: each entry hashes its own content plus the previous entry's hash. If someone edits or deletes a row later, the chain breaks and you can prove it. You don't need a blockchain — a simple SHA-256 chain is enough for an inspector or a chargeback dispute.

Example payload

{ "eventid": "d7d8d9da-1234-5678-9abc-def012345678", "occurredat": "2025-03-14T21:15:03.000Z", "actorid": "mgr-04", "actorrole": "shiftmanager", "action": "override", "objecttype": "posvoid", "objectid": "ord-99812", "locationid": "loc-5", "before": { "status": "pendingvoid", "amountminor": 1600 }, "after": { "status": "voided", "amountminor": 1600 }, "reason": "guest sent back incorrect cocktail", "prev_hash": "9f2c...a1", "hash": "4b7e...c3" }

Validation rule that matters: additionalProperties: false. Audit logs should reject anything they don't explicitly expect. A loose audit schema that silently accepts extra fields is how sensitive data leaks into a log you later hand to a third party.

When this level of rigor is worth it — and when it isn't

When it makes sense

  1. You run more than one location and reconcile sales against inventory centrally.
  2. You take deposits or run banquets, where reserved vs. available stock actually diverges.
  3. You've had at least one month-end where POS totals and inventory depletion disagreed and nobody could explain why.
  4. You're feeding this data into forecasting and need it to actually be trustworthy.

When it's overkill

  1. Single location, one terminal, you count inventory by hand weekly and it's fine. Adding causal chains and hash-linked audit logs to a 40-seat café with no third-party integrations is effort you won't get back.
  2. You don't yet have a reconciliation cadence. Schemas are downstream of governance — nail down required fields and reconciliation frequency first, then formalize events.

Who should not do this

If your team doesn't currently reconcile anything, don't start here. A perfect schema feeding a process nobody checks produces very tidy numbers that are still wrong. Build the habit first.

A real scenario: the phantom banquet shortfall

A mid-size steakhouse group — four locations, full bar, regular private dining — kept running short on prep-heavy proteins during banquet nights while à la carte service ran fine the rest of the week. The POS showed healthy "on hand" counts right up until the banquet fired, then the line was suddenly short 10–15 portions.

The root cause was exactly the single-count model: banquet allocations weren't held as reserved, so à la carte sales ate into stock that was already promised. Over roughly two months they tracked around six banquet nights where this happened, each one forcing a scramble — comping dishes, pulling substitute proteins, one near-cancellation of a 30-top.

After moving to reserved/committed/prepped events (partitioned by locationid:sku, deduped on eventid), "available to sell" finally subtracted held stock. The shortfalls stopped. The quieter win was the audit chain: when a cook released a reservation hold to grab portions, the released event with an actor made it visible instead of a mystery. Variance investigations that used to take an hour of back-and-forth dropped to a quick lookup.

FAQ — fields mapped to reconciliation checks and freshness targets

Which fields do I reconcile POS against inventory with? Join POS lineitems[].sku + qty against inventory depleted events sharing the same orderid via ref_id. Any sale without a matching depletion within your freshness window is a recipe-mapping gap or a missing event.

How do I detect lost events? Watch source_sequence per source. A gap (e.g., jumps from 55012 to 55014) means event 55013 was dropped — fetch it before trusting the running balance.

What freshness targets are reasonable?

  1. POS sale → ingest

    under ~60 seconds p95. Cash reconciliation can tolerate minutes, not hours.

  2. Reservation state change → ingest

    under ~30 seconds, since seated/cancelled drive host decisions live.

  3. Inventory depletion → available-to-sell update

    under ~2 minutes during service.

  4. Audit log write

    synchronous — the action shouldn't complete until the entry is durable.

How do I safely replay a day? Process per partition in sourcesequence order, dedup on eventid, and make every apply idempotent. If replay changes your totals, you have a non-idempotent handler — fix that before trusting any reconciliation.

What's the minimum validation I should enforce at ingest? Reject missing required fields, reject duplicate eventid, reject occurredat more than a few minutes in the future (clock drift), and for POS, reject amount/line-item mismatches. Everything else can warn rather than block.

Download the schemas and example batches

The full bundle — Avro .avsc files for all four event types, the JSON Schema versions, and example event batches (including a complete banquet reserve→prep→commit→deplete sequence and a sale→void→refund chain) — is packaged in the downloadable gist linked with this post. Drop the Avro files straight into your schema registry and the example batches into a test topic to validate your consumers before pointing them at live data.

Start with the governance foundation in the restaurant data governance checklist, then wire these schemas in. Get the five ordering fields right and most of your reconciliation headaches stop being mysteries and start being lookups.

Start with the governance foundation in the restaurant data governance checklist, then wire these schemas in. Get the five ordering fields right and most of your reconciliation headaches stop being mysteries and start being lookups.

Built for Restaurants Tailored management tools for restaurant workflows
Save Time Streamline reservations, orders, and staffing
Delight Customers Faster seating and smoother service experiences
Boost Revenue Maximize table utilization and repeat visits