GS1 Digital Link URI Structure: A Technical Deep Dive

This is the spec reference for developers and technical teams implementing or integrating with GS1 Digital Link resolvers. If you're looking for a general overview, start with What Is a QR Code Resolver? instead.

URI anatomy

A GS1 Digital Link URI has four parts:

Application Identifiers in the path

GS1 Application Identifiers (AIs) structure the path segments. Each AI is a numeric code that defines the type and format of the data that follows it.

Primary identification keys

The first path segment after the domain must be a primary key AI. The most common is GTIN, but others are supported:

For most product-focused implementations, you'll only use AI 01 (GTIN).

Key qualifiers

Key qualifiers narrow the identification scope. They follow the primary key in the path:

Multiple qualifiers can be chained after the primary key:

/01/09506000134376/10/BATCH123/21/SERIAL456

GTIN formatting rules

GTINs in Digital Link URIs are always 14 digits, zero-padded on the left:

Resolvers must accept GTINs at any valid length (8, 12, 13, or 14) and normalize to 14 digits for lookup. The check digit must be valid. SunriseQR handles this automatically when you enter a GTIN -- padding and validation happen before the URI is generated.

Query parameters

Query parameters modify the resolver's behavior. The main parameter defined by the standard:

linkType

Requests a specific link type from the resolver:

https://id.example.com/01/09506000134376?linkType=gs1:pip

If omitted, the resolver returns the default link. If the requested link type doesn't exist for the product, the resolver returns the default link or a 404.

linkType=all

A special value that requests the complete linkset for the product:

https://id.example.com/01/09506000134376?linkType=all

The resolver returns a JSON document listing all available links for the product, their types, titles, and URLs. This is how supply chain systems discover what data is available.

context

An optional parameter defined in the spec for disambiguating between multiple links of the same type in specialized scenarios. Most consumer-facing implementations don't use this parameter.

Content negotiation

A conformant resolver supports HTTP content negotiation via the Accept header. The same URI can return different responses depending on what the client accepts:

This is what makes one code serve multiple audiences: a consumer's browser sends text/html and gets redirected to a product page. A supply chain system sends application/linkset+json and gets structured data. SunriseQR's resolver handles this negotiation automatically for every product you add.

Resolver response: linkset JSON

When a client requests application/linkset+json, the resolver returns a document structured like:

{
  "linkset": [
    {
      "anchor": "https://id.example.com/01/09506000134376",
      "https://gs1.org/voc/pip": [
        {
          "href": "https://brand.com/products/olive-oil",
          "title": "Product Information Page",
          "type": "text/html",
          "hreflang": ["en"]
        }
      ],
      "https://gs1.org/voc/hasRetailers": [
        {
          "href": "https://brand.com/where-to-buy",
          "title": "Where to Buy",
          "type": "text/html",
          "hreflang": ["en"]
        }
      ],
      "https://gs1.org/voc/traceability": [
        {
          "href": "https://brand.com/trace/LOT2026A",
          "title": "Traceability Information",
          "type": "application/json"
        }
      ]
    }
  ]
}

Each link type uses its full GS1 vocabulary URI as the key. Each entry includes href, title (required by GS1), content type, and optional hreflang for language targeting.

Conformance requirements

The GS1-Conformant Resolver Standard defines a set of individual requirements using RFC 2119 keywords:

• SHALL (mandatory): HTTPS, 307 redirects, linkType support, linkset JSON responses, resolver description file at /.well-known/gs1resolver
• SHOULD (recommended): JSON-LD linkset format, language-based link selection
• MAY (optional): HTML linkset format, context parameter support, URI compression

There are no numbered "levels" -- a resolver either meets the mandatory requirements or it doesn't. The official test suite validates conformance against these requirements.

SunriseQR's resolver is fully conformant and validated against the official test suite.

URI compression

GS1 Digital Link URIs can be long, which increases QR code density (more modules = harder to scan at small sizes). The standard defines a compressed URI format that encodes the same AI data using URI-safe base64, reducing the path length significantly. This matters when printing at small sizes.

Compression is optional in the spec. For most product QR codes (GTIN only), the standard URI is short enough that compression isn't necessary, and uncompressed URIs are easier to read and debug.

Implementation notes

Redirects must use 307, not 301 or 302

GS1 specifies HTTP 307 (Temporary Redirect) for resolver redirects. This preserves the HTTP method and body across the redirect, which matters for machine clients. Using 301 (Permanent) would tell clients to cache the redirect and skip the resolver in the future, defeating the purpose of dynamic resolution.

HTTPS is mandatory

GS1 Digital Link URIs must use HTTPS. HTTP URIs are not valid GS1 Digital Links.

Trailing slashes

The standard treats /01/09506000134376 and /01/09506000134376/ as equivalent. Resolvers should handle both.

URL encoding in qualifiers

Batch/lot numbers and serial numbers may contain characters that need URL encoding (spaces, special characters). Use standard percent-encoding: LOT 123 becomes LOT%20123.

CORS headers

If your resolver serves linkset JSON to browser-based clients, include appropriate CORS headers (Access-Control-Allow-Origin) to enable cross-origin requests from web applications.

Getting all of these details right -- and keeping them right as the standard evolves -- is a meaningful amount of ongoing work. SunriseQR handles this so you don't have to track spec changes yourself.

Further reading

• GS1 Digital Link Standard (official specification)
• GS1-Conformant Resolver Standard -- the full technical spec for resolver implementations
• GS1 Resolver Test Suite -- the official test suite for validating resolver conformance
• GS1 Web Vocabulary (link type definitions)
• What Is a GTIN? for the basics of product identification
• GS1 Link Types Explained for a practical guide to link types
• What Is a QR Code Resolver? for a non-technical overview

Building a resolver or integrating with one? SunriseQR handles the resolver infrastructure so you can focus on your product data. Learn more →