Digital Traceability Events

info

Please note that this specification is suitable for pre-production pilot implementations.

Artifacts

V0.8.0 Schema and Samples

Artefact	Description
DigitalTraceabilityEvent.json	The UNTP credential envelope. Defines the VCDM wrapper and references the GS1 EPCIS JSON Schema for the events themselves.
DigitalTraceabilityEvent_embedded.json	A self-contained copy of the envelope schema with the GS1 EPCIS definitions embedded, for tools that cannot resolve an external $ref. Generated from the envelope schema and the GS1 EPCIS JSON Schema; the envelope schema is normative.
GS1 EPCIS JSON Schema	Normative event structure. Published by GS1, referenced unmodified.
Sample instances	Sample DTE credentials. See Choosing an Event for picking the right event type.

Vocabulary and Context

A DTE references three JSON-LD contexts, in this order:

"@context": [
  "https://www.w3.org/ns/credentials/v2",
  "https://vocabulary.uncefact.org/untp/0.8.0/context/",
  "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"
]

• The W3C VCDM context defines the credential envelope.
• The UNTP context defines only the wrapper terms: the DigitalTraceabilityEvent credential type, CredentialIssuer and issuingSoftware. It contributes nothing to the event body.
• The GS1 EPCIS context defines the event semantics.

Further entries MAY be appended. Unlike other UNTP credentials, a DTE also permits inline context objects in this array, because EPCIS user extensions declare their namespaces at document level and the credential occupies that position.

The three contexts compose without collision. All three are @protected, so a term that two of them defined differently would prevent composition. They share no substantive terms: only id, type and xsd, which every JSON-LD context defines the same way, and JSON-LD 1.1 permits redefining a protected term with an identical definition. No nesting is required. Nesting would in any case conflict with VCDM 2.0, which discourages a nested @context inside credentialSubject.

Sample Credential

A hosted, signed sample credential with QR code, as on the other credential pages, will be published once a 0.8.0 DTE has been issued and signed. The existing hosted sample is in the withdrawn 0.7.0 format.

Overview

A Digital Traceability Event (DTE) carries one or more GS1 EPCIS 2.0 events, issued as a W3C Verifiable Credential. DTEs are lightweight credentials that record what happened to which products, where, when and by whom, across a value chain. Each DTE can be independently verified, and because its events reference products, facilities and parties by resolvable identifiers, it links to other credentials such as Digital Product Passports and Digital Conformity Credentials. DTEs are discoverable from identity resolvers using the product identifier, subject to access control where data is commercially sensitive.

Any supply chain, however complex, can be described by what happens to its products: they are made, moved, or modified. Together, make and move events record the stocks and flows through each facility, which is what enables facility-level volume reconciliation of sustainability claims. An event records what physically moved; it does not state a chain of custody model, because the model depends on which attribute is being claimed. Chain of Custody and Mass Balance is the normative reference for how the models are defined and which claims they support. Modify events record changes to a product's state, or observations of it, without a change of identity: inspection, repair, sensor observation and end of life.

No dependency on GS1 identifiers

UNTP uses GS1 EPCIS as its traceability event standard, but a DTE has no dependency on GS1 identifiers. Products, facilities and parties may be identified using any identifier scheme, such as a national business register, a facility register, a sector scheme or a W3C DID, provided each identifier is a URI. GS1 identifiers are equally valid, and different schemes may be mixed within a single event. See TEV-00 and Any UNTP Identifier.

EPCIS 2.0 is the normative event model for UNTP. It is used as published, without a restrictive UNTP profile. UNTP adds the credential envelope that makes an event independently verifiable and linkable to the rest of the UNTP credential suite. The event itself is unmodified.

Conceptual Model

Every traceability event records one of three kinds of product lifecycle activity:

• Make — products come into existence, are transformed, or are built into something else: commissioned, produced from input products, or assembled at a facility.
• Move — products change location without changing identity: they are packed, shipped, received or stored.
• Modify — an existing product changes state, or its state is observed, without changing identity: it is inspected, repaired, monitored by sensors, or taken out of use.

Make, move and modify are not separate schemas. Each is expressed with one or more EPCIS event types, chosen as described in Choosing an Event.

The questions in the diagram map onto the EPCIS event as follows, each backed by a controlled vocabulary from the CBV where one applies. Note that the diagram's what is the lifecycle activity, while EPCIS's own What is the objects, which the diagram calls which.

