a2aproject / a2aproject/a2a-rs
a2acli: card get --validate against the A2A JSON schema
- Vorherrschende Sprache
- Rust
- Sterne
- 76
- Forks
- 19
- Ø Merge
- 1 T. 5 Std.
- Gemergte PRs (30 T.)
- 58
Beschreibung
Part of #181 (Tier 2).
## Summary
`A2ACLI_CARD_GET_002` (Tier 2) requires `card get --validate` — validate the Agent Card against the A2A schema (§10.1).
`a2acli` deserializes the card into `a2a::AgentCard` and reports a deserialization failure as `A2ACLI_ERR_CARD_INVALID` (#173). That is a type check, not a schema check: it accepts a card that parses into the Rust type while violating the published schema, and it says nothing about *which* constraint failed.
The canonical schema is [`A2A/specification/json/a2a.json`](https://github.com/a2aproject/A2A/blob/main/specification/json/a2a.json) — the same source the Python SDK generates its types from.
## Why
`card get` is the command you reach for when an agent is not behaving, and "is this card actually valid?" is the first question. Serde's answer is binary and its error messages describe Rust types, not schema constraints, so a card that is structurally wrong in a way serde tolerates (a field with a permissive type, an unrecognized enum handled leniently) passes today.
## A note on conforming to the canonical implementation
The Go CLI validates the card **unconditionally** rather than behind a flag — `internal/cli/card_get.go` calls `cfg.agentCard.Validate()` on every `card get`, and has no `--validate`. `COMPLIANCE.md` names the flag, so the specification and the reference implementation disagree here.
Proposal: implement `--validate` as the spec names it, and keep the current unconditional type check as-is. That satisfies the requirement without changing default behavior, and leaves room to align with Go if the spec is later amended toward unconditional validation. Worth raising upstream in `a2a-cli` either way.
## Scope
- [ ] Add `--validate` to `card get`: validate the fetched card against the A2A JSON schema and report the outcome.
- [ ] Decide how the schema is obtained — vendored into the repo at a pinned A2A version, or generated into `a2a` at build time. Vendoring is simpler; either way the A2A version it came from must be recorded and reported, because "valid" is meaningless without saying valid against what.
- [ ] Report **every** violation, not just the first, with a JSON-pointer path to each — a card with three problems should take one run to diagnose.
- [ ] `text` renders violations as a block under its own `Label:` line (§11.2); `-o json` carries them as structured data.
- [ ] A card that fails validation exits non-zero with `A2ACLI_ERR_CARD_INVALID` (Appendix D), consistent with the existing deserialization failure.
- [ ] `--validate` against an unreachable agent still reports `A2ACLI_ERR_UNREACHABLE`; validation is not reached.
- [ ] Tests: a valid card passes; a card with a missing required field, a wrong type, and a bad enum value reports all three with their paths.
## Requirements closed
| ID | Requirement |
| --- | --- |
| `A2ACLI_CARD_GET_002` | `card get --validate` — validate the Agent Card against the A2A schema (§10.1) |
Beitragsleitfaden
Rechercherichtung
Das Issue betrifft den Befehl `card get` von `a2acli`. Beginne damit, den Code des Befehls zu untersuchen, wahrscheinlich in `src/cli/card_get.rs` oder an einer ähnlichen Stelle. Die Schema-Datei befindet sich unter `specification/json/a2a.json` im A2A project. Du musst einen JSON-Schema-Validator wie das `jsonschema`-crate integrieren, entscheiden, wie das Schema gebündelt werden soll, und den Befehl ändern, um das Flag `--validate` hinzuzufügen. Es sollten Tests hinzugefügt werden, um zu überprüfen, dass die Validierung korrekt erfolgreich ist und fehlschlägt, wobei alle Verstöße mit JSON-pointer-Pfaden gemeldet werden.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- json
- Bereich
- api, cli
- Issue-Typ
- Feature
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Aktiv
- Klarheit
- Klar beschrieben
- Anfängerfreundlichkeit
- 55/100