OpenEPCIS

Resolver Setup Guide

How to expose your DPP behind a GS1 Digital Link resolver

resolvergs1-digital-linklinkset 4 min read

Overview

A GS1 Digital Link resolver turns a product identifier (GTIN + optional serial) into the right URL for the right audience — the consumer information page, the EPCIS event history, certificates, recall information, and so on. Each of those is a link relation taken from the GS1 vocabulary.

For a Digital Product Passport you only need two things to be live:

  1. A resolver endpoint that responds to /{primary key}/{value} Digital Link URLs — most often /01/{GTIN}/21/{serial}.
  2. A linkset per identifier — a small application/linkset+json document (IETF RFC 9264) that says which URL to send each link relation to. GS1 relations appear as full-IRI keys, e.g. https://ref.gs1.org/voc/pip.

Hosting options

OptionWhen to choose it
Verified by GS1 (managed)You want GS1 to host the resolver under id.gs1.org. Lowest operational effort, subscription-based.
Self-hosted under your own domainYou already operate a domain you want consumers to see, e.g. id.yourcompany.com. You manage TLS, scale and uptime.
Your domain, operated for you (CNAME)Consumers see id.yourcompany.com, but a platform runs the resolution behind it. You point one DNS record at the operator; the operator handles TLS, scale and uptime. This is the option most brand owners want, and the section below explains why it matters beyond convenience.
HybridGS1 holds the canonical id.gs1.org entry and redirects to your domain for resolution. Brand control without running global ID infrastructure.

The identifier belongs to the brand owner

This is a design principle, not a preference, and it has consequences that are hard to undo — so it is worth stating before the first label is printed.

The host in a printed Digital Link is permanent. A QR code on a battery, a garment or a construction product is read for as long as the product exists, which under ESPR means years after it left the factory. Whatever hostname is in that URL cannot be changed for items already in the field.

Therefore it should be a hostname the brand owner controls. Point id.yourcompany.com at your operator with a CNAME and the printed code carries your domain. Change operator later, or bring resolution in-house, and you repoint one DNS record: every code already printed keeps working. Put the operator's hostname on the label instead and you have handed a third party a permanent dependency on every product you ever shipped.

It also happens to be the semantically correct choice. The brand owner holds the GS1 prefix licence for those GTINs; the identifier namespace matching the licence holder is what the GS1 licence chain expresses, and what an auditor expects to see as the responsible economic operator.

Two rules follow, and they are not the same rule.

Linksets rebase per request. A resolver answering on id.yourcompany.com anchors its linkset there — GS1 conformance compares the anchor against the requested URL byte for byte, so this is required rather than optional. The same product answers correctly on every hostname bound to it.

Identities are minted once and never rebase. The identifier written into a signed passport credential is fixed at issuance. It cannot follow the request context, or two credentials for the same product would disagree about what that product is. A later domain change applies to newly issued credentials and leaves existing ones untouched.

Signed credentials add one wrinkle worth knowing about, and it cuts in a reassuring direction: verification does not depend on the identifier resolving. A verifier needs the published contexts and the issuer's key document, not the subject URL. A brand domain that lapses breaks the click-through from identifier to data — it does not invalidate a single passport. Where that click-through matters, a credential can carry a second, operator-resolvable form of the same identity alongside the brand one, so both paths survive independently. See Signed Passports.

How the resolver itself is built is intentionally out of scope here — any HTTP server that can match the Digital Link path patterns, do content negotiation on Accept, and route on the ?linkType= query parameter will do. OpenEPCIS ships a reference resolver in the business edition; see Modules → Resolver.

Getting onto Verified by GS1

  1. Contact your local GS1 Member Organisation and subscribe to Verified by GS1.
  2. Make sure you have a valid GS1 Company Prefix and that the GTINs you'll publish are registered against it.
  3. Publish a linkset per identifier — one object per anchor, GS1 relations as full-IRI keys, link descriptors as values. Refer to RFC 9264 and the GS1 Digital Link standard for the exact field shape.

A worked end-to-end example is on the DPP Resolution Flow page.

A note on the linkType query parameter

When you call a resolver URL like https://id.gs1.org/01/{GTIN}/21/{serial}?linkType=…, the value is a bare GS1 relation name (pip, epcis, certificationInfo, …) — not the compact gs1: form. The compact / full-IRI form only appears as the key in the linkset JSON itself.

Next steps