OpenAPI Specification
The GDST standard defines what data to capture and how partners exchange it. This article introduces the machine-readable counterpart: an OpenAPI 3.1 definition of the HTTP interface a GDST 2.0 solution must expose.
Use it to generate client code, drive a mock server, or check an implementation against the standard without reading through prose.
What it covers
GDST requires a defined subset of the EPCIS 2.0 REST binding, not all of it. The definition describes only that subset, so everything in it is mandatory for a conforming solution:
GET /events: the EPCIS query interface, with the nine required query parameters. This is the only EPCIS method GDST requires.- The GS1 Digital Link Resolver:
/417/{pgln},/414/{gln},/01/{gtin},/00/{sscc},/01/{gtin}/10/{lot}and/01/{gtin}/21/{serial}, serving thegs1:epcisandgs1:masterDatalink types. X-API-Key: the authentication header both parties must support.- Master data: the payload shape for gs1:Organization, gs1:Place and gs1:Product.
The core events
The seven core events are plain EPCIS with CBC business steps. Their immutable signatures are declared in the x-gdst-core-events block:
Event |
|
|
|
|
Commission | ObjectEvent | ADD |
|
|
Decommission | ObjectEvent | DELETE |
| not fixed |
Aggregation | AggregationEvent | ADD |
|
|
Disaggregation | AggregationEvent | DELETE |
|
|
Shipping | ObjectEvent | OBSERVE |
|
|
Receiving | ObjectEvent | OBSERVE |
| not fixed |
Transformation | TransformationEvent | - |
|
|
commissioning; type tells them apart. Transformation has no action field in EPCIS.Reading the vendor extensions
Four x- fields carry information OpenAPI has no native place for:
x-gdst-core-events: the table above, machine-readable.x-kde-name: on each master data property, the CBV attribute name, so the definition can be read against the KDE tables in the other articles. JSON-LD useslocationClassification; the KDE tables call itname. Both are correct, for different derealization's.x-gdst-values: the permitted value forproductClassificationandlocationClassification. These are not declared as an enum because both lists are extensible through the GDST governance process.x-style/x-explode: see below.
Notes for implementers
Multi-valued filters are pipe-delimited, with the pipe URL-encoded: EQ_bizStep=shipping%7Creceiving. Repeating the key is not equivalent. The GS1 binding declares this as style: pipeDelimited, explode: false; it is carried hare as x-style and x-explode because some validators do not yet accept style on an OpenAPI 3.1 query parameter. If you generate a client, check that it emits one pipe-joined parameter and not repeated keys.
Business steps have three equivalent forms. shipping, urn:epcglobal:cbv:bizstep:shipping and https://ref.gs1.org/cbv/BizStep-shipping denote the same value, and a server must treat them as equal.
The response schema is referenced from GS1. The core events are plain EPCIS, so the definition points at the published EPCIS 2.0 JSON schema rather than restarting it. The document resolves on its own, but needs network access to do so.
Modules
Commodity-specific requirements (the Seafood, Aquaculture and Wild Catch modules) are out of scope here. A module constrains what a payload must contain; it adds no endpoint, no parameter and no header. Those requirements are enforced by JSON Schema and documented in the Modules articles.
