Skip to main content

How to Verify a GS1-Conformant Resolver

By Diljit Ramachandran · LinkedIn · /about

Published · Last updated · 2 min read

A developer checking code behaviour on screen.

A GS1-conformant resolver is a service that resolves GS1 Digital Link URIs and can be discovered by clients under the GS1-Conformant Resolver standard. You do not have to take “we put a GTIN in the URL” at face value: four requests show whether a resolver conforms.

The examples use QRCodeStack’s live description file at https://qrcodestack.com/.well-known/gs1resolver. They pair with our GS1 Digital Link tool and the comparison of Digital Link vs a normal QR code.

What does conformant mean?

The standard expects more than an HTTPS redirect that contains digits:

  • A Resolver Description File at /.well-known/gs1resolver, so a client can discover the service.
  • Resolution of Digital Link URIs such as /01/{gtin}, with optional path prefixes permitted by URI Syntax §4.11.
  • Support for linkType selection, a full linkset (a machine-readable list of all links for the item), and correct handling of unknown types.
  • Linksets through content negotiation, for example application/linkset+json per RFC 9264. HTTP Link headers are optional in the current release; QRCodeStack’s resolver sends them.

A stack that only 302s shoppers to a campaign page fails the discovery test even when the QR looks professional.

Does the description file exist?

Request GET https://qrcodestack.com/.well-known/gs1resolver in a browser or with curl. The Resolver Description File is a JSON (or JSON-LD) document that describes the resolver and how clients reach it. If the file is missing, clients should not treat the origin as a conformant resolver.

Custom domains: when packaging prints https://brand.com/01/{gtin}, checkers probe https://brand.com/.well-known/gs1resolver, not the vendor’s apex. Your scan domain must serve the file itself.

Does a GTIN path resolve?

For a registered GTIN, GET /01/{gtin} (or /gs1/01/{gtin} where that prefix is used) should redirect to the default link, typically a product information page (pip). The standard does not fix the status code; QRCodeStack’s resolver answers with HTTP 307.

  • GET, HEAD and OPTIONS are allowed, because CORS preflight matters for browser clients.
  • Any Link headers the resolver sends point at resources that resolve.
  • Query parameters other than linkType pass through on redirect, which the standard requires by default.

How should linkType behave?

A linkType is a query parameter that selects one of the links registered for a GTIN.

  • ?linkType=pip (or another published type) redirects to that specific link.
  • ?linkType=linkset returns the full link set as JSON.
  • ?linkType=unknown returns 404. The standard says a resolver SHALL return 404 Not Found when the requested type of link is not available. GS1 Digital Link 1.1 instead fell back to the default link and handed the client the wrong resource.

Also send Accept: application/linkset+json or application/ld+json to the GTIN URI; it should reach the linkset without relying on the query string.

What does the URI itself need?

Resolver conformance assumes a conformant Digital Link URI: 14-digit GTINs, application identifiers in the mandated path order, and attributes such as expiry in the query string where URI Syntax 1.7.0 places them. Our GS1 Digital Link generator validates against the ratified text.

For EU packaging that must stay editable after print, pair the resolver with a dynamic destination and review EU Digital Product Passport requirements.

Quick checklist

  1. /.well-known/gs1resolver returns a description file on the origin printed on pack.
  2. /01/{gtin} redirects to the default link.
  3. linkType selects links, linkset returns the set, unknown types 404.
  4. CORS allows GET, HEAD and OPTIONS.
  5. Brand custom domains serve their own well-known file.

QRCodeStack mounts its resolver at the origin root and under /gs1, and resolves custom domains for the brand that owns the hostname. Plans are on /pricing. The 7-day free trial needs no credit card and includes 5 dynamic QR codes, 0 static, 25 short links. Static QR codes in your account require a paid plan.

Build on a conformant resolver

Generate Digital Link QR codes, verify /.well-known/gs1resolver, and use editable destinations. 7-day free trial, no credit card — 5 dynamic, 0 static, 25 short links. From $9/mo.

Open GS1 Digital Link