Repository navigation
Closed
Description
SecurityRequirement JSON serialization doesn't match proto specification
Environment
- SDK Version: 1.0.0.Alpha2
- Affected Module:
jsonrpc-common,spec
Problem
The JSON serialization of AgentCard.securityRequirements doesn't match the proto definition, causing deserialization failures when clients fetch agent cards.
Expected Behavior (per proto spec)
According to specification/a2a.proto, SecurityRequirement is defined as:
message SecurityRequirement {
// A map of security schemes to the required scopes.
map<string, StringList> schemes = 1;
}This means the JSON should have a schemes field wrapping the map:
{
"securityRequirements": [
{
"schemes": {
"oauth2": ["profile"]
}
}
]
}Actual Behavior (SDK 1.0.0.Alpha2)
The SDK currently generates JSON without the schemes wrapper:
{
"securityRequirements": [
{
"oauth2": ["profile"]
}
]
}Impact
When a client tries to fetch an agent card with securityRequirements, deserialization fails with:
io.a2a.jsonrpc.common.json.InvalidParamsJsonMappingException:
Invalid request content: oauth2 in message a2a.v1.SecurityRequirement.
Please verify the request matches the expected schema for this method.
This breaks OAuth2-enabled agents completely as clients cannot parse their agent cards.
Reproducer
package io.a2a.spec;
import io.a2a.jsonrpc.common.json.JsonUtil;
import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.*;
/**
* Reproducer for SecurityRequirement JSON serialization bug.
*/
public class SecurityRequirementSerializationBug {
@Test
public void testAgentCardWithSecurityRequirementsSerialization() throws Exception {
// Create an AgentCard with OAuth2 security
AgentCard agentCard = AgentCard.builder()
.name("Test Agent")
.description("Agent with OAuth2 security")
.version("1.0.0")
.supportedInterfaces(List.of(new AgentInterface("jsonrpc", "http://localhost:9999")))
.capabilities(AgentCapabilities.builder().build())
.defaultInputModes(List.of("text"))
.defaultOutputModes(List.of("text"))
.skills(List.of())
.securityRequirements(List.of(Map.of("oauth2", List.of("profile"))))
.securitySchemes(Map.of("oauth2",
OAuth2SecurityScheme.builder()
.flows(OAuthFlows.builder().build())
.build()))
.build();
// Serialize to JSON
String json = JsonUtil.toJson(agentCard);
System.out.println("Generated JSON: " + json);
// Try to deserialize - this fails with InvalidParamsJsonMappingException
AgentCard deserialized = JsonUtil.fromJson(json, AgentCard.class);
assertNotNull(deserialized);
assertEquals(1, deserialized.securityRequirements().size());
}
}Workaround
Currently, agents must omit securityRequirements entirely and only specify securitySchemes:
return AgentCard.builder()
// ... other fields ...
// .securityRequirements(...) // MUST BE OMITTED due to SDK bug
.securitySchemes(Map.of("oauth2", securityScheme))
.build();Related
- Proto spec:
specification/a2a.protolines definingSecurityRequirement - Previous security serialization fix: fix: Fix Security JSON serialization #592 (fixed
SecurityScheme, but notSecurityRequirement)
Verification
To verify this is fixed, the test above should pass, and the generated JSON should include the schemes field wrapper.
Reacted by Jeff Mesnil
Metadata
Metadata
Assignees
Labels
bugSomething isn't workingSomething isn't working
Activity
jmesnil commentedon Feb 18, 2026
I don't think the JSON representation in the description is correct.
The canonical JSON representation of Security Requirements is defined in https://a2a-protocol.org/latest/definitions/#json as such:
So the correct JSON representation is:
feat!: Add SecurityRequirement to the domain API
feat!: Add SecurityRequirement to the domain API
feat!: Add SecurityRequirement to the domain API
feat!: Add SecurityRequirement to the domain API (#670)
feat!: Add SecurityRequirement to the domain API