GS1 Digital Link Resolver¶

The resolver is the core engine of the GTIN1 platform. It parses GS1 Digital Link URIs, extracts Application Identifiers, and routes every scan to the right destination based on context, device, and content type.

How the Resolver Works¶

When a consumer scans a GS1 Digital Link QR code or clicks a Digital Link URI, the GTIN1 resolver processes the request through a multi-step pipeline that determines the correct response. This pipeline ensures every scan is resolved accurately, whether the request comes from a smartphone camera app, a point-of-sale terminal, or an automated supply-chain system.

1. URI Parsing¶

The resolver receives the incoming URI and breaks it into path segments. Each segment pair is matched against the GS1 Application Identifier registry to extract structured data such as GTIN, batch/lot number, serial number, and expiry date.

2. AI Extraction¶

Once the URI is parsed, the resolver identifies the primary key (typically a GTIN) and any qualifier AIs such as lot, serial, or expiry. These qualifiers narrow the resolution scope from a general product page to a specific batch or individual item.

3. Destination Lookup¶

The resolver queries the link registry for matching destinations. Each trade item can have multiple link entries that map to different target URLs based on link type, language, geographic region, and device context. The most specific match is selected.

4. Content Negotiation¶

Based on the HTTP Accept header, the resolver returns the response in the appropriate format: an HTML redirect for browsers, a JSON object for API consumers, or a linkset document for machine-readable resolution conforming to RFC 9264.

Supported Application Identifiers¶

GS1 Application Identifiers (AIs) are standardized numeric prefixes that define the meaning of the data that follows. The GTIN1 resolver supports all primary identification AIs used in GS1 Digital Link URIs.

AI	Name	Role	Example
`01`	GTIN	Primary Key	`/01/00012345678906`
`10`	Batch/Lot Number	Qualifier	`/01/00012345678906/10/LOT2025A`
`21`	Serial Number	Qualifier	`/01/00012345678906/21/SN001`
`17`	Expiration Date	Qualifier	`/01/00012345678906/17/261231`
`00`	SSCC	Primary Key	`/00/340123450000000017`
`414`	GLN (Location)	Primary Key	`/414/0614141000005`
`8003`	GRAI (Returnable Asset)	Primary Key	`/8003/00614141000005XYZ`
`8004`	GIAI (Individual Asset)	Primary Key	`/8004/0614141ABC123`

The resolver also supports GDTI (253), GCN (255), GINC (401), GSIN (402), ITIP (8006), CPID (8010), GMN (8013), and GSRN (8018) for specialized use cases such as document identification, coupons, consignments, and service relations.

Content Negotiation¶

A single GS1 Digital Link URI can return different response formats depending on the HTTP Accept header sent by the client.

`text/html`¶

The default for browsers. The resolver redirects the user to the most appropriate destination URL with an HTTP 307 redirect. This is the response consumers receive when scanning a QR code with their smartphone camera.

`application/json`¶

Returns structured product data as a JSON object. Useful for mobile apps, point-of-sale integrations, and custom applications that need to consume product information programmatically.

`application/linkset+json`¶

Returns an RFC 9264 linkset document listing all available link relations for the identified item. This machine-readable format enables automated discovery of all destinations associated with a product.

`application/ld+json`¶

Returns product data structured with the GS1 Web Vocabulary as JSON-LD. This format is ideal for search engines and semantic web applications that consume structured data using Schema.org and GS1 vocabularies.

Example: Requesting a Linkset

curl -H "Accept: application/linkset+json" \
  https://gtin1.com/01/00012345678906

Policy-Driven Routing¶

The resolver does not simply redirect every scan to a single URL. Instead, it evaluates a set of policies to determine the best destination for each request. This allows brand owners to serve different experiences to different audiences from a single QR code.

Link Type¶

Route by GS1 link type: product info page, instructions, recipe, safety data, recall notice, or certification.

Locale¶

Route by the Accept-Language header or explicit language parameter to serve content in the scanner's preferred language.

Device Class¶

Route by device type so mobile users see a mobile-optimized experience while desktop users see a full product page.

Campaign Context¶

Route to campaign-specific landing pages using query parameters, enabling time-limited promotions tied to product packaging.

Fallback Handling