Diagram	EPCIS	What it records
WHAT	Event type and action; eventTime with eventTimeZoneOffset; bizStep and disposition	The activity: its type, when it occurred in local time, the business step it belongs to, and the objects' business condition afterwards. A disposition is presumed to hold until a later event contradicts it.
WHICH	epcList, quantityList and their input, output and child variants; parentID	The objects the event is about: individually identified items, or measured quantities of a product class. parentID names the containing object of an aggregation or association.
WHERE	readPoint, bizLocation	Where the event was observed, and where the objects are expected to be afterwards. A business location is presumed to hold until a later event says otherwise.
WHO	The credential issuer; sourceList, destinationList	The party asserting the event, and the parties and locations involved where custody changes.
EVIDENCE	sensorElementList	Sensor observations made during the event: device metadata and one or more readings.
REFERENCE	bizTransactionList; identifiers resolved through an identity resolver	Business documents linked to the event, and the passports, facility records and other credentials reached by resolving the product, facility and party identifiers.

The event type — ObjectEvent, TransformationEvent, AggregationEvent, TransactionEvent or AssociationEvent — determines which fields of the WHICH row apply; the other rows are common to all types. Alongside them, action records how the event relates to the objects' lifecycle: ADD when they enter it, OBSERVE when they are seen within it, DELETE when they leave it.

Requirements

The traceability event meets the following requirements, in addition to the general UNTP Requirements.

ID	Name	Requirement Statement	Solution Mapping
TEV-00	Identifier independence	The traceability event MUST NOT depend on the use of GS1 identifiers, or of any other particular identifier scheme. Products, facilities and parties MUST be identifiable using any identifier scheme.	EPCIS requires identifiers to be URIs, not GS1 identifiers. Any UNTP identifier that follows Identifier Representation can be used in epcList, quantityList (epcClass), readPoint, bizLocation, sourceList and destinationList, and schemes may be mixed within an event; see Any UNTP Identifier. The samples use no GS1 identifiers.
TEV-01	Sub-components	The traceability event MUST provide a mechanism to trace from a DPP representing a product assembly to the individual DPPs of each sub-assembly component part.	AssociationEvent with the assembly as parentID and the component parts in childEPCs. Components keep their identity, so each sub-assembly DPP stays resolvable from the event.
TEV-02	Consumed materials	The traceability event MUST provide a mechanism to trace a manufactured product DPP back to the DPPs representing batches of input materials that are consumed in manufacturing one or more output products.	TransformationEvent with inputQuantityList and outputQuantityList.
TEV-03	Aggregated bundles	When a DPP represents an aggregated bundle of similar items (e.g. a pallet of cotton bales) then the traceability event MUST provide a means to allocate the aggregate measures to each individual item (i.e. each bale).	AggregationEvent with parentID and childEPCs, or childQuantityList where the contents are class-level quantities. Distinct from transformation, so the bundle can later be disaggregated with action: DELETE.
TEV-04	Transportation	When a product (or consolidated consignment) is shipped from one physical location to another, the traceability event MUST provide a means to record the movement and associate sustainability measures such as transport emissions to the shipped bundle.	ObjectEvent with bizStep: shipping / receiving, or departing / arriving, and sourceList / destinationList using the location and possessing_party types. Transport measurements such as emissions are carried in sensorElementList.
TEV-05	Items or quantities	Traceability events MUST work equally well whether the input or output items are individually serialised items or measured quantities (mass or volume) of a product class.	epcList / inputEPCList / outputEPCList for instance-level identifiers; quantityList / inputQuantityList / outputQuantityList for class-level quantities. Where a batch is split across movements, the moved quantity is first packed into an identified container; see Move.
TEV-06	IoT sensor data	Traceability events will often be generated by or associated with physical sensor readings. In such cases, the traceability event SHOULD support the association of sensor data with the event.	sensorElementList, with sensorMetadata for the device and sensorReport for the readings.
TEV-07	Time and location	Traceability events MUST always record the timestamp and physical location of the event so that multiple events can be connected in time and space.	eventTime and eventTimeZoneOffset are mandatory on every EPCIS event. readPoint and bizLocation carry location; EPCIS marks both optional, but bizLocation is presumed to hold until contradicted by a subsequent event, so location carries forward through an event stream in the same way as disposition.
TEV-08	Product disposition	The traceability event MUST record the state of each product after the event has occurred (e.g. new, consumed, repaired, recycled, disposed) so that product status can be tracked through its lifecycle.	disposition using CBV Disp-* values. It applies to the objects in the event and is presumed to hold until contradicted by a later event, so a product's current state is the most recent disposition asserted for it.
TEV-09	Activity classification	The traceability event MUST support industry-specific classification of the business activity (e.g. ginning, spinning, weaving in textiles) so that generic event types can carry domain-specific context.	bizStep using CBV values, or a sector-namespaced extension URI.
TEV-10	Related documents	The traceability event SHOULD support links to related credentials and documents such as Digital Product Passports, Digital Conformity Credentials, test results, or shipping manifests.	A Digital Product Passport or Digital Facility Record is reached by resolving the product or facility identifier through an Identity Resolver. Business documents are linked through bizTransactionList, using CBV business transaction types: cert for conformity credentials, bol for bills of lading, testres for test results, prodorder for production orders.
TEV-11	Related parties	The traceability event MUST identify the parties involved in the event and their roles (e.g. manufacturer, shipper, receiver) to establish accountability.	sourceList and destinationList, using the CBV types owning_party and possessing_party; other roles may use a sector-namespaced extension URI. The credential issuer identifies the party asserting the event.
TEV-12	Confidentiality	The traceability event SHOULD support access control mechanisms so that commercially sensitive data can be selectively shared.	Decentralised Access Control, applied per credential.
TEV-13	Mass-balance support	The traceability event model MUST support facility-level mass-balance accounting so that a facility's claimed outputs can be verified against its documented inputs and inventory.	TransformationEvent and shipping / receiving ObjectEvent together model stocks and flows, as described in Chain of Custody.

