# 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`:

```json
{ "@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": "0614141008889" },
            { "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](/journal/lot-data-lives-at-birth/): 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 artifact — 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 artifact](/journal/no-eval-at-validation-time/) — digest `0f46ff69…`, checkable at [/conformance/](/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](/journal/the-company-is-not-the-performer/): 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](/journal/lot-data-lives-at-birth/), 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](/journal/lot-data-lives-at-birth/) 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](/business-transactions/), 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/](/conformance/); CBV 2.0 §9.2/§9.3 master-data attributes; fixture validated with the packaged CLI 2026-07-31, exit 0.*

---

**Proof, not adjectives.** This build could not verify the gateway's test suite green, so no sentence on this page claims a passing run — the last verified run is recorded in the repository's own CI, not here. Live on this origin, no key: POST /translate, /validate, /hash. No conformance attestation has ever been issued. The dated ledger is /what-ships-today/.