When no policy matches the request context, the resolver falls back through a priority chain: first to the default link for the requested link type, then to the product information page (gs1:pip), and finally to the GTIN1-hosted product page. This guarantees every scan reaches a meaningful destination.

URI Structure¶

GS1 Digital Link URIs follow a hierarchical path structure where the domain is followed by Application Identifier and value pairs.

Basic GTIN Resolution¶

https://gtin1.com/01/{gtin}

Example:
https://gtin1.com/01/00012345678906

GTIN with Batch/Lot¶

https://gtin1.com/01/{gtin}/10/{lot}

Example:
https://gtin1.com/01/00012345678906/10/LOT2025A

GTIN with Serial Number¶

https://gtin1.com/01/{gtin}/21/{serial}

Example:
https://gtin1.com/01/00012345678906/21/SN-40928

Full Qualification with Expiry¶

https://gtin1.com/01/{gtin}/10/{lot}/17/{expiry}

Example:
https://gtin1.com/01/00012345678906/10/LOT2025A/17/261231

Query Parameters¶

Parameter	Purpose	Example
`linkType`	Request a specific GS1 link type (e.g. product information, recipe or instructions)	`?linkType=gs1:pip`, `?linkType=gs1:recipeInfo`
`context`	Specify geographic or market context	`?context=us`
`fmt`	Request a barcode image instead of resolution	`?fmt=svg`
`qr`	Request a QR code image for the Digital Link	`?qr`

GS1 Conformance¶

GTIN1 implements the GS1 Digital Link standard and follows the conformance requirements defined by GS1 for resolver services.

Conformance File¶

GTIN1 publishes a conformance file at the well-known URI path that declares the resolver's capabilities, supported AIs, and conformance level.

https://gtin1.com/.well-known/gs1resolver

RFC 9264 Linkset¶

All linkset responses conform to RFC 9264, the IETF standard for representing web links as JSON objects. This enables automated systems to discover and traverse all available links for a given identifier.

Standards Compliance Summary¶

GS1 Digital Link URI syntax (GS1 Digital Link Standard 1.3)
GS1 Digital Link resolver conformance requirements
RFC 9264 linkset media type for machine-readable link discovery
GS1 Web Vocabulary for structured product data in JSON-LD
HTTP content negotiation via Accept header (RFC 7231)
FSMA 204 traceability support through lot and serial qualifiers

Frequently Asked Questions¶

What is a GS1 Digital Link resolver?

A GS1 Digital Link resolver is a web service that interprets GS1 Digital Link URIs and routes requests to the appropriate destination. When a consumer scans a QR code containing a GS1 Digital Link, the resolver parses the Application Identifiers in the URI, looks up the registered destinations for that product, and returns the correct response based on the request context. It acts as the bridge between a standardized product identifier and the brand's digital content.

Which GS1 Application Identifiers does GTIN1 support?

GTIN1 supports all primary GS1 identification keys used in Digital Link URIs. This includes GTIN (01), Batch/Lot (10), Serial Number (21), Expiration Date (17), SSCC (00), GLN (414), GRAI (8003), and GIAI (8004) as core identifiers. Additionally, the resolver handles GDTI, GCN, GINC, GSIN, ITIP, CPID, GMN, and GSRN for specialized use cases.

How does content negotiation work?

Content negotiation allows the same GS1 Digital Link URI to return different response formats depending on the client's needs. When a browser requests text/html, the resolver issues an HTTP redirect. When an API client requests application/json, it returns structured product data. Requesting application/linkset+json returns an RFC 9264 linkset document. The client specifies its preference via the standard HTTP Accept header.

Can I customize where the resolver redirects?

Yes. Brand owners can configure multiple destination URLs for each trade item and assign them to different link types such as product information, recipes, safety data sheets, or promotional pages. The resolver selects the correct destination based on the linkType query parameter, the user's language, device type, and geographic context. You can update destinations at any time without reprinting QR codes.

Is GTIN1 GS1-conformant?

GTIN1 implements the GS1 Digital Link standard and publishes a conformance file at /.well-known/gs1resolver that declares the resolver's capabilities. The resolver supports the required content negotiation behaviors, returns RFC 9264 linkset responses, validates GTIN check digits, and correctly handles all mandatory Application Identifiers defined in the GS1 Digital Link specification.