Description of endpoints ending with path ".../{eventID}" requires change

[shalikasingh]

Hi @RalphTro, @mgh128,

The description for endpoints listed below needs a slight change in openapi.yaml and 2021_01_26y EPCIS 2-0 COMMREV as well.

• GET /eventTypes/{eventType}/events/{eventID}
• GET /epcs/{epc}/events/{eventID}
• GET /bizSteps/{bizStep}/events/{eventID}
• GET /readPoints/{readPoint}/events/{eventID}
• GET /bizLocations/{bizLocation}/events/{eventID}
• GET /dispositions/{disposition}/events/{eventID}

Description as-is: "Returns an individual EPCIS event." Description to-be: "Return EPCIS event(s) related to given [eventType] and eventID."

Note: Word within the square bracket will change as per endpoint.

Reason: Below have quoted from 2021_01_26y EPCIS 2-0 COMMREV from section 7.4.1.2 Error Declaration

" The prior event is not modified in any way, and subsequent queries will return both the prior event and the error declaration. "

The above line is self-explanatory that why the description of listed endpoints requires change. The erroneous event and error declaration event are going to share the same eventID and queries need to return both without any discrimination.

Let us know if we are missing any points here.

[mgh128]

Hi @shalikasingh

Another good catch! So the point you're making here is that the original event and any subsequent event expressing an ErrorDeclaration for the original event (and quoting the same eventID) will both be returned by such an endpoint.

Tagging @joelvogt and @CraigRe so that they can make the change in openapi.yaml and 2021_01_26y EPCIS 2-0 COMMREV

Thanks!

Mark

[CraigRe]

@shalikasingh regarding the EPCIS doc (not the openapi.yaml), do you mean only within table 12-5, or other passages, too?

[shalikasingh]

Hi @CraigRe ,

In EPCIS doc version 2021_01_26y EPCIS 2-0 COMMREV under section 12.7 Events interface , we can see Table 5 and Table 6 requires change.

[CraigRe]

Will review changes to tables 12-6 and 1-6 during 9 February WG telco.

[CraigRe]

Openapi still needs to reflect this change.

[CraigRe]

Added passage: Query endpoints ending with /events/{eventID} may return more than one event if the eventID is present in subsequent events that include an ErrorDeclaration to indicate that the original event was in error.

[domguinard]

In the openapi we should:

• Change the text as we changed it in the standard document
• Change the examples to ensure we have more than 1 event returned

[joelvogt]

@mgh128 or @dakbhavesh or @shalikasingh could you please provide a complete JSON example of an event and errors so that I can use in the openapi spec? Thank you!

[shalikasingh]

Hi @joelvogt ,

Please find below the requested example for EPCIS document that contains erroneous and error declaration events with the same eventID.

{
   "@context":[
      "https://gs1.github.io/EPCIS/epcis-context.jsonld",
      {
         "example":"http://ns.example.com/epcis/"
      }
   ],
   "id":"_:document1",
   "isA":"EPCISDocument",
   "creationDate":"2020-01-15T07:47:21.677+00:00",
   "schemaVersion":1.2,
   "format":"application/ld+json",
   "epcisBody":{
      "eventList":[
         {
            "isA":"TransformationEvent",
            "eventTime":"2020-01-14T00:00:00+01:00",
            "eventTimeZoneOffset":"+01:00",
            "eventID":"urn:uuid:374d95fc-9457-4a51-bd6a-0bba133845a8",
            "inputEPCList":[
               "urn:epc:id:sgtin:4012345.011111.987"
            ],
            "outputEPCList":[
               "urn:epc:id:sgtin:4012345.033333.AGHFG"
            ],
            "inputQuantityList":[
               {
                  "epcClass":"urn:epc:class:lgtin:4012345.022222.87545GHGH",
                  "quantity":500,
                  "uom":"KGM"
               }
            ],
            "outputQuantityList":[
               {
                  "epcClass":"urn:epc:idpat:sgtin:4012345.044444.*",
                  "quantity":452,
                  "uom":"KGM"
               }
            ],
            "bizStep":"urn:epcglobal:cbv:bizstep:commissioning",
            "readPoint":{
               "id":"urn:epc:id:sgln:0614141.07346.1234"
            },
            "errorDeclaration":{
               "declarationTime":"2020-01-15T00:00:00+01:00",
               "reason":"urn:epcglobal:cbv:er:incorrect_data",
               "example:vendorExtension":"Test1",
               "correctiveEventIDs":[
                  "urn:uuid:404d95fc-9457-4a51-bd6a-0bba133845a8"
               ]
            }
         },
         {
            "isA":"TransformationEvent",
            "eventTime":"2020-01-14T00:00:00+01:00",
            "eventTimeZoneOffset":"+01:00",
            "eventID":"urn:uuid:374d95fc-9457-4a51-bd6a-0bba133845a8",
            "inputEPCList":[
               "urn:epc:id:sgtin:4012345.011111.987"
            ],
            "outputEPCList":[
               "urn:epc:id:sgtin:4012345.033333.AGHFG"
            ],
            "inputQuantityList":[
               {
                  "epcClass":"urn:epc:class:lgtin:4012345.022222.87545GHGH",
                  "quantity":500,
                  "uom":"KGM"
               }
            ],
            "outputQuantityList":[
               {
                  "epcClass":"urn:epc:idpat:sgtin:4012345.044444.*",
                  "quantity":452,
                  "uom":"KGM"
               }
            ],
            "bizStep":"urn:epcglobal:cbv:bizstep:commissioning",
            "readPoint":{
               "id":"urn:epc:id:sgln:0614141.07346.1234"
            }
         }
      ]
   }
}

[joelvogt]

Thank you @shalikasingh! I'll include your example in the openapi spec