Logical Model

Unlike the other UNTP credentials, the DTE is not an assembly of components from the UNTP core vocabulary: its credential subject is defined by the GS1 EPCIS JSON Schema.

Loading schema viewer...

The DTE credential wraps one or more EPCIS events as its credentialSubject. The EPCIS context is declared once at credential level and the events need not repeat it, exactly as events inside an EPCISDocument rely on the context declared by the document. The credentialSubject is therefore not, by itself, a drop-in EPCIS document: tooling that expects one wraps the events in an EPCISDocument and re-attaches the EPCIS context, which changes nothing in the events themselves.

Grouping several events into one credential is permitted and is appropriate where the events form a single business fact, such as the two halves of a long-running transformation. A credential is the unit of signature, revocation and access control, so events with different confidentiality requirements belong in different credentials.

The event structure is not reproduced here: UNTP does not add, remove or constrain any EPCIS event property.

Implementation Guidance

UNTP makes three choices about how EPCIS is used. None of them changes the EPCIS data model.

JSON-LD Only

EPCIS 2.0 defines two syntaxes for the same data model: XML, carried over from EPCIS 1.x, and JSON-LD. UNTP requires JSON-LD. A DTE is a Verifiable Credential, so its @context is mandatory and its credentialSubject is JSON by construction; the schema references the GS1 EPCIS JSON Schema rather than the XML schema.

Any UNTP Identifier

EPCIS requires identifiers to be URIs. It does not require them to be GS1 identifiers. Identifiers in a DTE are ordinary UNTP identifiers and follow the rules in Identifier Representation; identifiers from different schemes MAY be mixed within a single event.

No REST API Required

EPCIS defines a data model, the Core Business Vocabulary (CBV), and a set of interfaces for exchanging events. UNTP requires the first two and does not require the third. DTEs are distributed as Verifiable Credentials behind an HTTPS URL, discoverable through an identity resolver, rather than through the EPCIS Capture and Query interfaces.

EPCIS 2.0 defines conformance for data separately from conformance for its interfaces: section 14.1 covers XML data and 14.7 covers JSON-LD data, while the remaining clauses of section 14 cover the capture, query and REST interfaces. A DTE is required to satisfy the data clauses. Implementers already operating Capture and Query interfaces may continue to do so; UNTP is an additional distribution channel, not a replacement.

Choosing an Event

This section is a guide to answering given my process, which event do I emit?, worked through with UNTP identifiers. GS1's EPCIS & CBV Implementation Guideline remains the reference for cases beyond those below.

Each event records a single business step, and event boundaries follow the boundaries of the activity itself: distinct operations, at distinct times or locations, are distinct events. Start from what you are doing to the product: making it, moving it, or modifying it. The grouping follows the purpose of the process, not the structure of the event, so the same event type can appear under more than one heading.

The examples are drawn from one product's life: a mine commissions a batch of copper concentrate and ships it in a container to a refinery, which unpacks it, smelts it into anodes and refines them into cathode; the refinery loads part of the cathode into a shipping container that departs for a battery plant, where it arrives, is unloaded and stored, and the plant builds a battery from it; the battery is tested, installed into a vehicle, repaired years later, and finally removed from the vehicle and decommissioned. Each example links to a complete credential.

The examples illustrate the event types, not the traceability requirements of any one sector. Sector-specific scenarios, such as fishing and landing events in seafood, or ginning and spinning in textiles, are expected to come from UNTP extensions, which can add worked examples and the industry business step vocabulary the events use.

Each table row gives the event type, the action where the type has one, and the bizStep and disposition that a process of that kind typically uses. The bizStep names the step, and the disposition records the state the product is in afterwards, which holds until a later event replaces it. A disposition is set only where the step changes the product's state; the CBV recommends omitting it rather than using in_progress, which adds little. The values are CBV terms and are a starting point, not a constraint: use another CBV value, or a sector-namespaced extension URI, where it describes the process more precisely. The examples show them in place, along with the product lists described in the Conceptual Model.

Make

