EPCIS traceability alignment

[nissimsan]

@mgh128, I just got a link to your white paper from Phil:
https://gs1.github.io/EndToEndTraceability/GS1-WhitePaper-VerifiableCredentials-EPCIS-end-to-end-traceability.pdf
Some of the terms seem very similar to event types which we recently added to this repo: TransformEvent, TransferEvent, and a few others. It'd be great if you can take a quick look from a harmonization point of view. Specifically, we shouldn't be re-invent something like https://w3id.org/traceability#TransformEvent if there is already a GS1 definition.

[mgh128]

Hi @nissimsan
Thanks for the interest. The GS1 EPCIS standard ( http://gs1.org/epcis ) was first ratified and published in 2007 and currently (as of v1.2) supports four event types:

• ObjectEvent
• AggregationEvent
• TransactionEvent
• TransformationEvent

v2.0 (the result of almost four years of major modernisation efforts, including the addition of JSON/JSON-LD data format, REST / OpenAPI interface, business-relevant sensor data and various other improvements, including persistentDisposition and formal Linked Data ontologies for EPCIS and CBV) also introduces a further standardised event type (AssociationEvent) for more permanent associations (such as the attachment of a sensor device to a returnable transport container such as a plastic crate, such that the sensor device remains attached even when the fruit/vegetables are emptied from the crate). You're very welcome to look at https://github.com/gs1/EPCIS to see our current draft examples and schema. Publication of EPCIS/CBV v2.0 and its schema and artefacts is expected within Q2 of 2022. We're currently doing final corrections and checks.

I took a quick look at TransformEvent, TransferEvent and I agree that there is some potential overlap.

Your TransformEvent appears to correspond to our EPCIS TransformationEvent in which the fields inputEPCList and outputEPCList are used to specify instance-level identifiers (e.g. a product GTIN + serial number) for the inputs and outputs to the transformation process, while inputQuantityList and outputQuantityList are used to specify quantities of class-level identifiers (e.g. 100g of product with a specific GTIN) for the inputs and outputs to the transformation process. These appear to correspond to your properties consumedProducts (inputs) and newProducts (outputs), respectively, though I'm sure you know better than I do whether you're using instance-level identification only or also supporting quantities of class-level identifiers (e.g. 50 grams of tomato purée with this GTIN).
See for example: https://github.com/gs1/EPCIS/blob/master/JSON/Example_9.6.4-TransformationEvent.jsonld

Your TransferEvent appears to correspond to something which we would usually model in GS1 EPCIS as an ObjectEvent with "bizStep" : "shipping" or "bizStep" : "receiving". We use the "source" and "destination" fields to identify the locations or organisations involved in the transfer, while the source/destination type indicates whether the value is a location, possessing party or owning party - and each event may specify a source or destination for each of these types. See for example https://github.com/gs1/EPCIS/blob/master/JSON/Example_9.6.2-ObjectEvent.jsonld
So our source and destination fields appear to correspond closest to your fields initiator and receiver.

A general comment I would make is that EPCIS event data generally does not embed significant amounts of master data about products, organisations, locations. Although this is possible using GS1 CBV master data attributes and instance/lot master data, an alternative approach would be to make use of GS1 Digital Link URIs (see https://www.gs1.org/standards/gs1-digital-link ) and their resolver infrastructure to be redirected to (by specifying a link type of https://www.gs1.org/voc/masterData ) sources of master data about that object / organisation / location, such as a block of JSON-LD published online using Linked Data markup using schema.org and/or the GS1 Web vocabulary ( https://gs1.org/voc ). So our EPCIS approach is perhaps less self-contained than your approach but that's to keep the event data volumes more manageable in EPCIS event repositories.

Happy to discuss further. I hope the examples are helpful in the meantime.
You can still find the public review drafts for EPCIS/CBV v2.0 at https://www.gs1.org/standards/development-work-groups/public-reviews#EPCISCBV_Public-Review-2021 (from October 2021) but please be aware that there have been several improvements since then, in response to numerous public review feedback comments - so they are somewhat stale relative to what will be published soon as EPCIS/CBV v2.0.

[VladimirAlexiev]

hi Mark @mgh128 !

EPCIS event data generally does not embed significant amounts of master data... to keep the event data volumes more manageable

Right!
But RDF doesn't work in terms of messages. If you store both event data and master data in a GraphDB (hint, hint :-), you can generate responses that include more of the data embedded in one JSONLD, as the traceability examples show.

In JSONLD it's a simple matter of defining in a frame whether the master data should be @embed in the events, or kept at top level.

The real problem is in the structure of the JSON Schemas that traceability relies on. They are more fixed in their @embed intent, and more rarely offer the use of a reference URL that can be resolved separately (or placed at top level): #290

[CraigRe]

By the way, some of you might previously have been looking at github.com/gs1/EPCIS .
Now that EPCIS & CBV 2.0 have been ratified, normative artefacts and example files can now be found at https://ref.gs1.org/standards/epcis/artefacts .
If you're having difficulty accessing anything in particular, please let us know and we'll help.

[nissimsan]

@CraigRe, noting that github.com/gs1/EPCIS is 404'ing. Is that a private repo?

[mgh128]

@nissimsan - the former repository at github.com/gs1/EPCIS has moved to a private repository
I have pointed out to GS1 that it would probably still make sense for a public-facing repository to exist on GitHub, even if it only contains the ratified artefacts that are now at https://ref.gs1.org/standards/epcis/artefacts

[VladimirAlexiev]

https://github.com/w3c-ccg/traceability-vocab/blob/main/docs/openapi/components/schemas/common/CommissionEvent.yml corresponds to epcis:CreateEvent with epcis:action="CREATE"

[mgh128]

https://github.com/w3c-ccg/traceability-vocab/blob/main/docs/openapi/components/schemas/common/CommissionEvent.yml corresponds to epcis:CreateEvent with epcis:action="CREATE"

Almost correct - except that "CREATE" is not a valid value for the field epcis:action - within an EPCIS ObjectEvent, the defined string value of "ADD" is used instead, to indicate the creation or first appearance of objects in the supply chain.

Typically, in EPCIS a commissioning event is represented as an epcis:ObjectEvent with epcis:action="ADD" and epcis:bizStep = cbv:BizStep-commissioning (if the output objects have globally unique serialised identifiers) or epcis:bizStep = cbv:BizStep-creating_class_instance (if the output objects do not have globally unique serialised identifiers)

There are also situations where input objects (such as ingredients) are irreversibly transformed into output objects (such as mixes or products) - and in this situation, the commissioning of those output objects can be represented via an epcis:TransformationEvent - but noting that epcis:TransformationEvent has no epcis:action field, although epcis:bizStep = cbv:BizStep-commissioning or epcis:bizStep = cbv:BizStep-creating_class_instance could still be used.

In the above, the CURIE prefix epcis = https://ref.gs1.org/epcis/ and cbv = https://ref.gs1.org/cbv/

[nissimsan]

@mgh128, @CraigRe and I talked this over yesterday. A sensible next step will be to start implementing the EPCIS event model with the terms defined in https://ref.gs1.org/epcis/.

https://ref.gs1.org/docs/epcis/examples includes examples we can use for VC examples.

[brownoxford]

Need for someone to pick this up - @nissimsan is happy to collaborate and discuss any work already done

[nissimsan]

@paulfdietrich, let's collaborate on this as discussed on the call.

[ghost]

@nissimsan happy to try to lend some insight here. I'm with the GS1 US standards team and I focuse on EPCIS. I work with @paulfdietrich, @mgh128, and @CraigRe .

A couple of quick thoughts:

1. EPCIS defines an abstract data model for recording and sharing physical object-centric events occurring across the supply chain. When two disparate systems are exchanging EPCIS data it's done as a collection of events assembled together in an EPCIS Document or EPCIS Query Document. EPCIS data differs from other business data because it doesn't correlate with a concrete transaction recognized by trading partners (e.g., Bill of Lading, Purchase Order). It envisions a data sharing model of inter-connected EPCIS repositories utilizing APIs to execute queries for the events held by respective trading partners in their chosen repositories.

2. The EPCIS data model accepts "vocabulary" defined with a companion standard called the Core Business Vocabulary (CBV) - https://ref.gs1.org/standards/cbv/ We made a concerted effort with the development of EPCIS 2.0 to utilize the GS1 Web Vocabulary to take advantage of Linked Data and the Semantic Web. This means that many vocabulary in EPCIS 2.0 can utilize the GS1 Web Vocabulary for populating relevant fields.

I'm late to the party but happy to help interpret how GS1 Standards (EPCIS and others) could be utilized with a Verifiable Credential based Traceability Vocabulary. I saw the use of GS1 ID Keys in a few of the other example VCs. I may not be able to attend the calls regularly or contribute PRs but I'm happy to respond to issues like this and point you all in the right direction. Let me know if that would be helpful or other support you all might need.

[mgh128]

Thanks to Neil @visibleOrigins for that summary. Regarding what he said :

EPCIS data differs from other business data because it doesn't correlate with a concrete transaction recognized by trading partners (e.g., Bill of Lading, Purchase Order). It envisions a data sharing model of inter-connected EPCIS repositories utilizing APIs to execute queries for the events held by respective trading partners in their chosen repositories.

I'd like to assure everyone that each EPCIS event can reference one or more associated business transactions by ID and by type (see the code list at https://ref.gs1.org/cbv/BTT ). Each EPCIS event can express a property/field called bizTransactionList which expects one or more instances of a BizTransaction class that then has a property bizTransactionType (appearing in the JSON/XML syntax as 'type') that expects a value from the CBV code list BTT, while its RDF Subject is the URI of the business transaction, though the JSON / XML syntax shows this as a 'bizTransaction' property (really just an alias of @id)

I think the point that Neil @visibleOrigins was trying to make is that the event data isn't embedded within EDI-style transaction messages that contain significant master data. EPCIS events can be retrieved and exchanged on-demand, typically between trading partners. If we need to reference master data, our current best practice is to do so by reference rather than embedding much master data within the EPCIS event data. The GS1 Web vocabulary is an external extension to schema.org and enables products (but also organisations and locations) to be described in greater detail than using schema.org in isolation. Further updates are currently in progress to enhance the expressiveness of the GS1 Web vocabulary in relation to organisations and locations and will appear in updates over the next few months.
GS1 Digital Link defines a Web URI syntax for GS1 identifiers (such as GTIN, GLN etc.), which can already link via resolver infrastructure to multiple types of links to various online information resources, including master data (which in turn could be a block of JSON-LD data expressed using terms from the GS1 Web vocabulary and schema.org, in which GS1 Digital Link URIs can also appear as the RDF Subject or Object, where appropriate).

[ghost]

Great additions @mgh128 !

I'll try to be a little more clear. I was trying to express that several of the example Credentials already built by this community have a correlary to an "official form" or commonly recognized transaction between two trading partners. For example, the CBP Form 7501 - Entry Summary Credential maps to CBP Form 7501 and the Bill of Lading Credential maps to a commonly recognized document that is typically exchanged between a shipper, receiver, carrier, freight forwarder, customs brokers, etc.

EPCIS data on the other hand doesn't represent discrete singular documents. When this data is exchanged, it's a collection of events. For example, a Warehouse receiving a shipment could query the receiver for the events about the journey of the various shipping containers in that shipment. The receiver could return this collection:

• Events reflecting the identies of pallets packed into each container
• An event for the containers being collected from the shippper
• An event of the containers arriving at the carrier's container yard
• An event of the containers being loaded onto the carrier's ship
• An event of the containers being offloaded at the destination port
• An event of the containers being associated with a customs entry transaction
• An event of the containers being collected from the carrier's yard for transport to the receiver

I'm trying to provide context because it may not make sense for single EPCIS events to be a Credential but maybe collections of events (i.e., EPCIS Documents) would be Credentials.

[nissimsan]

@nissimsan to action this still.

[OR13]

Still ready for PR @nissimsan