Ship the dictionary with the data.

31 July 2026 · the launch journal

The cold-load problem is the quiet tax on every partner onboarding. You send a technically flawless stream of EPCIS events, and your partner's system ingests a thousand records that say, in effect: something identified by urn:epc:id:sgln:0614141.00888.0 observed something identified by urn:epc:idpat:sgtin:0614141.107346.*. Every identifier is opaque until a second channel delivers the decoder ring — a spreadsheet of GLN-to-site-name mappings, a product master extract, a "master data alignment call" on somebody's calendar. The events were standard; the context shipped by email.

The standard's own answer is sitting in the document envelope, and most integrations never open it: epcisHeader. An EPCISDocument is not just an event list — the pinned official EPCIS 2.0.1 schema defines a header that carries epcisMasterData — a vocabularyList of typed vocabularies: business locations, read points, parties, product classes — right beside the epcisBody whose events reference them. One artifact, self-describing, loadable cold.

The fixture

A despatch in one document: two locations, one product class, two events — and a receiver who has never exchanged a spreadsheet with the sender. Validated against the pinned schema, exit 0:

{ "@context": "https://ref.gs1.org/standards/epcis/epcis-context.jsonld",
  "type": "EPCISDocument", "schemaVersion": "2.0",
  "creationDate": "2026-07-31T12:00:00.000Z",
  "epcisHeader": { "epcisMasterData": { "vocabularyList": [
    { "type": "urn:epcglobal:epcis:vtype:BusinessLocation",
      "vocabularyElementList": [
        { "id": "urn:epc:id:sgln:0614141.00888.0",
          "attributes": [
            { "id": "urn:epcglobal:cbv:mda:site", "attribute": "0614141008880" },
            { "id": "urn:epcglobal:cbv:mda:name", "attribute": "Plant 2, Grand Rapids" } ] },
        { "id": "urn:epc:id:sgln:0614142.00777.0",
          "attributes": [
            { "id": "urn:epcglobal:cbv:mda:name", "attribute": "DC East, Allentown" } ] } ] },
    { "type": "urn:epcglobal:epcis:vtype:EPCClass",
      "vocabularyElementList": [
        { "id": "urn:epc:idpat:sgtin:0614141.107346.*",
          "attributes": [
            { "id": "urn:epcglobal:cbv:mda:descriptionShort",
              "attribute": "12oz sparkling water, 24-pack" } ] } ] } ] } },
  "epcisBody": { "eventList": [
    { "type": "ObjectEvent", "action": "OBSERVE",
      "eventTime": "2026-07-31T08:00:00.000Z", "eventTimeZoneOffset": "-05:00",
      "epcList": ["urn:epc:id:sgtin:0614141.107346.4001"],
      "bizStep": "shipping", "disposition": "in_transit",
      "readPoint": { "id": "urn:epc:id:sgln:0614141.00888.0" } },
    { "type": "ObjectEvent", "action": "OBSERVE",
      "eventTime": "2026-07-31T16:20:00.000Z", "eventTimeZoneOffset": "-05:00",
      "epcList": ["urn:epc:id:sgtin:0614141.107346.4001"],
      "bizStep": "receiving", "disposition": "in_progress",
      "readPoint": { "id": "urn:epc:id:sgln:0614142.00777.0" } } ] } }

The receiver's loader resolves every identifier in the events from the header of the same file: the ship-from SGLN is Plant 2, Grand Rapids; the receive point is DC East, Allentown; the serial's class pattern is a 24-pack of sparkling water. No second channel. The attribute names are the CBV §9.2/§9.3 master-data vocabulary (urn:epcglobal:cbv:mda:… — name, site, descriptionShort), the same namespace discipline that governs lot attributes in ILMD: the dictionary entries are standardized too, so even the decoder ring needs no decoder.

This is core schema, not a vendor envelope

Worth being precise about, because header master data looks like the kind of thing a vendor would bolt on. It is in GS1's own published artefact — the pinned epcis-json-schema.json defines it at three named definitions you can read by line: vocabularyList (line 256: vocabularies with vocabularyElementList, each element an id with typed attributes), epcisHeader (line 347: requiring epcisMasterData when present), and the document-level wiring that admits epcisHeader beside epcisBody (line 406). The fixture above exercises exactly those paths, and the validator that accepts it is compiled from that pinned artefact — digest 0f46ff69…, checkable at /conformance/ or against ref.gs1.org directly.

When the header wins, and when it doesn't

The header is a document-scoped dictionary, and its sweet spot is exactly that scope:

Partner onboarding — the first despatch to a new receiver carries its own context; day-one integration is parse one file, not schedule master-data alignment. Send the document, not the project.
Boundary crossings — co-packer to brand, 3PL to owner: parties who share goods but not systems get the context with the goods.
Archival and audit — a document that validates and self-describes years later, when the sender's ERP and its service accounts are long gone. Same property that makes ILMD the right home for lot data, one level up.

It is not a master-data management strategy. Attributes drift — a site renames, a description changes — and a header stamps the values current at authoring time, per document. If you and a partner already run a live GDSN subscription, that feed is the system of record and re-shipping full item masters in every document is noise; the header then carries only what the receiver can't already resolve — locations and read points, typically, which GDSN doesn't cover. The two mechanisms compose: GDSN for the slowly-changing product truth, epcisHeader for the document-scoped context, ILMD for the per-lot birth facts. Three scopes, three mechanisms, all conformant. And when the despatch advice itself arrives as a business document — an 856, a DESADV — its party and item context compiles onto events the same way, which is why the one-file onboarding generalizes beyond EPCIS-native senders.

The fixture is yours: paste it, npx epcis.dev validate, exit 0. Then send your next new partner one file that needs no phone call — and cancel the alignment meeting.

Sources: pinned epcis-json-schema.json definitions vocabularyList (l.256), epcisHeader (l.347), document wiring (l.406) — digests at /conformance/; CBV 2.0 §9.2/§9.3 master-data attributes; fixture validated with the packaged CLI 2026-07-31, exit 0.