check: digital-link-resolver — verify a DECLARED Digital Link interface - #1
Merged
Merged
Conversation
…interface
An OPTIONAL third interface beside `interfaces.http` and `interfaces.mcp`.
The card naming `interfaces.digitalLink` is the whole gate, and it cuts both
ways:
- OMITTED ⇒ the check SKIPs, the well-known is never fetched, no budget is
spent, and the grade is untouched. Nothing that conformed yesterday starts
failing. The `apis-ax-standard` pinned spec is NOT touched — it stays at 21
requirements and its digest is unchanged. A target that wants this enforced
pins `digital-link-resolver` in its own spec.
- DECLARED ⇒ judged strictly. GS1 fixes the discovery indicator (RFC 8615
/.well-known/gs1resolver; "the presence or absence of this file can be used
to determine whether or not the URI points to a service conformant to this
standard"), so the well-known must be same-origin, answer 2xx with a JSON
media type, parse, and validate against GS1's published description-file
schema. A machine-readable claim is one a verifier will believe.
GS1's schema is VENDORED and digest-pinned (sha256:99d505c7…, the bytes
ref.gs1.org served 2026-08-06), never fetched at verification time: a
third-party document its publisher can edit would be a sixth input to the
determinism invariant, and `observe` refuses off-origin fetches anyway. The
runtime constraint is a hand-written MiniSchema translation, audited against
the vendored bytes keyword by keyword in BOTH directions — a dropped constraint
and an invented one each fail the suite (both proven by mutation).
What is deliberately NOT enforced is named in the verdict text, not just in a
comment: draft-07 `format: "uri"` is an annotation, and `contact.hasTelephone`
sits outside a keyword position in GS1's own file, so GS1's schema does not
validate it and neither do we. RFC 9264 linkset behaviour is out of scope —
this check verifies the discovery indicator, not resolution.
Failing cases shipped, and they are the point: 404, non-2xx, unparseable JSON,
non-JSON content-type, missing required member, out-of-vocabulary primary key,
resolverRoot naming another origin, card/document resolverRoot disagreement,
network failure, cross-origin claim (refused unfetched), private/metadata
claim, and four malformed declaration shapes. A present-but-defective
declaration FAILs — it is never collapsed to an absence.
Verified against reality: https://id.org.ai/.well-known/gs1resolver returns 404
today, so the estate's own resolver would FAIL this check if it declared the
interface. That is asserted from the recorded 404, and — under
APIQA_LIVE_NET=1 — against the live host. barcoding.dev's live document (which
does serve 200) is vendored and asserted to validate, so the validator has seen
a real in-the-wild file and not only its own fixtures.
44 new tests. Full suite: 1005 passed, 4 skipped, 36 files.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Optional-when-declared: skips when the card declares nothing, verifies GS1's published description-file schema when it does. 1005 passed / 4 skipped (was 963/2). Not pinned in the standard's own spec, so no existing surface can start failing.