This is a documentation bug, based on the 0.3.0 version of the A2A spec.

There is considerable ambiguity in what the payload for requests and responses (success and error) should be under the HTTP+JSON/REST transport. This has led to incompatible behavior in some SDKs such as ADK and .NET A2A.

Section 3.2.3 states that the transport "MUST use JSON objects that are structurally equivalent to the core A2A data structures." It is not defined what "structurally equivalent" means: one-to-one key name and value type? key isomorphism (e.g., case or naming transformations accepted)?

Section 6.11 states that "A2A adheres to the standard JSON-RPC 2.0 structures for requests and responses." Is this statement only applicable to JSON-RPC transport?

Sections 6.11.1 and 6.11.2 both speak generally about method calls and responses being encapsulated in JSON-RPC objects, without scoping this specifically to JSON-RPC transport. But 6.11.3 specifically says "When a JSON-RPC call encounters an error, the Response Object will contain an error member with a value of this structure."

Section 7 shows REST payload definitions for some protocol methods but not all; and these are not encapsulated in JSON-RPC structures. In 7.1 we see this statement: "The error response for all transports in case of failure is a JSONRPCError or equivalent." However, no examples or definitions of an HTTP equivalent payload for an error response are given.

Section 8 says "Errors are returned in the error member of the JSONRPCErrorResponse [sic] object." This seems to conflict with 7.1 saying the error response is the JSONRPCError—should it be wrapped in the JSONRPCResponse object, or not, or only for JSON-RPC?

Finally, in 11.1.5 it says that agents "MUST use valid JSON-RPC 2.0 request/response objects as defined in Section 6.11." Is this implicitly only for JSON-RPC transport?

The asks:

1. Clarify language in 3.2.3 and 7.1 to define equivalence.
2. Be clear throughout Section 6, 8, and 11.1.5 what parts apply to all transports and what is strictly JSON-RPC only.
3. Move the definition of error response format to a more top-level location, not as an aside at the end of the message/send method definition
4. Clarify what the actual request, response, and error payloads should be for HTTP (whether JSONRPCResponse, JSONRPCError, bare protocol data objects, etc.) for all protocol methods
5. Provide some HTTP-specific examples of requests, successful responses, and error responses.
6. Clarify in 3.2.3 whether HTTP status codes are to be used instead of, or together with, the JSON-RPC error codes defined in Section 8 and referred to in 11.1.5.
7. Explicitly map defined A2A and JSON-RPC error codes to HTTP status codes.

Relevant log output

N/A

Code of Conduct

• I agree to follow this project's Code of Conduct