Skip to content

SecurityRequirement JSON serialization doesn't match proto specification #667

Closed

Description

@kabir

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

Verification

To verify this is fixed, the test above should pass, and the generated JSON should include the schemes field wrapper.

Activity

  1. self-assigned this
    on Feb 18, 2026
  2. added this to the 1.0.0 milestone on Feb 18, 2026
  3. jmesnil commented on Feb 18, 2026

    @jmesnil
    Contributor

    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:

        "Security Requirement": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "additionalProperties": false,
          "description": "Defines the security requirements for an agent.",
          "properties": {
            "schemes": {
              "additionalProperties": {
                "$ref": "lf.a2a.v1.StringList.jsonschema.json"
              },
              "description": "A map of security schemes to the required scopes.",
              "propertyNames": {
                "type": "string"
              },
              "type": "object"
            }
          },
          "title": "Security Requirement",
          "type": "object"
        },
        "String List": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "additionalProperties": false,
          "description": "A list of strings.",
          "properties": {
            "list": {
              "description": "The individual string values.",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "title": "String List",
          "type": "object"
        },

    So the correct JSON representation is:

      "securityRequirements" : [
        {
          "schemes": {
            "oauth2": {
              "list": ["profile"]
            }
          }
        }
      ]
    
  4. added 3 commits that reference this issue on Feb 18, 2026
    eda37d3
    c7eddff
    a1d844c
  5. added a commit that references this issue on Feb 18, 2026
    8946760
  6. added a commit that references this issue on Feb 19, 2026
    05f5f00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions