Canonical JSON events

Canonical event model

The shared event vocabulary every integration consumes — what a canonical event is, how it travels from scan to your systems, what it looks like, and the schema contract behind it.

What a canonical event is

A canonical event is a checkpointed, structured emission from the portable core to the host — the last step of the scan pipeline. It keeps the host integration explicit and testable.

Each release publishes canonical JSON schemas for the payloads it exchanges, alongside the versioned OpenAPI document. The artifacts carry content hashes so consumers can verify they are building against an unchanged contract.

Event lifecycle

An event travels one way: from the capture to the systems you already run. Your host integration consumes the event at the handoff and maps it into your warehouse or ERP model.

Annotated example — a synthetic session

This is the exact canonical JSON the sandbox replays for its "Clean GTIN capture" session. It is synthetic data — it shows the event shape, not production output.

{
  "gtin": "00347019000105",
  "scanState": "success"
}

gtin

The qualified GTIN from the scanned label — GTIN is the primary identity; lot, expiration, and serial stay GTIN-scoped dependent evidence. See the GTIN-first principle in Platform concepts.

scanState

The capture outcome. The sandbox replays success, duplicate-detected, missing-required-field, and ambiguous.

duplicate-detected

Repeated video frames are not quantity. Key your receiving logic on the checkpointed event, not on raw frames.

missing-required-field

A lot, serial, or expiration value without a qualified GTIN is temporary evidence, not a receivable item.

For the on-device side of the same vocabulary, the Android quickstart documents how scan observations are produced before they are emitted as canonical events. Try the synthetic sandbox demo to replay the other sessions.

Schema vocabulary

Canonical JSON schemas provide a single typed vocabulary for request and payload schemas shared across scan sessions, receiving workflows and billing state — so client applications and integrations use one consistent shape per release.

Field-level details live in the generated spec for the release you deploy; this page intentionally does not duplicate them, so the published artifact stays the single source of truth.

GS1 reference

The barcode reference this page hosts: GS1 application identifiers, check digits, and the portal-side validation tooling.

GS1 application identifiers

A GS1 element string is a chain of (AI)value pairs: each two-to-four-digit application identifier (AI) names the data element that follows it. AI (01) carries the GTIN — the primary identity under the GTIN-first principle (Platform concepts); lot, expiration, and serial are GTIN-scoped dependent evidence, never standalone identifiers.

Check digits

GTIN and SSCC values carry a Modulo-10 check digit as their final digit. The routine: starting from the rightmost data digit and moving left, multiply alternately by 3 and 1, add the products, and subtract the remainder (mod 10) from 10 — a zero remainder means a zero check digit. A failed check digit means the value was misread or mistyped, never a value to repair silently.

Worked example — synthetic GTIN 00300012345671:

The same routine guards the 18-digit SSCC carried by AI (00).

GS1 validation — portal-side tooling

The web tooling behind the portal validates bracketed (AI)value element strings with validateGs1Structure(): per-AI length and pattern checks, GTIN and SSCC check-digit verification, a suggestedCheckDigit (and autoFixedGtin when the fix is computable) on failure, and a DSCSA completeness flag for AIs (01), (17), (10), and (21).

OCR rescue policy

OCR rescue is a constrained second pass for worn, partial, or missing labels, gated twice. First, it runs only when no valid barcode is present — a decoded symbol always wins, and rescue never overwrites decoded data. Second, every proposal is labeled as OCR rescue and needs operator review: confirm records it with the review decision; reject or ambiguous stays visible for review. Nothing auto-commits.

Barcode catalog reference

Canonical events describe what was scanned, not which symbology carried it — but if you need the barcode reference, the barcode catalog lists the knowledge base's barcode entries and their GS1 application identifiers. The catalog describes the reference collection, not which symbologies the RC2 SDK decodes: SDK decode support is not published yet, so never read a catalog entry as a decode guarantee.