Agent Card Reader / Validation rules
A2A agent card validation rules
Every check the reader runs, with the section of the A2A specification it comes from. Problems break conformance and clients may reject the card; warnings are SHOULD-level or likely mistakes; notes are informational. Rules marked as hints are not in the spec.
Is it an agent card at all
- Problem Not an agent card
- JSON with fewer than 3 of the card fields (name, description, supportedInterfaces, version, capabilities, skills, defaultInputModes, defaultOutputModes) is rejected instead of decoded. spec
- Problem Must be a JSON object
- A card is a single JSON object, not an array or a string. spec
Required fields and types
- Problem Missing required field
- Every field marked required in §4.4 and §4.5 must be present, for example AgentCard name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes and skills; AgentSkill id, name, description and tags. spec
- Problem Required array is empty
- Arrays marked required must contain at least one element: supportedInterfaces, defaultInputModes, defaultOutputModes, skills, and each skill's tags. spec
- Problem Wrong type
- Strings must be strings, booleans true or false (not "yes"), objects objects, arrays arrays. The message names the field and the type found. spec
- Problem snake_case field name
- JSON uses camelCase: default_input_modes must be written defaultInputModes. The reader recognises the snake_case form and names the right one. spec
- Note Unknown field
- A field not in the 1.0 table is reported but not an error; clients should ignore unrecognized fields. spec
- Note Empty string
- An empty string where text is expected. A hint, not a spec rule.
URLs and media types
- Problem Not an absolute URL
- URL fields (documentationUrl, iconUrl, provider.url, OAuth endpoints, openIdConnectUrl, oauth2MetadataUrl) must be absolute. spec
- Warning Plain HTTP
- HTTP-based interfaces must use HTTPS in production; plain http is flagged (localhost excepted). spec
- Warning Not a media type
- defaultInputModes, defaultOutputModes and per-skill modes are media types such as text/plain or application/json. spec
Interfaces and bindings
- Problem gRPC address format
- A GRPC interface URL is "hostname:port", for example grpc.example.com:443. spec
- Problem Misspelled core binding
- protocolBinding values close to a core binding (HTTP-JSON, jsonrpc) must use the exact spelling: JSONRPC, GRPC or HTTP+JSON. spec
- Warning Custom binding is not a URI
- Custom bindings should be identified by a URI, such as https://example.com/bindings/websocket/v1. spec
- Note Custom binding
- A URI binding is valid; only clients that know it can use that interface. Custom bindings may use any URL scheme, such as wss://. spec
- Warning protocolVersion format
- protocolVersion should look like "1.0" (Major.Minor). spec
- Note Duplicate interface
- Two entries with the same url, binding and version. A hint, not a spec rule.
Security
- Problem SecurityScheme must hold exactly one scheme
- Each entry of securitySchemes contains exactly one of apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme. spec
- Problem API key location
- apiKeySecurityScheme.location is "query", "header" or "cookie". spec
- Problem OAuthFlows must hold exactly one flow
- flows contains exactly one of authorizationCode, clientCredentials, implicit, password, deviceCode. spec
- Warning Deprecated OAuth flow
- implicit and password flows are deprecated; use authorization code with PKCE, or device code. spec
- Problem Requirement names an undefined scheme
- Every scheme named in securityRequirements must be declared in securitySchemes. spec
Skills
- Problem Duplicate skill id
- Skill ids are unique identifiers; the same id twice is an error. spec
Signatures (§8.4)
- Problem Unreadable protected header
- protected must be base64url-encoded JSON. spec
- Problem Header lacks alg or kid
- The protected header must include alg and kid. spec
- Warning typ is not JOSE
- typ should be "JOSE". spec
- Problem alg "none"
- An unsigned signature proves nothing. spec
- Warning jku over plain HTTP
- Fetch the key set over HTTPS. spec
- Problem Invalid signature
- The signature does not match the canonical card: the card changed after signing, or it was signed over a different canonical form. See how signatures work. spec
Older 0.3 cards
- Note 0.3 field names
- url, preferredTransport, additionalInterfaces, top-level protocolVersion, security and supportsAuthenticatedExtendedCard are read and explained, OpenAPI-style schemes ("type": "apiKey") too. See the migration guide.
Based on the A2A specification (latest, 1.0). Updated 2026-10-14. Check a card now: open the reader.