Extension Documentation

[aopel]

Are there any examples of how to format extensions in JSON? Specifically for custom ILMD or custom event-level data. It is unclear how to incorporate custom data into our EPCIS output that isn’t defined as ILMD and examples would be the most effective way for us to understand how to incorporate the correct structure into our outputs.

[mgh128]

Yes, you can find some examples within https://github.com/gs1/EPCIS/tree/master/JSON e.g. https://github.com/gs1/EPCIS/blob/master/JSON/Example_9.6.1-ObjectEvent.jsonld where you can find example:myField as an example of a vendor / user extension.

We're using a JSON-LD data structure in which we hide most of the JSON-LD weirdness in the standard @context resource for EPCIS, so that most of the body can be treated as JSON by those who aren't interested in the JSON-LD / Linked Data aspects. However, user/vendor extension fields should be expressed as Compact URI Expressions [CURIE]s e.g. example:myField and the namespace mapping/expansion for user-defined namespaces should be declared in an additional @context resource if you want those user-defined / vendor-extension fields to work correctly also for anyone consuming the EPCIS data as JSON-LD.

In https://github.com/gs1/EPCIS/blob/master/JSON/Example_9.6.1-ObjectEvent.jsonld you can see an example of this, in which an example organisation has defined that the example: CURIE prefix maps to a Web URI namespace with a URI stem of http://ns.example.com/epcis/ meaning that example:myField = http://ns.example.com/epcis/myField

Best practice is for those user-defined / vendor-defined extension fields to resolve to an online definition, just as properties within schema.org or the GS1 Web vocabulary also resolve to online definitions - see for example gs1:gtin

For further info about compact URI expressions [CURIE]s, please see https://www.w3.org/TR/curie/ CURIEs look similar to QNames used in XML, but unlike QNames, they usually concatenate to Web URIs that resolve to a useful definition.

[aopel]

Thanks for the explanation - what should be the Web URI namespace and the URI stem so that the user-defined / vendor-extension fields work correctly as consumption? Is that something we have to create/define ourselves?

[mgh128]

Exactly. Each user / vendor / consortium can reuse their existing own Internet domain name (or register one at absolutely minimal cost) and then use that in the URI stem for their extension namespace, thus automatically avoiding any collision with extension fields or extension code lists defined by others.

Best practice would be for those Web URIs to actually resolve to online definitions, ideally also with embedded machine-interpretable Linked Data (e.g. a block of JSON-LD) using W3C Linked Data standards such as RDF, RDFS, OWL, SKOS, just as GS1 has done for terms within the GS1 Web vocabulary and as we're in the process of setting up for the standard core terms within EPCIS and CBV.