index of the examples

[VladimirAlexiev]

Examples are great, examples in multiple formats even better. But if I'm a new developer, how will I know which example demonstrates what?

I think we need an index (README.md) listing all examples, and describing what's special about them.

@RalphTro or @CraigRe can you start this? Below are some rough notes when I first saw EPCIS 2.

Note: #231 and #233 and #236 and #237 ask for more examples

---

XML Examples

• EPCIS_2_0 - 9_6_1 - 2020_06_18a.xml: Shipping and receiving event, of SGTIN goods, involving a transaction with Purchase Order (po) and Despatch Advice (desadv)
• CBV_2_0 - 11_4 - 2020_06_16a.xml: Master Data document (VocabularyList, not EventList). Defines the attributes of some SGLN that are readPoints: site (SGLN of the site where the readPoint is located) and ssd (description)
• CBV_2_0 - 11_3 - 2020_06_16a.xml: Custom bizstep (quarantined) and disposition (contaminated): the doc is CBV-Compatible but not CBV-Compliant.
• CBV_2_0 - 11_2 - 2020_06_16a.xml: Custom identifiers using urn:example and http://: EPC, readPoint, businessLocation, business transactions
• CBV_2_0 - 11_1 - 2020_06_16a.xml: CBV-Compliant identifiers (eg urn:epc:id:gdti for transaction document)
• 2020_07_03y Transaction Event examples.xml:
  1. Hospital discharge summary (GDTI Document) of a patient (GSRN ServiceRecipient)
  2. Train passage (urn:gs1:epcisapp:rail:btt:passage) of 3 vehicles: first and last are identified (GIAI IndividualAsset) but the middle is not. Matches examples in "GS1 EPCIS for Rail Vehicle Visibility Application Standard". Source/destination use type urn:epcglobal:cbv:sdt:location (see CBV sec 7.4.2). Complications I don't fully understand:
     • MasterGIAI vs proxyGIAI
     • Differently written elements: rail:vehicle (with namespace) vs vehiclePosition (no namespace). But the result should be the same because xmlns:rail="urn:gs1:epcisapp:rail" xmlns="urn:gs1:epcisapp:rail".
     • source/destination are listed in envelope <extension> but the rail elements are not in extension? (I understand this now)
• 2020_06_28w persistent dispositions.xml: (THIS IS NEW) An aggregation (packing) event followed by desaggregation (unpacking), at which point a persistentDisposition is changed from urn:epcglobal:cbv:disp:completeness_inferred to urn:epcglobal:cbv:disp:completeness_verified (i.e. someone checked that nothing was missing from the packages).

JSON Examples

• Example_9.6.1-ObjectEvent-with-error-declaration.json
• Example_9.6.1-ObjectEventWithDigitalLink.jsonld
  • Uses eventID URIs like ni:///sha-256;9fa42e8bf64e1cfe152d582a248646ce0ad2b0c6826c7e8ed95442a7a1545f33?ver=CBV2.0. These are content-based (SHA of the content)

[RalphTro]

@CraigRe : did the group already agreed on how we are going to provide all these non-normative examples after ratification? I remember that we discussed several options (e.g. separate file residing on gs1.org, EPCIS GitHub). If we decide to continue GS1's GitHub issue repo, then @VladimirAlexiev 's suggestion makes sense. For that purpose, we e.g. could set up folders that contain all these examples in both formats (.jsonld + .xml) to which we can link to through a README file. As it is not an urgent matter, we e.g. can start working on this after we motioned the two drafts to public community review. Your thoughts?

[mgh128]

Agree that these should be linked from https://www.gs1.org/epcis after ratification, alongside the interface definitions and schema.

Useful to maintain a presence of EPCIS/CBV on GitHub even after ratification.
Need to synch the GitHub version with the official ratified artefacts at gs1.org/epcis but update the README file to point to the official artefacts at gs1.org/epcis

GitHub could serve as a place that additional work around examples and tools could continue while the officially approved content exists on the GS1 website. Could we display a warning when people post issues? "Any changes to the standard must go through the working group... etc..." GitHub also provides the option to disable the issue feature altogether What if people found issues in the examples or tools? To be discussed - many GitHub repos specify ‚HOW TO CONTRIBUTE‘

• we could point them to the GS1 WR system - what do you think? Ralph agrees, though that opening issues is far easier - but we need to discuss how they are moderated (e.g. by the Traceability and Event Sharing SMG, as the EPCIS MSWG will be disbanded soon)

GitHub can be a channel for issues but then they need to be moderated and curated towards the appropriate recipient Also there can be issues with the artefacts, schemas, swagger, etc. and GitHub is very convenient to report them Possible monthly SMG review of any issues posted after ratification.

[VladimirAlexiev]

@CraigRe

can start working on this after we motioned the two drafts to public community review.

Of course! ("two drafts" means EPCIS and CBV, right?)

https://github.com/VladimirAlexiev/EPCIS/blob/issue-231/JSON/WithSensorData/README.md is an example of the level of detail I think is useful (a couple of lines per example).