ObjectEvent
Purpose: Captures information about an event that happened to one or more physical or digital objects.
Example: Items were commissioned, observed, shipped, received, or decommissioned.
Key elements:
epcListandquantityList: the objects the event pertains to. You must include at least one of these elements.action: Defines the relationship of the event to the object lifecycle:ADD: Objects are commissioned or enter the scope of tracking.OBSERVE: objects were observed without lifecycle change (for example, shipping or receiving).DELETE: Objects are decommissioned or destroyed.
bizStepanddisposition: Describes the business context, such ascommissioning/active.readPointandbizLocation: Describes the observation point and subsequent location.ilmd: Instance/Lot Master Data (ILMD): Descriptive data about the objects, only permitted when action isADD(typically withbizStep = commissioning).sensorElementList: Describes sensor conditions.
JSON payload fields
The following table describes EPCIS 2.0 JSON document payload fields applicable to ObjectEvents:
| Name | Type | Description | Required or optional | Example |
|---|---|---|---|---|
| type | String | The event type discriminator: ObjectEvent. | Required | ObjectEvent |
| eventTime | DateTime (ISO 8601) | The date and time at which the event occurred. | Required | 2026-06-12T08:30:00.000Z |
| eventTimeZoneOffset | String | The local time zone offset where the event occurred, format ±HH:MM. | Required | -06:00 |
| eventID | URI | Unique event identifier. | Optional (recommended) | urn:uuid:374d95fc-9457-4a51-bd6a-0bba133845a8 |
| action | Enum | ADD, OBSERVE, or DELETE. | Required | ADD |
| epcList | Array of URIs | Instance-level EPCs the event applies to. | Conditionally required; must include this object or the quantityList array. | ["urn:epc:id:sgtin:4012345.011122.25"] |
| quantityList | Array of quantity objects | Class-level objects the event applies to. | Conditionally required; must include this object or the epcList array. | [{"epcClass": "urn:epc:class:lgtin:4012345.012345.LOTA", "quantity": 100, "uom": "KGM"}] |
| bizStep | URI or CBV string | The business step taking place (CBV vocabulary or user vocabulary). In JSON, CBV values may be expressed as bare strings, such as shipping. | Optional | commissioning |
| disposition | URI or CBV string | The business condition of the objects after the event. | Optional | active |
| readPoint | Object | The specific location at which the event was observed, such as a dock door. | Optional | { "id": "urn:epc:id:sgln:4012345.00011.987" } |
| persistentDisposition | Object | Sets or unsets dispositions that persist until explicitly changed. Contains set and/or unset arrays. | Optional | { "set": ["completeness_verified"]} |
| bizLocation | Object | The location where the objects are assumed to be after the event. | Optional | { "id": "urn:epc:id:sgln:4012345.00011.0" } |
| bizTransactionList | Array of bizTransaction objects | Business transactions associated with the event. Each entry has type (such as po, inv, desadv) and bizTransaction (the transaction identifier). | Optional (Required in TransactionEvent) | [{ "type": "po", "bizTransaction": "urn:epcglobal:cbv:bt:0614141073467:PO1234" }] |
| sourceList | Array of source objects | Identifies the originating party or location of a transfer. Each entry has type (such as owning_party, possessing_party, location) and a source URI. | Optional | [{ "type": "owning_party", "source": "urn:epc:id:pgln:4012345.00001" }] |
| destinationList | Array of destination objects | Identifies the receiving party or location of a transfer. Each entry has type (such as owning_party, possessing_party, location) and a destination URI. | Optional | [{ "type": "owning_party", "destination": "urn:epc:id:pgln:0614141.00001" }] |
| ilmd | Object | Instance/lot master data (only with action=ADD). Namespace-qualified entries. | Optional | {"cbvmda:lotNumber": "LOT2026A"} |
| sensorElementList | Array of SensorElement | Sensor metadata and readings captured with the event (temperature, humidity, GPS, and so on). | Optional | Refer to the following annotated example. |
| errorDeclaration | Object | Error declaration. | Optional | Refer to the Error declaration page. |
ILMD extension fields
Instance/Lot Master Data (ILMD) enables tracking and monitoring of individual items within the supply chain. ILMD identifies and traces products at the item level, providing accurate and detailed information about the location, status, and condition. This helps improve supply chain efficiency, reduce errors, enhance visibility, and enable better inventory management.
The cbvmda namespace is used for specifying master data attributes that may be used to describe a physical location identifier or party identifier. Master data is associated with new item instances or lots. Expiration dates, sell by, and best before dates are often queried, and should be included wherever applicable. ILMD applies to all SGTIN, LGTIN, and SSCC objects in the epcList and quantityList tags. ILMD should include one or more elements from Core Business Vocabulary Standard Section 9.2 (PDF) . Use the ISO 3166-1 alpha-2 country code format (or numeric-3 format for script independence) to specify the countryOfOrigin.
| Name | Type | Description | Required | Example |
|---|---|---|---|---|
| itemExpirationDate | date or date-time | Specifies a date in ISO 8601 format Use This parameter defines the date after which the product should not be used or consumed. For food items, the date indicates the possibility of a direct health risk resulting from use of the product after the specified date. | No | <itemExpirationDate>2026-08-01</itemExpirationDate> |
| sellByDate | date | Specifies the date by which the product should be sold. | No | <sellByDate>2026-08-01</sellByDate> |
| bestBeforeDate | date | Specifies the date before which the product is best used or consumed. | No | <bestBeforeDate>2026-06-01</bestBeforeDate> |
| lotNumber | string | Specifies a distinctive combination of numbers or letters from which the complete history of the manufacture, processing, packaging, coding and distribution of a batch can be determined. Maximum string length: 20 characters. | No | 101 |
| farmList | list | Specifies a list of one or more farms that contains identification and information about the type of farm at the location. | No | [{"farmIdentification": "urn:epc:id:sgln:0614141.00001.0", "farmIdentificationTypeCode": "EPC-SGLN"}] |
| farmList.farmIdentification | string | Specifies an identifier for the farm. The identifier is a GS1 Global Location Number (GLN), expressed as a GLN EPC URI. | No | urn:epc:id:sgln:0614141.00001.0 |
| farmList.farmIdentificationTypeCode | string | Specifies the farm identification type. | No | EPC-SGLN |
JSON payload examples
The following sections provide two EPCIS 2.0 aggregation event JSON documents.
Annotated payloads
The following example provides an annotated JSON payload of a commissioning event with sensor data. Remove the comments in this JSON file before sending data to the blockchain.
{ // Event type discriminator "type": "ObjectEvent", // Globally unique event ID (UUID URN) — needed if the event must ever be corrected "eventID": "urn:uuid:374d95fc-9457-4a51-bd6a-0bba133845a8", // Real-world occurrence time of the event (UTC, ISO 8601) "eventTime": "2026-06-12T08:30:00.000Z", // Local timezone offset where the event took place "eventTimeZoneOffset": "+01:00", // ADD: the objects are being brought into existence (commissioned) "action": "ADD", // Instance-level (serialized) identifiers of the commissioned items "epcList": [ "urn:epc:id:sgtin:4012345.011122.25", // serialized trade item #25 "urn:epc:id:sgtin:4012345.011122.26" // serialized trade item #26 ], // Business step: items are being commissioned (CBV bizStep) "bizStep": "commissioning", // Condition of the items after the event: active in the supply chain "disposition": "active", // Physical point where the event was observed (e.g., production line scanner) "readPoint": { "id": "urn:epc:id:sgln:4012345.00005.line-1" }, // Location where the items are assumed to be after the event (the plant) "bizLocation": { "id": "urn:epc:id:sgln:4012345.00005.0" }, // Instance/Lot Master Data — only allowed because action = ADD "ilmd": { // CBV master-data attribute: production lot number "cbvmda:lotNumber": "LOT2026A", // CBV master-data attribute: item expiration date "cbvmda:itemExpirationDate": "2027-06-11" }, // Sensor data captured at commissioning time ("How" dimension) "sensorElementList": [ { // Metadata describing the sensor reading context "sensorMetadata": { // Time the sensor reading was taken "time": "2026-06-12T08:29:50.000Z", // Device identifier (GIAI of the sensor) "deviceID": "urn:epc:id:giai:4012345.sensor-77", // Reference to device metadata "deviceMetadata": "https://id.gs1.org/8004/4012345sensor-77" }, // One or more individual sensor readings "sensorReport": [ { // Measurement type from the CBV measurement vocabulary "type": "Temperature", // Measured value "value": 21.4, // Unit of measure per UN/CEFACT Rec 20 (CEL = degrees Celsius) "uom": "CEL" } ] } ] } The following example provides an annotated JSON payload of an observed shipping event. Remove the comments in this JSON file before sending data to the blockchain.
{ // Event type discriminator "type": "ObjectEvent", // Unique event identifier "eventID": "urn:uuid:5d1c5b21-9a64-4f1d-9d2c-1f6f1f8a2b1e", // When the shipment was observed leaving "eventTime": "2026-06-12T14:05:00.000Z", "eventTimeZoneOffset": "-06:00", // OBSERVE: nothing changed about the objects' lifecycle; they were observed shipping "action": "OBSERVE", // The logistic unit (pallet SSCC) being shipped "epcList": [ "urn:epc:id:sscc:4012345.0111222333" ], // CBV business step: shipping "bizStep": "shipping", // CBV disposition: goods are now in transit "disposition": "in_transit", // Dock door reader where the pallet was observed "readPoint": { "id": "urn:epc:id:sgln:4012345.00011.dock-3" }, // Purchase order and despatch advice this shipment fulfills "bizTransactionList": [ { // Transaction type: purchase order (CBV) "type": "po", "bizTransaction": "urn:epcglobal:cbv:bt:4012345000009:PO-2026-0457" }, { // Transaction type: despatch advice / ASN (CBV) "type": "desadv", "bizTransaction": "urn:epcglobal:cbv:bt:4012345000009:ASN-88123" } ], // Transfer semantics: ownership moving from seller to buyer "sourceList": [ { "type": "owning_party", "source": "urn:epc:id:pgln:4012345.00000" } ], "destinationList": [ { "type": "owning_party", "destination": "urn:epc:id:pgln:0614141.00000" } ] } Ready to use
The following shipping event JSON file is ready to use. Define your own values for each tag, then send the data to the blockchain.
{ "type": "ObjectEvent", "eventTime": "2025-12-19T16:16:00.000-03:00", "recordTime": "2025-12-23T18:11:25.000-03:00", "eventTimeZoneOffset": "-08:00", "eventID": "urn:uuid:00000000-0000-0000-0000-000000000001", "epcList": [ "urn:gdst:example.com:lpn:obj:acmeseafood.LPN-EXAMPLE-0001" ], "action": "OBSERVE", "bizStep": "shipping", "disposition": "in_transit", "bizLocation": { "id": "9999999000014" }, "bizTransactionList": [ { "type": "po", "bizTransaction": "urn:epcglobal:cbv:bt:9999999000014:PO-EXAMPLE-0001" } ], "sourceList": [ { "type": "owning_party", "source": "urn:gdst:example.com:party:acmeseafood.0" } ], "destinationList": [ { "type": "owning_party", "destination": "urn:gdst:example.com:party:bigboxretail.0" } ], "ilmd": { "gdst:broodstockSource": "Farmed", "gdst:aquacultureMethod": "semi-intensive" }, "gdst:productOwner": "urn:gdst:example.com:party:acmeseafood.0", "cbvmda:certificationList": { "certification": [ { "gdst:certificationType": "urn:gdst:certType:harvestCoC", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP (Processing Plant)", "certificationValue": "4", "certificationIdentification": "CERT-PROC-001" }, { "gdst:certificationType": "urn:gdst:certType:harvestCert", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP - (Farm)", "certificationValue": "4", "certificationIdentification": "CERT-FARM-001" }, { "gdst:certificationType": "urn:gdst:certType:harvestCoC", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP (Hatchery)", "certificationValue": "4", "certificationIdentification": "CERT-HATCH-001" }, { "gdst:certificationType": "urn:gdst:certType:harvestCoC", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP (Feed Mill)", "certificationValue": "4", "certificationIdentification": "CERT-FEED-001" } ] }, "cbvmda:informationProvider": "urn:gdst:example.com:party:acmeseafood.0" } Updated about 3 hours ago
Did this page help you?