Open Badges 3.0 Conformance Suite Runbook

Intent

Validate the credential-export surface against the official 1EdTech Open Badges 3.0 schema early and repeatedly — the credential-lane analogue of the LRS upstream-battery lane (lrs-conformance-suite.md). Wired from the first signing slice, not a release-week smoke test.

See also: Credential Issuer Keys Runbook, credential-export-v1.md.

What it runs

bun run test:ob:conformance

tools/scripts/run-ob-conform-ed.ts boots an isolated Podman Compose stack (postgres + Supabase auth + supabase_vault) via the integration harness, applies the migrations, and runs tests/conformance/ob-credential.conformance.test.ts against the real export surface, then tears the stack down. Needs the rootless Podman socket up (systemctl --user start podman.socket).

The lane exercises the HTTP routes (auth + handlers, in-process) end to end: provision the platform issuer + an Ed25519 key, grant a fixture award, POST the export endpoint, and GET the issuer JWKS + Profile document. It then asserts:

1. VC-JOSE shape — a 3-part compact JWS with alg: EdDSA, typ: vc+jwt, and a kid in the protected header.
2. Discovery + signature — the kid resolves in the published JWKS and the signature verifies against that key.
3. Official schema — the decoded credential validates against the vendored 1EdTech ob_v3p0_achievementcredential_schema.json (draft 2019-09, via ajv) — the authoritative conformance assertion.
4. Normative structure — @context order, type membership, validFrom, credentialSubject/achievement required fields.
5. Issuer surface — the Profile document id matches the credential issuer; JWKS keys are OKP/Ed25519, use: sig, with no private material.

Conformance fixture

tests/conformance/fixtures/ob_v3p0_achievementcredential_schema.json is the official upstream schema, vendored verbatim (provenance in that directory’s README.md). Refresh it from https://www.imsglobal.org/spec/ob/v3p0/ if the OB 3.0 schema is revised, and re-run the lane.

CLR 2.0 lane (sibling)

bun run test:clr:conformance

tools/scripts/run-clr-conform-ed.ts runs tests/conformance/clr-credential.conformance.test.ts on the same isolated Compose stack. It provisions the platform transcript issuer + key and two per-org issuers, grants two awards across the two orgs, POSTs /workflow/credentials/clr, then asserts the same VC-JOSE / discovery / signature checks plus: the decoded CLR validates against the vendored official 1EdTech clr_v2p0_clrcredential_schema.json (draft 2019-09, via ajv); the bundle has one entry per granted award with per-award ids; the subject is a single coherent transcript pairwise URI shared by every inner credential; the hashed-email IdentityObject sits once at the ClrSubject; and each inner achievement keeps its own org issuer (the multi-issuer bundle). Refresh the CLR fixture from https://www.imsglobal.org/spec/clr/v2p0/ if the schema is revised, and re-run.

Development lifecycle policy

• From the first signing slice: the lane is wired and expected green for the export surface as it exists (currently the AchievementCredential pull).
• Milestone / release gates: the lane must be green. A failing schema or signature check blocks credential-lane readiness even if unit and integration tests are green.
• The CLR 2.0 assembler and any new proof format (Data Integrity) extend this lane with their own conformance fixtures before they are marked validated.

Scope notes

• The official 1EdTech hosted conformance system (manual submission of a live issuer) remains the external bar for a public validated claim; this lane is the automated, in-CI gate that keeps the export schema-conformant continuously.
• Run only against the disposable Compose stack — never a production issuer.