feat(amdp): example validator + fix I-6 violation in procurement example#3
Merged
Merged
Conversation
…example
The amdp-spec now ships with `tools/validate-examples.py`, a reference
validator that extracts the JSON Schema from SPECIFICATION.md section 2.1
at runtime and checks each example against:
- Schema (Draft 2020-12) — required fields, UUID v7 mandate_id pattern,
enum constraints on vertical and signature algorithm
- Issuer rule I-6 — expires_at MUST NOT be more than 12 months after
issued_at
- Section 4.5 — action identifiers MUST be defined for the mandate's
vertical
- Section 5 — vertical-specific constraints (currently `data_classes`,
public-services only) MUST appear only in mandates for the matching
vertical
- delegation_chain entries MUST be UUID v7 (friendlier error message
than the schema gives)
The validator caught one real conformance failure on first run:
- `examples/procurement-cross-vendor.json` had `expires_at` 367 days
after `issued_at`, violating I-6. Tightened to exactly one year
(2027-04-28T09:30:00Z). The other four examples passed unchanged.
Usage:
pip3 install jsonschema
python3 amdp-spec/tools/validate-examples.py
Exit codes are 0 (all pass), 1 (one or more failures), 2 (spec or
examples unreadable). `--quiet` suppresses passing files, `--json`
emits machine-readable output.
The schema lives only in SPECIFICATION.md section 2.1 — no separate
`mandate.schema.json` was added because that would create a second
source of truth. If implementers want a standalone schema file, the
validator can be repurposed to emit one.
Closes the "validate examples before IAB Tech Lab submission" gap from
the AMDP 2026-05-17 spec-drop session.
Co-Authored-By: Claude Opus 4.7 (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.
Was
Reference validator für die AMDP-Examples plus 1 echter Konformitäts-Bug-Fix.
Warum
Vor IAB-Tech-Lab-AAMP-Submission KW21 (E-Mail-Draft in nexbid PR #602) müssen die Examples nachweislich validieren. Bislang war kein Validator vorhanden — der Spec-Drop vom 2026-05-17 (PR #1) ist Doc-only.
Bug-Befund
examples/procurement-cross-vendor.jsonhatteexpires_at367 Tage nachissued_at. Issuer-Rule I-6 (SPECIFICATION.md section 2.1 + Issuer-Conformance):Validator hat es beim ersten Lauf gefangen. Fix:
expires_atauf2027-04-28T09:30:00Z(exakt ein Jahr nach issued_at). Die anderen 4 Examples sind unverändert geblieben.Änderungen
tools/validate-examples.py(+341 Zeilen, NEU)Python 3.9+ Validator mit Single-File-Approach, nur Standard-Library + jsonschema. Extrahiert das Schema aus SPECIFICATION.md section 2.1 zur Laufzeit (kein doppeltes
schema.json). Conformance-Checks:data_classesnur in public-services (per Spec)Exit-Codes: 0 (all pass), 1 (failures), 2 (unreadable spec/examples).
CLI-Flags:
--quiet— nur Failures+Warnings ausgeben--json— machine-readable Output (für CI-Integration)examples/procurement-cross-vendor.json(Fix)expires_at2027-05-01T00:00:00Z → 2027-04-28T09:30:00Z (genau 1 Jahr nach issued_at).time_window.toanalog aktualisiert.README.md(+10 Zeilen)Validator in Spec-Übersichts-Tabelle eingetragen + neue "Validating examples locally" Sektion mit Install/Run/Output-Hinweis. Schema-Single-Source-of-Truth-Begründung dokumentiert.
CHANGELOG.md(+12 Zeilen)Neuer [Unreleased] Block mit Added + Fixed Sektionen.
Tests
--jsonOutput ist parsebar (python3 -m json.tooldurchläuft)--quietzeigt nur Failures, nichts wenn alle passReview-Punkte
mandate.schema.json— bewusste Entscheidung gegen doppelte Source-of-Truth. Wenn IAB Tech Lab später ein standalone Schema verlangt, kann der Validator es generieren.data_classes(public-services). Spec-Section 5 deutet weitere Spezialisierungen an — wenn die formalisiert werden, im ValidatorVERTICAL_SPECIFIC_CONSTRAINTSMap erweitern.pull_requestevent aufamdp-spec/**)? Macht beim nächsten Spec-Edit Sinn.Dokumentation
--helpPending
Keine. Validator und Fix sind in sich abgeschlossen. Folge-Tasks (separate PRs sinnvoll):
@protocol-commerce/amdp-conformance(TypeScript-Counterpart) — bereits in CHANGELOG.md als v0.2.0-Backlog gelistet🤖 Generated with Claude Code