Migrating from GDST 1.2 to 2.0

Updated 5 days ago by John Heggelund

The overall communication protocol and data format for GDST 2.0 is very similar to GDST 1.2, but there are a few important differences. This article outlines the key changes between GDST 1.2 and 2.0 with guidance on how to address them.

Digital Link Resolver

GDST 1.2 was based on the Digital Link Standard 1.1.2 which did not formalize the JSON shape of digital link responses. Resolvers in GDST 2.0 are based on the updated Resolver 1.2 standard, which establishes the RFC 9264 Linkset as the normative response from a digital link resolver.

Resolver Migration Guidance

1. When requesting links, always include the ?linkType=linkset parameter to ensure you get JSON response including the linkset. In the 1.2 standard, resolvers are expected to redirect directly to the requested resource if you include a linkType like gs1:masterData or gs1:epcis. While this redirect might be useful for masterdata, it is not particularly helpful for getting the epcis link.
2. Set the Accept header to application/linkset+json to ensure the linkset object is returned rather than a redirect.
3. Update your own resolver to return the correct linkset format.

Response Example

{
            "linkset": [
              {
                "anchor": "https://resolver.example.org/digitallink/01/urn:gdst:example.org:product:class:system.processedfish",
                "itemDescription": null,
                "https://ref.gs1.org/voc/defaultLink": [
                  {
                    "href": "https://resolver.example.org/masterdata/product/urn:gdst:example.org:product:class:system.processedfish",
                    "title": "Default Master Data"
                   }
                ],
                "https://ref.gs1.org/voc/masterData": [
                  {
                    "href": "https://resolver.example.org/masterdata/product/urn:gdst:example.org:product:class:system.processedfish",
                    "title": "Master Data"
                  }
                ],
                "https://ref.gs1.org/voc/epcis": [
                  {
                    "href": "https://resolver.example.org/epcis",
                    "title": "EPCIS Repository"
                  }
                ]
              }
            ]
          }

Events

1 new event, the decommission event, and 1 new KDE, unloading port on transshipment and landing events, were added in GDST 2.0. Business steps were normalized to the standard EPCIS values, some redundant KDEs were removed, product and location classifications were introduced, and locations can now provide either an address, geo coordinates, or a geo fence.

Event Migration Guidance

• Migrate business steps for the following event types
  • urn:gdst:bizstep:farmHarvest → urn:epcglobal:cbv:bizstep:commissioning
  • urn:gdst:bizstep:hatching → urn:epcglobal:cbv:bizstep:commissioning
  • urn:gdst:bizstep:fishingEvent → urn:epcglobal:cbv:bizstep:commissioning
  • urn:gdst:bizstep:transshipment → urn:epcglobal:cbv:bizstep:shipping or urn:epcglobal:cbv:bizstep:receiving
  • urn:gdst:bizstep:landing → urn:epcglobal:cbv:bizstep:receiving
• Break up transshipment events into a shipping and receiving event pair
• Add unloadingPort KDE to landing and transshipping events
• Add a decommission event example

Master Data

GDST 2.0 introduces product and location classifications. These are required to effectively profile events to determine what KDEs are required or expected for that event type. Additionally, the geo property was added to locations to support assigning coordinates or a geofence to a location.

See the Classifications article for more details.

Master Data Migration Guidance

• Ensure master data is not included in event query responses
  • As of EPCIS 2.0, master data is not allowed to be in the EPCIS Query Document header. The Capability Test will raise an error if master data is included in the header on an event query.
• Classifications
  • Add the vessel location classification to all vessels in your master data
  • Add the land facility classification to all land based facilities in your master data
  • Add the seafood product classification to all seafood products in your master data
  • Add the wildcaught product classification to all wildcaught products in your master data
  • Add the feed product classification to all feed products in your master data
  • Add the immature product classification to all the broodstock in your master data
  • Add the mature product classification to all the mature harvested products in your master data
  • Add the processed product classification to all the processed products in your master data
• Handle coordinates and geofences in your locations
  • Review the gs1:GeoCoordinates definition and make sure you can deserialize and serialize it if provided on the geo property of a location.
  • Review the gs1:GeoShape definition and make sure you can deserialize and serialize it if provided on the geo property.

Location with GeoCoordinates Example

{
              "@context": {
                  "cbvmda": "urn:epcglobal:cbvmda:mda",
                  "xsd": "http://www.w3.org/2001/XMLSchema#",
                  "gs1": "http://gs1.org/voc/",
                  "@vocab": "http://gs1.org/voc/",
                  "gdst": "https://traceability-dialogue.org/vocab"
              },
              "gdst:locationClassification": [
                  {
                      "type": "gdst",
                      "value": "land facility"
                  }
              ],
              "@type": "gs1:Place",
              "globalLocationNumber": "urn:gdst:example.org:location:loc:solution.feedmill",
              "cbvmda:owning_party": "urn:gdst:example.org:party:solution.feedmill",
              "cbvmda:informationProvider": "urn:gdst:example.org:party:solution.feedmill",
              "name": [
                  {
                      "@language": "en-US",
                      "@value": "Feed Mill"
                  }
              ],
              "geo": {
                  "@type": "gs1:GeoCoordinates",
                  "latitude": {
                      "@value": 37.7749,
                      "@type": "xsd:float"
                  },
                  "longitude": {
                      "@value": -122.4194,
                      "@type": "xsd:float"
                  }
              }
          }

Location with Geofence Example

{
              "@context": {
                  "cbvmda": "urn:epcglobal:cbvmda:mda",
                  "xsd": "http://www.w3.org/2001/XMLSchema#",
                  "gs1": "http://gs1.org/voc/",
                  "@vocab": "http://gs1.org/voc/",
                  "gdst": "https://traceability-dialogue.org/vocab"
              },
              "gdst:locationClassification": [
                  {
                      "type": "gdst",
                      "value": "land facility"
                  }
              ],
              "@type": "gs1:Place",
              "globalLocationNumber": "urn:gdst:example.org:location:loc:solution.fishfarm",
              "cbvmda:owning_party": "urn:gdst:example.org:party:solution.fishfarm",
              "cbvmda:informationProvider": "urn:gdst:example.org:party:solution.fishfarm",
              "name": [
                  {
                      "@language": "en-US",
                      "@value": "Fish Farm"
                  }
              ],
              "geo": {
                  "@type": "gs1:GeoShape",
                  "polygon": "37.7749 -122.4194 37.7749 -122.418 37.776 -122.418 37.776 -122.4194 37.7749 -122.4194"
              }
          }

Query Parameters

The LE_eventTime and LE_recordTime query parameters are deprecated in GDST 2.0. They are replaced by the LT_eventTime and LT_recordTime parameters respectively to better align with the EPCIS standard. Additionally, the Capability Test now checks that all query parameters required by the GDST standard are implemented and functioning correctly.

Query Parameter Migration Guidance

• Replace LE_eventTime support with LT_eventTime
• Replace LE_recordTime support with LT_recordTime
• Ensure the EQ_bizStep query parameter is supported.
  • Standard business step values should be expressed as bare words, e.g. `shipping`, whereas custom values should be expressed as URIs or CURIEs for which the namespace prefix is defined.
• Ensure the EQ_transformationID query parameter is supported
• Ensure the EQ_bizLocation query parameter is supported

How did we do?