Product comes into existence or is built into something else: commissioning, transformation and association.

Your process	Event and typical values	Example
A product or batch is identified for the first time and has no traceable input, such as harvest, mining or catch	ObjectEvent · ADD bizStep: commissioning for a serialised item, creating_class_instance for a batch disposition: active	concentrate_commissioned_at_mine
Inputs are consumed and different outputs are produced, irreversibly	TransformationEvent bizStep: creating_class_instance for batch outputs, commissioning for serialised outputs disposition: active	concentrate_smelted_into_anodes (batch output), cathode_assembled_into_battery (serialised output)
As above, but inputs and outputs are recorded at different times, such as anodes charged into refining cells and cathode harvested two weeks later	Two or more TransformationEvents sharing a transformationID bizStep: as above disposition: active on the event recording the outputs	anodes_refined_into_cathode
A component is built into an assembly, or a sensor or equipment is installed into an asset or facility	AssociationEvent · ADD, or DELETE to end the association bizStep: installing or assembling; removing on DELETE disposition: active; usually omitted on DELETE	battery_installed_in_vehicle (ADD), battery_removed_from_vehicle (DELETE)

Transformation, aggregation or association? All three bring objects together, and AggregationEvent and AssociationEvent are structurally identical, so the choice is semantic rather than structural.

• Transformation consumes the inputs. Their identity does not survive and the operation cannot be undone. Use TransformationEvent.
• Aggregation is a temporary relationship such as packing, loading or palletising. The children keep their identity and can be separated again. Use AggregationEvent, covered under Move.
• Association is a lasting relationship, permanent or semi-permanent: a component built into an assembly, a sensor fitted to a reusable asset, equipment installed into a facility. Use AssociationEvent. It is the only event type whose parentID may be a location identifier.

Move

Product changes location without changing identity: packing and unpacking for transport, shipping, receiving, and storage within a facility.

Packing can look like a Make step, since it creates or reuses a container identifier, but its purpose is to give the moved goods an identity that the shipping, receiving and unpacking events can reference.

Your process	Event and typical values	Example
Items are combined into a case, pallet or container, and could later be separated	AggregationEvent · ADD bizStep: packing disposition: usually omitted; container_closed once sealed	concentrate_packed_at_mine
Goods leave a facility	ObjectEvent · OBSERVE bizStep: shipping disposition: in_transit	concentrate_leaves_mine
Goods arrive at a facility	ObjectEvent · OBSERVE bizStep: receiving disposition: usually omitted	concentrate_arrives_at_refinery
A case, pallet or container is broken down	AggregationEvent · DELETE bizStep: unpacking disposition: usually omitted	concentrate_unpacked_at_refinery
A product is put into a sub-location within a facility, such as a storage bay	ObjectEvent · OBSERVE bizStep: storing disposition: usually omitted bizLocation: the sub-location, distinct from the readPoint	cathode_stored_at_plant

Whether an ObjectEvent alone can describe a movement depends on how the goods are identified. A serialised item carries an identifier that no other product shares, so an ObjectEvent naming it is unambiguous: what is shipped is exactly what is received. A batch can be split. A quantityList entry only says that some quantity of the batch moved, and if the same batch leaves in several consignments nothing distinguishes one from another, so the receiver cannot tell which part of the batch has arrived. To move part of a batch unambiguously, pack it first: an AggregationEvent places the quantity in a case, pallet or container with an instance identifier of its own, and the shipping and receiving events then name that container.

The CBV also defines an alternative vocabulary for the same movement, departing and arriving in place of shipping and receiving, with loading and unloading as AggregationEvents into and out of the shipping conveyance. The two are mutually exclusive, so describe a given movement with one vocabulary only. The cathode leg of the examples uses the second, with the carrier's container as the parent: cathode_loaded_into_container, container_leaves_refinery, container_arrives_at_plant and container_unloaded_at_plant.

Modify

An existing product changes state, or its state is observed, without changing identity: sensor readings, inspection, test, repair, refurbishment, and end of life.

Your process	Event and typical values	Example
A sensor records readings on the product, such as test measurements, temperature, humidity or shock	ObjectEvent · OBSERVE bizStep: sensor_reporting for a standalone reading, or the step the readings belong to (inspecting in the example) disposition: usually omitted, as the product's state is unchanged	battery_tested_at_plant
A product is inspected or tested, keeping its identity	ObjectEvent · OBSERVE bizStep: inspecting disposition: conformant or non_conformant	battery_tested_at_plant
A product is repaired or refurbished, keeping its identity	ObjectEvent · OBSERVE bizStep: repairing disposition: available	battery_repaired_at_workshop
A product leaves the supply chain, such as by destruction, disposal or decommissioning	ObjectEvent · DELETE bizStep: decommissioning, or destroying disposition: inactive, or destroyed	battery_decommissioned