Skip to content

About

An open-source GS1 Digital Link conformant resolver, written in Clojure.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

gs1-resolver

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.

What this is

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.

Status

  • 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

Conformance

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.

Architecture

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.

Running it

Requirements: Java 21+, Clojure CLI.

HTTP only

clojure -M:run
# starts on http://localhost:8080

The 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/gs1resolver

HTTPS

The conformance suite expects HTTPS. Generate a self-signed keystore once:

./scripts/gen-keystore.sh

Then run with TLS:

SSL_PORT=8443 clojure -M:run
# starts on http://localhost:8080 and https://localhost:8443

Environment variables: PORT (default 8080), SSL_PORT (no default — HTTPS off unless set), KEYSTORE (default resources/keystore.jks), KEY_PASSWORD (default changeit).

Running the tests

Clojure unit/conformance tests

clojure -X:test

Official GS1 test suite (headless Chromium)

Drives 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.mjs

The 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.

Adding records

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.

REPL

clojure -M:nrepl
# nREPL on port 1667 with CIDER middleware

Upstream harness assets

The 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.

Contributing

Issues and pull requests welcome. Before opening a PR:

  • clojure -X:test passes
  • node run-conformance.mjs returns 31/31 (or document a regression)

License

Apache License 2.0 — see LICENSE.

Third-party vendored components in harness/ are credited in NOTICE.

About

An open-source GS1 Digital Link conformant resolver, written in Clojure.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages