An open-source GS1 Digital Link conformant resolver, written in Clojure. Meets 22 of the 25 conformance criteria in the GS1-Conformant resolver standard v1.2.0 and scores 31/31 against the official browser-based test suite — see Conformance below for exactly what those pass-counts do and don't cover.
A reference implementation for people who want a working, spec-conformant GS1 DL resolver they can read, run, and extend. In-memory store, no database, no external service dependencies at runtime. The codebase is small enough to read in one sitting.
- 19 deftests covering each conformance criterion (59 assertions)
- 31/31 on the upstream GS1 test suite, driven from headless Chromium
- Continuous integration runs both suites on every push
These pass-counts are real, but they're not the whole story: the 18 deftests are
self-graded, and the 31 suite rows independently verify 19 of the standard's 25
conformance criteria. See Conformance below for what's independently
verified versus behaviourally confirmed, and where the gaps are.
Out of scope for this version:
- Full GS1 Digital Link Compression decoder — compression is not supported in this release; there is no decoder or stub, and compressed GS1 Digital Link URIs return HTTP 400 (see Conformance)
- Persistence beyond an in-memory atom
22 of 25 conformance criteria met (19 independently verified by GS1's own suite) against the GS1-Conformant Resolver Standard's own §5 Conformance statement (Release 1.2.0) — run unmodified against the live server and re-run on every commit, with results counted by the suite itself, not self-graded. 3 more criteria are confirmed by our own tests or direct observation. The remaining 3 are genuine gaps, stated plainly — one of them material (compression). See CONFORMANCE.md for the exact per-criterion breakdown.
Compression is explicitly out of scope for this release: it is not supported, and compressed GS1 Digital Link URIs return HTTP 400 rather than being decoded.
See CONFORMANCE.md for the full criterion-by-criterion matrix, the evidence tier behind every row, and the reasoning for each gap — including exactly what the "18 + 31" pass-counts above do and don't prove.
gs1.resolver.path ;; pure path-segment helpers
gs1.resolver.store ;; in-memory atom + put!/get-record
gs1.resolver.fixtures ;; conformance seed data
gs1.resolver.parse ;; DL URI validation + GS1 AI vocabulary
gs1.resolver.linkset ;; RFC 9264 linkset builder (pure)
gs1.resolver.handler ;; Ring handler — orchestrates the above
gs1.resolver.server ;; Jetty entry point (HTTP + optional HTTPS)
Dependencies flow one way. Linkset is a pure function of records, not a function that reaches into the store. The handler does the lookup.
Requirements: Java 21+, Clojure CLI.
clojure -M:run
# starts on http://localhost:8080The server seeds a single GTIN (09506000164908) with five link types
so you can probe the conformance behaviour immediately:
curl -i http://localhost:8080/01/09506000164908
curl -i 'http://localhost:8080/01/09506000164908?linkType=linkset'
curl -i 'http://localhost:8080/01/09506000164908?linkType=gs1:certificationInfo'
curl -i http://localhost:8080/.well-known/gs1resolverThe conformance suite expects HTTPS. Generate a self-signed keystore once:
./scripts/gen-keystore.shThen run with TLS:
SSL_PORT=8443 clojure -M:run
# starts on http://localhost:8080 and https://localhost:8443Environment variables: PORT (default 8080), SSL_PORT (no default —
HTTPS off unless set), KEYSTORE (default resources/keystore.jks),
KEY_PASSWORD (default changeit).
clojure -X:testDrives the upstream JavaScript suite against your running resolver.
# one-time setup
npm install
npx playwright install chromium
sudo npx playwright install-deps chromium # Linux only
./scripts/fetch-harness.sh # download upstream GS1 suite assets
./scripts/gen-keystore.sh
# in one terminal
SSL_PORT=8443 clojure -M:run
# in another
node run-conformance.mjsThe runner boots a tiny static server for the harness page, intercepts
the suite's calls to tester.php via Playwright's page.route (emulating
the upstream PHP cURL helper with Node fetch), waits until the suite's
result list stops growing, then prints a pass/fail summary.
Edit src/gs1/resolver/fixtures.clj. Each record looks like:
{"/01/09506000164908"
{:item-description "Crew neck white t-shirt"
:default-link-type "gs1:pip"
:links
{"gs1:pip"
[{:href "https://example.com/pip"
:title "Product Info"
:type "text/html"
:hreflang ["en"]}]
"gs1:certificationInfo" [...]}}}Anchor paths follow the canonical GS1 DL form: /01/{gtin} for primary,
/01/{gtin}/21/{serial} for a serial-number qualifier, etc. The
:default-link-type MUST exist as a key in :links.
clojure -M:nrepl
# nREPL on port 1667 with CIDER middlewareThe conformance harness loads three unmodified files from the GS1 test
suite plus an Ajv bundle. They live in harness/ at runtime but are
not committed — scripts/fetch-harness.sh downloads them, pinned to
known commit SHAs and verified by checksum. To refresh against a newer
upstream, update the SHAs at the top of the script, re-run it, and copy
the printed checksums into the script's EXPECTED_ table.
Issues and pull requests welcome. Before opening a PR:
clojure -X:testpassesnode run-conformance.mjsreturns 31/31 (or document a regression)
Apache License 2.0 — see LICENSE.
Third-party vendored components in harness/ are credited in NOTICE.