Digital Link Resolution¶
GS1 Digital Link transforms traditional product identifiers into web-native URIs. When a consumer scans a QR code on a product, GTIN1 resolves the embedded Digital Link URI to deliver the right content -- whether that is a product information page, machine-readable data, or a redirect to a brand's own website.
URI Structure¶
Every GS1 Digital Link URI follows a consistent pattern:
The primary key Application Identifier (AI) identifies the type of GS1 key, and the value is the key itself. Additional AIs can be appended as path segments to provide more context:
For example:
https://gtin1.com/01/00785034739064
https://gtin1.com/01/00785034739064/10/LOT2024A
https://gtin1.com/01/00785034739064/10/LOT2024A/21/SN00001
https://gtin1.com/01/00785034739064/17/261231/10/BATCH99
Supported Primary Key AIs¶
GTIN1 recognizes URIs for all standard GS1 primary key Application Identifiers. The GTIN (AI 01) resolver is fully implemented with product lookup, content negotiation, and rule-based resolution. Other primary keys return a descriptive message indicating they are not yet resolved.
| AI | Name | Example URI |
|---|---|---|
| 01 | Global Trade Item Number (GTIN) | https://gtin1.com/01/00785034739064 |
| 00 | Serial Shipping Container Code (SSCC) | https://gtin1.com/00/340123450000000014 |
| 253 | Global Document Type Identifier (GDTI) | https://gtin1.com/253/4012345000010 |
| 255 | Global Coupon Number (GCN) | https://gtin1.com/255/4012345000100 |
| 401 | Global Identification Number for Consignment (GINC) | https://gtin1.com/401/4012345AB |
| 402 | Global Shipment Identification Number (GSIN) | https://gtin1.com/402/40123450000000001 |
| 414 | Global Location Number -- Physical Location | https://gtin1.com/414/4012345000015 |
| 415 | Global Location Number -- Invoicing Party | https://gtin1.com/415/4012345000015 |
| 417 | Party Global Location Number | https://gtin1.com/417/4012345000015 |
| 8003 | Global Returnable Asset Identifier (GRAI) | https://gtin1.com/8003/04012345000010 |
| 8004 | Global Individual Asset Identifier (GIAI) | https://gtin1.com/8004/4012345ABC |
| 8006 | Individual Trade Item Piece (ITIP) | https://gtin1.com/8006/040123451234560102 |
| 8010 | Component/Part Identifier (CPID) | https://gtin1.com/8010/4012345ABC |
| 8013 | Global Model Number (GMN) | https://gtin1.com/8013/4012345ABC |
| 8017 | Global Service Relation Number (GSRN) -- Provider | https://gtin1.com/8017/4012345000000014 |
| 8018 | Global Service Relation Number (GSRN) -- Recipient | https://gtin1.com/8018/4012345000000014 |
Note
Only GTIN (AI 01) is fully resolved today. Scanning a URI with any other primary key AI returns a 404 response with a message identifying the key type (e.g., "The Serial Shipping Container Code (SSCC) (00) AI is not supported."). Support for additional primary keys is planned.
Content Negotiation¶
GTIN1 uses the HTTP Accept header to determine which representation to return. This means the same URI can serve different consumers -- a web browser sees a product page, while an API client receives structured data.
| Accept Header | Response Type | Description |
|---|---|---|
text/html |
HTML redirect | Redirects to the product information page (or a custom URL if configured) |
application/linkset+json |
GS1 Linkset | A JSON document listing all available links for the product, per IETF RFC 9264 |
application/ld+json |
JSON-LD | Structured data using GS1 and schema.org vocabulary |
application/json |
JSON | Machine-readable product data with brand info and traceability metadata |
HTML Response¶
When a browser or consumer scans a QR code, the resolver returns an HTTP redirect to the product's information page:
The redirect response includes HTTP Link headers for machine discoverability:
HTTP/1.1 307 Temporary Redirect
Location: /catalog/ti/abc123xyz/
Link: <https://gtin1.com/01/00785034739064?linkType=linkset>; rel="linkset"; type="application/linkset+json"
Content-Language: en
Linkset Response¶
The linkset representation provides a structured directory of all available links for a product:
{
"linkset": [
{
"anchor": "https://gtin1.com/01/00785034739064",
"https://gs1.org/voc/pip": [
{
"href": "https://gtin1.com/catalog/ti/abc123xyz/",
"title": "Organic Olive Oil 500ml"
}
],
"describedby": [
{
"href": "https://gtin1.com/catalog/ti/abc123xyz/jsonld/",
"type": "application/ld+json",
"title": "JSON-LD Structured Data"
}
],
"https://gs1.org/voc/certificationInfo": [
{
"href": "https://gtin1.com/catalog/ti/abc123xyz/#certifications",
"title": "Certifications"
}
]
}
]
}
Available link relations depend on the product's data. GS1 link types are represented as full URLs (e.g., https://gs1.org/voc/pip), while IANA relation types use short names (e.g., describedby). A product with certifications will include https://gs1.org/voc/certificationInfo; a product under recall will include https://gs1.org/voc/recallStatus; a food product subject to FSMA 204 will include https://gs1.org/voc/traceability.
JSON-LD Response¶
The JSON-LD representation uses GS1 and schema.org vocabulary for semantic web interoperability:
{
"@context": ["https://schema.org/", "https://gs1.org/voc/"],
"@type": "Product",
"@id": "https://gtin1.com/01/00785034739064",
"gtin": "00785034739064",
"gtin14": "00785034739064",
"name": "Organic Olive Oil 500ml",
"description": "Cold-pressed extra virgin olive oil from Andalusia.",
"brand": {
"@type": "Brand",
"name": "Mediterranean Harvest",
"url": "https://medharvest.example.com"
},
"inLanguage": "en"
}
JSON Response¶
The plain JSON representation provides product data and resolved Application Identifiers:
{
"@context": "https://gs1.org/voc/",
"type": "Product",
"gtin": "00785034739064",
"name": "Organic Olive Oil 500ml",
"anchor": "https://gtin1.com/01/00785034739064",
"applicationIdentifiers": {
"10": "LOT2024A"
},
"brand": {
"name": "Mediterranean Harvest",
"url": "https://medharvest.example.com"
},
"links": {
"pip": "https://gtin1.com/catalog/ti/abc123xyz/",
"jsonld": "https://gtin1.com/catalog/ti/abc123xyz/jsonld/"
}
}
Additional Application Identifiers¶
When resolving a GTIN URI, GTIN1 parses qualifier AIs from the path. These provide additional context about the specific instance of the product being scanned. See Application Identifiers for the complete reference.
Common combinations:
/01/{gtin}/10/{lot} -- Product with batch/lot number
/01/{gtin}/21/{serial} -- Product with serial number
/01/{gtin}/10/{lot}/21/{serial} -- Specific serialized item in a lot
/01/{gtin}/17/{expiry} -- Product with expiration date
/01/{gtin}/17/{expiry}/10/{lot} -- Lot with expiration date
QR Code Generation¶
Any Digital Link URI can be rendered as a QR code by adding the fmt query parameter or the qr flag:
| Parameter | Format | Content Type |
|---|---|---|
?fmt=svg |
Scalable Vector Graphics | image/svg+xml |
?fmt=pdf |
PDF document | application/pdf |
?fmt=eps |
Encapsulated PostScript | application/postscript |
?qr |
SVG (default) | image/svg+xml |
Example:
The generated QR code encodes the canonical Digital Link URI with an uppercase scheme and host, as recommended by the GS1 Digital Link standard for optimal QR code encoding efficiency.
Warning
PNG format is no longer supported. Use fmt=svg, fmt=pdf, or fmt=eps instead.
Link Type Requests¶
Use the linkType query parameter to request a redirect to a specific type of linked resource:
https://gtin1.com/01/00785034739064?linkType=gs1:pip
https://gtin1.com/01/00785034739064?linkType=gs1:recallStatus
https://gtin1.com/01/00785034739064?linkType=gs1:certificationInfo
If the requested link type is available for the product, the resolver returns a 303 See Other redirect to the target URL. If the link type is not available, a 404 response is returned.
Supported link types:
| Link Type | Description |
|---|---|
gs1:pip |
Product Information Page |
gs1:recallStatus |
Recall status and details |
gs1:instructions |
Usage instructions |
gs1:brandHomepageClinical |
Brand homepage (clinical context) |
gs1:certificationInfo |
Certifications |
gs1:traceability |
FSMA 204 traceability data |
gs1:promotion |
Promotional information |
gs1:masterData |
Master data (JSON-LD) |
gs1:allergenInfo |
Allergen information |
gs1:productSustainabilityInfo |
Sustainability information |
Use ?linkType=linkset to explicitly request the linkset representation regardless of the Accept header.
Language Selection¶
GTIN1 determines the content language using this precedence:
?lang=query parameter -- explicit language choice in the URIAccept-Languageheader -- browser or client preference- Trade item default -- the product's configured primary language
- Site default -- English (
en)
Supported languages: en, es, fr, de, zh, ja, ko.
The response includes a Content-Language header indicating the selected language.
CORS Support¶
All resolver responses include CORS headers to allow cross-origin access from any domain:
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Headers: Accept, Accept-Language
Access-Control-Max-Age: 86400
This enables client-side JavaScript applications to fetch product data directly from GTIN1 Digital Link URIs.
HTTP Methods¶
The resolver supports three HTTP methods, per GS1 conformance requirements:
| Method | Behavior |
|---|---|
GET |
Full resolution with content negotiation |
HEAD |
Same as GET but without response body |
OPTIONS |
CORS preflight response |
Caching¶
Responses include Cache-Control headers appropriate for the content type:
| Content | Cache Duration |
|---|---|
| Linkset / JSON / JSON-LD | 1 hour |
| HTML redirects | 5 minutes |
| Error responses | 1 minute |
All responses include Vary: Accept, Accept-Language to ensure caches serve the correct representation.
GTIN Validation¶
GTIN1 validates incoming GTINs against the GS1 specification:
- Must be 8, 12, 13, or 14 digits
- Must contain only numeric characters
- Must have a valid GS1 check digit
Invalid GTINs return a 400 Bad Request response with a descriptive error message. For JSON clients, the error is returned as structured JSON; for browser clients, a user-friendly error page is displayed.