Events, Credentials and Representations
What happens after a record is published: how a movement in your source system becomes an EPCIS event, where UNTP answers the same question differently, and how a passport gains a signed, selectively disclosed representation.
Two questions, two systems
Everything the connectors have done so far answers one question: what is this thing? A GTIN is registered, a brand, a net content and a set of images are attached to it, and a resolver makes that answer reachable from a scan. That is master data, and it lives in the catalog behind the GS1 Digital Link resolver.
Master data cannot answer the second question, what became of this particular one?, because that question concerns a moment in the life of one item. A lot came into being on a Tuesday; a pallet was packed, shipped, received and sold. Such statements belong in a separate system, an EPCIS 2.0 repository, with its own address, its own permissions and its own retention. A deployment may well run both on one host, but a connector never assumes so, and the two are configured separately.
The permissions are separate as well, even on the same token. Writing events requires the capture permission and reading them requires query, and holding one implies nothing about the other. On the platform, the tenant-scoped realm role <tenant>/capture expands to the capture permission. The connector's diagnosis ladder therefore has a rung of its own for it: an authenticated GET /capture that proves reachability and entitlement without capturing anything.
From a movement to an event
An EPCIS event answers four questions (what, when, where and why), and a single warehouse movement line in an ERP already holds all four. The Odoo connector reads them at the one moment where they are all settled, in the hook that runs when a transfer is validated. What is the lot or serial on the line, when is the completion of the transfer, where is the GLN of the location, and why is the operation type.
The why needs translation, because a source system does not speak GS1's vocabulary. Odoo knows that a picking is "incoming", and GS1's Core Business Vocabulary calls that receiving with disposition in_progress. The mapping therefore lives in two fields on the operation type, pre-filled from Odoo's own codes (incoming to receiving, outgoing to shipping, internal to storing, a manufacturing order to commissioning) and refined further by the sequence code, so a PICK, PACK, QC or STOR step lands on its own business step. Once a person has made a choice in these fields, the pre-fill never overwrites it.
A point-of-sale terminal looks to the stock module exactly like a delivery, so a small bridge addon recognises the till and reports retail_selling with disposition retail_sold. It hooks the moment a till is pointed at an operation type, since that changes none of the codes the pre-fill is computed from, and it restores the plain shipment meaning when the till is pointed elsewhere.
Reporting must never be the reason a transfer fails, so the event is not sent while the transfer is being validated. The picking writes rows into an outbox table, and a scheduled job delivers them. A warehouse operator pressing Validate can do nothing about an unreachable repository and is not bothered with it.
Delivery has two stages, and the outbox tracks them separately. accepted means the repository has taken the document into custody; captured means it is stored. A queue that deleted its row on the 202 would report success for events that were rejected minutes later. A capture job the repository does not recognise does not count as success either, because a rejected document and a forgotten one look the same from outside. After five attempts the row stops asking and reports that delivery cannot be confirmed.
The eventID is the event hash
Every event in this stack carries a computed eventID, which is the canonical CBV event hash, ni:///sha-256;<hex>?ver=CBV2.0, taken over everything the event asserts. Only a literal exclusion list is left out: the eventID itself, recordTime, errorDeclaration and its sub-fields, certificationInfo, and the JSON-LD @context. Anyone holding the event can recompute the hash, and that makes it an identity: two companies describing the same observation arrive at the same identifier without having agreed on anything beforehand.
eventTime and the declared eventTimeZoneOffset go into the hash, because the time is part of what the event says. So do the place and the business step: the read point's GLN, the operation type's bizStep and disposition mapping, and the form of the business transaction reference. Changing any of those changes the identifiers minted from that moment on. This is intended, and worth knowing in advance: an event identifier describes the statement, so a changed statement gets a changed name.
Computing the identifier makes retries safe. When it is derived from the facts, a repeated send creates no second event, whereas a randomly drawn identifier would turn every retry after a half-completed publish into a new occurrence of something that happened once. The repository applies two independent checks. It de-duplicates on the canonical hash, with a hard rejection when the same sender repeats an event and a quiet metadata update when a different tenant sends one it already holds. Separately, it refuses an eventID it has already seen.
Because the time is part of the identity, it has to come from the source and never from the clock at reporting time. An invented event time would be a false statement from the outset, and it would give the same movement a different name on every attempt. Where the source cannot say when something happened, no event is made at all: Odoo posts the reason on the transfer, and the Java connector publishes the instance to the catalog and logs that it was not commissioned. Both are visible enough to be fixed.
The connectors also keep a second, private key for their own bookkeeping. In Odoo this is an idempotency key derived from the database, the transfer and the identifiers, with a unique index per company, so the same movement cannot enter the outbox twice. It never leaves the database and plays no part in the event's name.
The event's name is assigned by the repository, which computes the hash when it stores the event. There is exactly one canonicalisation, and it runs on the side that keeps the event. The Java connector, which mints commissioning events, computes the same hash itself and sends it, and the repository keeps whatever a sender supplies verbatim. The connector places the capture call between the catalog PUT and the write of its own state. If capture fails, the state stays unwritten; the next tick publishes again (a harmless merge) and captures again under the same identifier, which the repository recognises as a repetition.
Class level and instance level
GS1 addresses three different things with one grammar. Mixing them up produces events that validate and still mean the wrong thing, and the library warns about this explicitly, since an LGTIN in an epcList is the most common way to get it wrong.
A bare GTIN is the model, the article itself: /01/{gtin}. A GTIN with a lot number (AI 10) is an LGTIN. It is still class level, because a lot is a set of things, and it belongs in the quantityList as an epcClass. A GTIN with a serial (AI 21) is an SGTIN, a single item, and only that belongs in the epcList. An SSCC (AI 00) identifies a logistic unit and becomes the parentID of an aggregation.
The product's tracking setting decides which qualifier applies, independent of the lot record. Serial tracking yields AI 21, and everything else falls back to AI 10, because the lot level is the weaker and therefore safer claim. Quantities are summed per class, since two lines of the same lot are one statement about that lot. EPCIS reads a quantity without a unit as a piece count, so the unit code for pieces is left off.
All of these identifiers are written as canonical GS1 Digital Link URIs on https://id.gs1.org, never on the installation's own resolver. Inside an event an identifier serves as an identity, and two companies describing the same pallet have to produce byte-identical strings. GS1 fixes the qualifier order (22, 10, 21), whatever the order of the call. Read points and business locations follow the same logic and become SGLN URIs under AI 414; a raw GLN would be accepted by the repository and then found by no query.
Instances are also published as catalog documents of their own under the model's GTIN: /01/{gtin}/10/{lot} and /01/{gtin}/21/{serial}. The sync loop walks the kinds in a fixed order, products and organizations first and lots and serials after them, so that a fresh GTIN document exists before the first instance hangs off it. An instance document under a GTIN the catalog does not hold would point at a model nobody can resolve. An event without a read point is only half an answer, so the Java connector reports the gap at startup and declines to commission for that connection, while Odoo skips the report and writes the reason into the document's chatter.
What is captured today
The two strands cover different ground.
The Java connector does exactly one thing: when a lot or a serial is published for the first time, it mints a commissioning event, an ObjectEvent with action=ADD, bizStep=commissioning and disposition=active. The event carries no ilmd. A production date copied into the event would be a second copy that can go stale, and ILMD is defined for the lot level only, so it has nothing to say about a serial. The instance path carries a gs1:masterData link, and the data is reached by resolution.
Three conditions must hold before anything is captured: it is the first publish of an instance, the connection has epcis.enabled=true and an epcis.url, and the article itself consents. That consent is master data, the field commissionCaptureEnabled on the product. An explicitly stated value always wins. Where nothing is stated, the licence decides, and only a key on a prefix the tenant is licensed for is commissioned. In dry run nothing is ever captured, only logged, because events are append-only and are the hardest category of irreversibility there is.
The Odoo strand goes much further, on both maintained branches: 18.0 and 19.0 carry the same five addons and differ only where Odoo itself does. Four of the five EPCIS event types are produced. A movement is a fact about a moment and can simply be stated. An aggregation and a transaction association are standing statements: scan the SSCC and the repository answers what is underneath it, read the despatch advice and it answers which goods went out on it. A standing statement that is never withdrawn keeps answering after it has stopped being true, so these two are reported both when they begin and when they end.
ObjectEvents come out of validated transfers. AggregationEvents carry packing as action=ADD and emptying as action=DELETE, with the SSCC as parentID. They are emitted before the movement event because that is the order in which things happen: goods leave one unit, enter another, and the unit itself moves last. A line counts as packed or unpacked only where the unit actually changed, so a pallet that merely travels produces a movement and nothing more. A unit without an SSCC is skipped on both sides, because nothing was ever claimed about it.
Emptying arrives by two routes, and both are caught: a warehouse takes a pallet apart either through a transfer or through the Unpack button on the package. The button destroys the contents and the location the event needs to describe, so both are read before it runs. SSCCs are minted as soon as a package is created, ahead of its first report.
On Odoo 19 an aggregation can have a second kind of child, since that release lets logistic units nest inside one another. A pallet of cases is the oldest hierarchy GS1 describes, and the vocabulary has always covered it, because an AggregationEvent's childEPCs may be SSCCs as well as trade items. What was missing was the record of the nesting, and only the newer Odoo keeps one. Nesting is a standing statement too, so the rule for a packed pallet applies: a unit entering a container and a unit leaving one are both reported, and a unit that changes container states both halves, so the first pallet stops answering with a case that is no longer on it.
Every route to nesting in Odoo passes through the parent field on the package, so one hook covers them all. The put-in-pack flows write it, the field on the package form writes it, and Unpack clears it on the children. A unit created already inside another never passes that hook, so creation is caught separately. Events are grouped by container, because an aggregation is a statement about a container: two cases put on one pallet are one statement about that pallet. The planned container, where a unit is heading during an open transfer, is ignored, since it is only a plan.
Nesting is also where two of the connector's rules meet. An event's time has to come from the source, yet nothing in Odoo records when a nesting happened, and the moment it is written is the moment it becomes true. That moment is therefore the event time, which is the same rule the Unpack button already followed. The read point is the container's own location, because the statement is about the container and a child on its way elsewhere has already left.
A TransactionEvent is emitted in exactly one situation. Every event this connector sends already names the paperwork it belongs to, so a TransactionEvent with action=ADD would assert the same association a second time. Ending an association is something no other event says. Goods coming back on a return stop belonging to the shipment they went out on, and a receipt only says that they arrived somewhere; nobody downstream can derive from it that they left a despatch advice. A return therefore releases the transaction the original transfer named, with action=DELETE and disposition returned. A return of goods that named no paperwork releases nothing.
The TransformationEvent lives in a bridge addon of its own and hangs on the manufacturing order, because production is the one movement where the identifiers going in differ from those coming out. One event carries the whole order: what was consumed as the input list, what came out as the output list, and no action, since this is the one event type that has none. A half transformation is refused, because an event with inputs and no outputs would assert that goods vanished. The business step comes from the same two fields on the operation type as everywhere else.
AssociationEvent, the fifth type, is not produced. It states that one thing is installed in another, and nothing a warehouse or a production order in Odoo records has that meaning.
Events also flow back. An inbox reads them with GET /events on a recordTime watermark and shows them on the lot or the package. It reads class level as well as instance level, so an event that names a lot only as an epcClass in a quantityList still finds it, and it recognises one of our identifiers inside a document that mixes ours with a partner's. Events the connector sent itself are recognised when they return, because the outbox derives its identifiers exactly as the repository holds them, and they are marked as ignored.
Stock can be booked from that inbox within narrow limits, and the guards are what make it safe. A transfer is completed only by an incoming event, reported by the partner the transfer names, against paperwork we named, on a transfer that is reserved and waiting, in the right company, with a business step that actually attests completion. The first check is the event type: an AggregationEvent or a TransformationEvent may be perfectly true and still says nothing about whether a transfer completed, so it is shown and never booked. A partner's event stays an observation; booking it as a document would make your period close depend on somebody else's data quality.
A reported event can also be withdrawn, although append-only storage seems to forbid it. EPCIS handles a movement that turns out not to have happened with an errorDeclaration, which adds a statement and removes nothing. Because the declaration fields are excluded from the canonical hash, the correction carries the same identity as the event it corrects, and the repository recognises which event is meant without the connector ever having learned its name. Only did_not_occur is offered. The other CBV reason, incorrect_data, keeps the occurrence and disputes the description, which would require minting the corrected events as well, and this connector mints none.
Status: on both maintained branches the Odoo connector produces ObjectEvent, AggregationEvent in both directions, TransactionEvent with action=DELETE and TransformationEvent, reads events back, and can withdraw one through an error declaration. Aggregation over nested units is 19.0 only, because Odoo 18 has no nesting to report. AssociationEvent is produced nowhere in this stack, and neither is a TransactionEvent with action=ADD. The Java connector's event surface is commissioning only; it produces no movement, aggregation, transaction or transformation event and reads nothing back.
UNTP
The UN Transparency Protocol is a UN/CEFACT specification for supply-chain transparency: a set of JSON-LD document types with their own vocabulary, aimed at the same problem as GS1 and EN 182xx from a different starting point. The GS1 stack begins with an identifier that already exists in the physical world and hangs everything off its resolution. UNTP begins with the document, such as a passport or a conformity attestation, as a credential that travels.
Both approaches are useful, and OpenEPCIS treats the difference as a translation problem. The alignment consists of a graded SKOS mapping in the module ontologies plus a bridge context. There are 41 mappings onto untp: terms across the core, battery, textile and electronics ontologies: 33 of them skos:broadMatch, four closeMatch and four exactMatch. The grading matters, because claiming equivalence where only a broader match holds is how two vocabularies drift apart unnoticed. The bridge context resolves UNTP property names onto oec: targets and adopts the conformity classes UNTP genuinely owns unchanged. Value conventions match as well: both sides use the same 0-1 decimal scale for ratios, so no arithmetic happens at the boundary. A command-line tool audits the mappings against the upstream vocabulary to confirm they still hold.
What "UNTP-aligned" means here: a vocabulary mapping, plus Data Integrity as the securing mechanism UNTP is native to. UNTP document types are not issued. The credential type this platform issues is oec:DigitalProductPassport; it issues neither untp:ProductPassport nor a UNTP conformity credential.
A passport, signed
On top of the master data, the passport and the event history sits a wrapper that anyone can check cryptographically: W3C Verifiable Credentials, data model 2.0. The platform's VC layer is a Quarkus service with a library core, and it adds no content of its own, since the credential subject is the same oec: graph the rest of the stack publishes.
Three securing mechanisms are implemented, and the choice is made in exactly one place, the credential configuration. JSON-LD Data Integrity with the ecdsa-rdfc-2019 cryptosuite is served as application/vc+ld+json, the W3C VC-JOSE compact envelope as application/vc+jwt, and SD-JWT VC, the format the EUDI wallet world speaks, as application/dc+sd-jwt. A configuration that names no format falls back to the JOSE envelope, which is cheaper for a large payload. Data Integrity is the mechanism the GS1 and UNTP ecosystems are converging on, and the interoperability evidence below rests on it.
Two guards protect the signing path. A safe-mode gate refuses to sign a credential that still contains relative @id or @type references, since nobody in the ecosystem could verify such a signature, and the endpoint answers 422. The credential type is written as a CURIE, because the standard contexts define prefixes only and a bare type would expand relatively, which strict verifiers reject.
Trust is anchored in did:web. The issuer publishes its own DID document at /.well-known/did.json, and key material lives in Kubernetes secrets and never in the search index. A rule library models the GS1 licence chain (topology, delegation and prefix containment, with did:web:id.gs1.org as the root) and has an off / log / enforce switch, so a deployment can observe before it enforces. The library checks structure only and performs no IO and no cryptography; signatures are the proof engine's job. The verification endpoint uses it as one of its trust roots, next to the platform's trusted issuer list. On the hosted verifier the GS1 root is not switched on yet. See Signed Passports.
Revocation is opt-in per credential configuration. Without a status purpose a credential carries no credentialStatus at all and can never be revoked, which suits a passport nobody intends to withdraw. Where revocation is enabled, two mechanisms are implemented, the W3C Bitstring Status List and the IETF Token Status List. The status URL can be dereferenced anonymously, because checking whether a credential is still valid must never require an account. Revocation is tenant-bound, idempotent and permanent, and a credential belonging to another tenant answers 404, so its existence stays hidden.
The interoperability has been measured, though not equally for every path. A real GS1 licence credential, fetched live and checked against GS1's own DID document, verifies in this engine and fails as soon as a byte changes. A credential issued here is accepted by a third-party verifier built on an unrelated library stack. This work uncovered a genuine defect: the bundled RDF canonicaliser was not RDFC-1.0 conformant and produced six wrong outputs on the 33 conclusive cases of the W3C suite, so nobody else could reconstruct a signature over a passport with many blank nodes. The canonicaliser was replaced. The vc+jwt path and the W3C bitstring list have so far only been round-tripped against this implementation's own output.
Status: the issuer publishes OID4VCI metadata and a credential endpoint, so a wallet can discover and request passport and event credentials with a Keycloak access token. Credential offers and holder key binding are not built. OID4VP presentation with an access receipt is released; see Signed Passports for what runs on epc.is. There is no bridge that mints a credential automatically when a passport is saved or an event is captured; issuance is always an explicit request.
Representations
The term that ties this page together is representation: the same statement, packaged differently and disclosed to a different extent.
The DPP API already works this way for the passport itself. The GS1 Web Vocabulary master data is the single source of truth, and the EN 18223 passport is derived from it on read and never stored a second time. From that one working document the DPP API projects four JSON representations:
compressed(the default, withoperationalas a silent alias) echoes the stored body verbatim, so that aGETreturns the bytes that werePUT;full(orexpanded) is the Annex A form, with every data element spelled out with itselementId,objectType,dictionaryReferenceandvalueDataType;gs1is the master-data body on its own;euis the flat JSON profile of the EU digital product passport registry, currently for batteries and limited to the public view.
The Annex B XML form and the RDF serialisations come out of the same computation and are chosen through the Accept header.
A verifiable credential joins that set as one more representation, and no new link type was minted for it. The credential is registered in the linkset under the existing gs1:dpp link type and told apart from the HTML rendering by its media type alone. That is ordinary GS1 content negotiation, and it is exactly what a pull consumer matches on. For an EPCIS event the mirror-image rule applies: the event stays in the repository, the credential references it, and the canonical CBV event hash travels along as a relatedResource to anchor that reference. Embedding the event would redefine terms the EPCIS context protects, and anyone who has the event can reproduce the hash.
Nothing in this stack takes a representation down again on its own:
- A product that disappears at the source leaves its catalog document standing, because a deletion in the catalog always takes an explicit act and never follows from a webhook that arrived late.
- A published passport page withdrawn in the PIM keeps its
gs1:pipentry in the linkset and points at a page that now answers with a tombstone, since an empty link list makes the registration step return without removing anything. - The resolver never checks whether a link target is still alive. An entry disappears only when somebody removes it through the linkset API.
Withdrawing a record, a passport or a link is therefore a manual act today, separately on each of the three levels. Events are the exception, because EPCIS provides for it: an event is taken back by declaring the error, so even the retraction is an addition.
Status: linkset auto-registration (the step that makes a credential discoverable as a representation) is switched off by default. Where it is enabled it runs as a read-merge-update through the resolver's PATCH interface on the caller's own token, and a failure is logged and does not turn into an issuance error.
Access tiers on a representation
Which parts of a passport a given reader may see follows the three-tier scale of ESPR Article 9, and the vocabulary itself carries it: Public, for every user including market surveillance and customs; AuthorizedOnly, for market surveillance authorities and customs; Restricted, for specified authorised economic operators. That is what the annotation on a property means, and the ontology states it in those words.
What the resolver actually enforces is narrower, because at runtime it knows tenant membership and roles and has no concept of actors. A caller who holds the authority role dpp-restricted or dpp-admin and belongs to the owning tenant is treated as Restricted; any other authenticated member of the owning tenant is AuthorizedOnly; everybody else, anonymous readers and authenticated strangers alike, is Public. Customs has no place in that computation, so an authority outside the tenant technically counts as a member of the public. Who receives the two roles is a Keycloak decision taken per deployment and fixed nowhere in code. Equating Restricted with Article 9(3) operators is therefore the intent of the vocabulary, and the implementation alone does not guarantee it.
The tier hangs on the property definition, together with a stated rationale. Where a regulation dictates the tier, the annotation locks the value in both directions, so it can be neither loosened nor tightened at runtime: an override on a mandated term is rejected before its direction is even examined, and the signing path ignores overrides on such terms outright. For the terms no regulation mandates, deployment and tenant policy may only ever tighten, resolved in the order tenant, deployment, semantic default, with AuthorizedOnly as the fail-closed floor. A property with no annotation at all lands on that floor as well. The issuer loads the same vocabulary artefacts the resolver's read-path enforcement is built from, so signing and filtering share one source of truth.
Two mechanisms turn a tier into disclosure, and they work differently. An SD-JWT disclosure frame keeps only the Public claims in the clear and makes everything else selectively disclosable, so the holder decides at presentation time. Tier slicing splits one subject into up to three independently signed credentials, one per tier, with the JSON-LD structural keys repeated in each slice and the non-public slices hash-chained to the public anchor through relatedResource.digestMultibase. Only the anchor is ever advertised in the linkset, and higher tiers are found through authorisation.
Enforcement on the read path has two layers, and only the lower one is active today.
Document level is enforced by OpenSearch document-level security against the stored accessLevel. A record either answers or it does not: an anonymous reader sees Public documents and gets a 404 for the rest.
Field level is implemented and sits behind dlr.field-access.enforce, default false. While the gate is off, nothing is filtered, and the policy API computes the tier matrix without enforcing it. With the gate on, the platform's own enforcer performs the projection, since the stored and served shapes differ and native field-level security cannot be used. It works on read paths only, leaves writes, patches and reconstruction untouched, and fails closed for an unclassified term or an unreachable policy store.
Selective disclosure at issuance is a separate mechanism and is unaffected by the gate. Public retrieval of a credential carries no authorisation at all. It goes through the unauthenticated search client, so document-level security is the only filter, and the signed bytes are served verbatim and never re-serialised.
Status: today the semantic vocabulary defaults are the policy in the issuer; the deployment and tenant override maps are wired but empty. Unlocking a higher tier by presenting a credential is implemented in the resolver and the verifier through an OID4VP access receipt, and it takes effect in every environment where credential types are mapped to roles, as on our development environment; where no such mapping is configured, access to a non-public slice is decided by the search role. The DPP API decides access per whole passport, so redaction within a document is likewise still open there. The relevant CEN/CENELEC standards, EN 18239 for access rights and EN 18246 for data authentication, are published; this page claims no formal conformance to either.