Migrating from GDST 1.2 to 2.0
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
- 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.
- Set the Accept header to application/linkset+json to ensure the linkset object is returned rather than a redirect.
- 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
No new KDEs were added to events in GDST 2.0. Buisness 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
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
- 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"
}
}