Migrating from 2.x to 3.0.0

This guide covers what changed between 2.x and 3.0.0, what you need to do before upgrading, and what you can adopt at your own pace after the upgrade.

Before you upgrade

1. Audit your registered link types

3.0.0 introduces strict validation of linkType values against namespace-specific vocabularies. Any registration request that uses an unrecognised link type will be rejected with a 404 error.

Before upgrading, review your registration scripts and payloads to ensure every linkType value uses a supported prefix and a key that exists within that vocabulary. See Link type validation below for the full list.

2. Review registration scripts that use itemDescription

The field itemDescription has been renamed to description. Both names are accepted in 3.0.0, but itemDescription is deprecated and will be removed in a future release. Now is a good time to update any scripts or tooling that still use itemDescription.

Breaking changes

Link type validation

Link types are now validated against a registered vocabulary for the prefix:key format. Previously, any string was accepted for linkType.

What changed:

• linkType must follow the prefix:key format (e.g. gs1:pip, untp:dpp).
• The prefix must be one of the supported vocabularies (gs1 or untp).
• The key after the colon must exist in that vocabulary.
• Invalid link types return a 404 error with a linkType field error.

Before (2.x — accepted without validation):

{
  "linkType": "myCustomType"
}

{
  "linkType": "gs1:unknownType"
}

After (3.0.0 — both examples above return 404):

{
  "linkType": "gs1:pip"
}

{
  "linkType": "untp:dpp"
}

Supported vocabularies

gs1 prefix — GS1 link type vocabulary:

Key	Title
activityIdeas	Activity Ideas
allergenInfo	Allergen information
appDownload	App download
backgroundInfo	Background Information
brandHomepageClinical	Information for professionals about this brand
brandHomepagePatient	Information for patients about this brand
careersInfo	Careers information
certificationInfo	Certification Information
consumerHandlingStorageInfo	Consumer handling and storage information
defaultLink	Default link
defaultLinkMulti	Default linkMulti
eifu	Electronic Instructions For Use
epcis	EPC Information Services (EPCIS) repository
epil	Electronic Patient Information Leaflet
eventsInfo	Events information
faqs	Frequently Asked Questions
handledBy	Handled by
hasRetailers	Has Retailers
homepage	Organisation Information Page
ingredientsInfo	Ingredients information
instructions	Instructions
jws	JSON Web Signature
leaveReview	Leave a review
locationInfo	Location information
logisticsInfo	Logistics information
loyaltyProgram	Loyalty program
masterData	Master data
menuInfo	Menu information
nutritionalInfo	Nutritional Information
openingHoursInfo	Opening hours information
paymentLink	Make Payment
pip	Product Information Page
productSustainabilityInfo	Sustainability and recycling (deprecated)
promotion	Promotion
purchaseSuppliesOrAccessories	Purchase supplies or accessories
quickStartGuide	Quick start guide
recallStatus	Recall status
recipeInfo	Recipe website
registerProduct	Register purchase
registryEntry	Entry in a register
relatedImage	Related image
relatedVideo	Related video
review	Reviews
safetyInfo	Safety information
scheduleTime	Scheduling/Reservation
serviceInfo	Service information
smartLabel	SmartLabel
smpc	Summary Product Characteristics (SmPC)
socialMedia	Social media
statisticInfo	Statistics
subscribe	Subscribe
support	Support
sustainabilityInfo	Sustainability and recycling
traceability	Traceability information
tutorial	Tutorial
userAgreement	Sign waiver/agreement/document
verificationService	Verification Service
whatsInTheBox	What's in the box?

untp prefix — UN Transparency Protocol vocabulary:

Key	Title
dpp	Digital Product Passport
dcc	Digital Conformity Credential
dte	Digital Traceability Event
idr	Identity Resolver
dfr	Digital Facility Record
dia	Digital Identity Anchor
cvc	Conformity Vocabulary Catalog

Error response

When a linkType fails validation, the API returns:

HTTP/1.1 404 Not Found

{
  "errors": [
    {
      "field": "linkType",
      "message": "..."
    }
  ]
}

There are two distinct error cases:

• Unknown prefix — the prefix before : is not gs1 or untp.
• Unknown key — the prefix is recognised but the key does not exist in its vocabulary.

New features

These features are all opt-in. Existing workflows continue to work without changes.

description field replaces itemDescription

The registration request field itemDescription has been renamed to description.

Both fields are accepted in 3.0.0. When both are present, description takes precedence. The itemDescription field is deprecated and will be removed in a future version.

Before (still works in 3.0.0, but deprecated):

{
  "namespace": "example-identifier-scheme",
  "identificationKeyType": "gtin",
  "identificationKey": "12345678901234",
  "itemDescription": "Organic green tea 250 g",
  "qualifierPath": "/",
  "active": true,
  "responses": []
}

After (preferred):

{
  "namespace": "example-identifier-scheme",
  "identificationKeyType": "gtin",
  "identificationKey": "12345678901234",
  "description": "Organic green tea 250 g",
  "qualifierPath": "/",
  "active": true,
  "responses": []
}

The value is stored and returned as description in the linkset context object regardless of which input field was used.

Application identifier ai field is now optional

When registering a namespace, the ai field on each ApplicationIdentifier object is now optional. If omitted, the resolver defaults it to the value of shortcode.

This simplifies identifier registration for non-GS1 schemes where GS1 application identifier numbers are not applicable.

Before (2.x — ai was required):

{
  "applicationIdentifiers": [
    {
      "title": "Product Serial Number",
      "label": "Serial",
      "shortcode": "serial",
      "ai": "serial",
      "type": "I",
      "regex": "[A-Za-z0-9]{1,20}"
    }
  ]
}

After (3.0.0 — ai can be omitted; defaults to shortcode):

{
  "applicationIdentifiers": [
    {
      "title": "Product Serial Number",
      "label": "Serial",
      "shortcode": "serial",
      "type": "I",
      "regex": "[A-Za-z0-9]{1,20}"
    }
  ]
}

For GS1 schemes, continue to provide ai explicitly (e.g. "ai": "01" for GTIN).

Checklist

Required before upgrade

• Audit all linkType values in existing registration scripts and payloads — any unrecognised prefix or key will be rejected after upgrade
• Pull the 3.0.0 container image

Recommended after upgrade

• Replace itemDescription with description in registration scripts and tooling
• Remove explicit ai fields from non-GS1 application identifier definitions where ai equals shortcode
• Monitor logs — improved error logging in the MinIO provider and global exception filter surfaces storage errors that were previously silent