Signing/verification canonicalization drops REQUIRED fields at their default value, breaks cross-SDK Agent Card signature verification

[aeoess]

What happened

_canonicalize_agent_card (used by both create_agent_card_signer and create_signature_verifier in src/a2a/utils/signing.py) removes empty strings, empty lists, and empty dicts from the Agent Card before canonicalizing, with no exception for fields the spec marks REQUIRED. Section 8.4.1 of the A2A specification says the opposite: REQUIRED fields must stay in the canonical payload even when they hold their default value.

The result is that a card signed by an SDK that keeps a REQUIRED field at its default value in the signed payload (for example description: "" or skills: []) fails verification in a2a-python, because a2a-python recomputes a different canonical payload for the same card.

Where it happens

At main, commit 0d5473ca4fa6d40034a6a7c8d65bce5cd85d8167:

src/a2a/utils/signing.py, _canonicalize_agent_card (lines 198-208):

def _canonicalize_agent_card(agent_card: AgentCard) -> str:
    """Canonicalizes the Agent Card JSON according to RFC 8785 (JCS)."""
    card_dict = MessageToDict(
        agent_card,
    )
    # Remove signatures field if present
    card_dict.pop('signatures', None)

    # Recursively remove empty values
    cleaned_dict = _clean_empty(card_dict)
    return canonicalize(cleaned_dict)

Two things contribute:

1. MessageToDict(agent_card) is called without always_print_fields_with_no_presence=True. Proto3 fields that have no explicit presence tracking (this includes the REQUIRED fields description, skills, and AgentSkill.tags, none of which carry the optional keyword) are omitted from the dict entirely once they hold the default value, before _clean_empty ever runs.
2. _clean_empty (lines 167-195) then unconditionally strips any remaining empty string, list, or dict:

def _clean_empty(d: Any, depth: int = 0) -> Any:
    ...
    if isinstance(d, dict):
        cleaned_dict = {
            k: cleaned_v
            for k, v in d.items()
            if (cleaned_v := _clean_empty(v, depth + 1)) is not None
        }
        return cleaned_dict or None
    if isinstance(d, list):
        cleaned_list = [
            cleaned_v
            for v in d
            if (cleaned_v := _clean_empty(v, depth + 1)) is not None
        ]
        return cleaned_list or None
    if isinstance(d, str) and not d:
        return None
    return d

Neither step distinguishes a REQUIRED field at its default value from an optional or repeated field that happens to be empty.

Permalink:

a2a-python/src/a2a/utils/signing.py

Lines 167 to 208 in 0d5473c

	def _clean_empty(d: Any, depth: int = 0) -> Any:
	"""Recursively remove empty strings, lists and dicts from a dictionary.
	Depth is bounded for the same reason canonicalization is: nesting reaches
	this function from `AgentExtension.params`, and without the bound a deeply
	nested card exhausts the interpreter stack here, before the canonicalizer
	ever gets the chance to reject it.
	"""
	if depth > MAX_DEPTH:
	raise CanonicalizationError(
	f'nesting exceeds the maximum depth of {MAX_DEPTH}'
	)
	if isinstance(d, dict):
	cleaned_dict = {
	k: cleaned_v
	for k, v in d.items()
	if (cleaned_v := _clean_empty(v, depth + 1)) is not None
	}
	return cleaned_dict or None
	if isinstance(d, list):
	cleaned_list = [
	cleaned_v
	for v in d
	if (cleaned_v := _clean_empty(v, depth + 1)) is not None
	]
	return cleaned_list or None
	if isinstance(d, str) and not d:
	return None
	return d
	def _canonicalize_agent_card(agent_card: AgentCard) -> str:
	"""Canonicalizes the Agent Card JSON according to RFC 8785 (JCS)."""
	card_dict = MessageToDict(
	agent_card,
	)
	# Remove signatures field if present
	card_dict.pop('signatures', None)
	# Recursively remove empty values
	cleaned_dict = _clean_empty(card_dict)
	return canonicalize(cleaned_dict)

Spec requirement

A2A specification, docs/specification.md, section 8.4.1, "Canonicalization Requirements" (checked at commit 43e0c874d3baba68ed84b98678d7f2268438e69f):

• Required fields: Fields marked with REQUIRED MUST always be present, even if the field value matches the default.
• Default values: Fields with default values MUST be omitted unless the field is marked as REQUIRED or has the optional keyword.

The section's own worked example signs this fragment:

{
  "name": "Example Agent",
  "description": "",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extensions": []
  },
  "skills": []
}

and gives this as the canonical result:

{"capabilities":{"pushNotifications":false,"streaming":false},"description":"","name":"Example Agent","skills":[]}

description (REQUIRED, empty string) and skills (REQUIRED, empty array) both stay in the canonical payload. extensions (not REQUIRED, empty array) is omitted. Current _canonicalize_agent_card drops description and skills along with extensions, contradicting the first bullet above.

Minimal reproduction

Python only, no other SDK needed:

from a2a.types import AgentCapabilities, AgentCard, AgentInterface
from a2a.utils.signing import _canonicalize_agent_card

card = AgentCard(
    name="Example Agent",
    description="",
    version="1.0.0",
    supported_interfaces=[
        AgentInterface(
            url="https://example.com/a2a/v1",
            protocol_binding="JSONRPC",
            protocol_version="1.0",
        )
    ],
    capabilities=AgentCapabilities(streaming=False, push_notifications=False),
    default_input_modes=["text/plain"],
    default_output_modes=["text/plain"],
    skills=[],
)

print(_canonicalize_agent_card(card))

Expected per 8.4.1: description and skills are present in the output ("description":"", "skills":[]).
Actual: both are absent from the canonical payload.

Cross-SDK consequence

We ran this against a2a-go PR #441 (bb750f5c7913b967d8dcbe3d24537a8a84dd1a61), which keeps description and skills in the signed wire JSON when they are at their default value (its Go struct tags do not mark those fields omitempty). Five single-field cases, one Ed25519 key shared on both sides:

Case	Go signs, Python verifies	Python signs, Go verifies
description: ""	fails, InvalidSignaturesError: No valid signature found	passes
skills: []	fails, same error	passes
capabilities.extensions: [] (not REQUIRED)	passes	passes
skill.tags: [] (REQUIRED on AgentSkill per a2a.proto)	fails, same error	passes
control, no empty/default values	passes	passes

The a2a-go maintainer reached the same reading on #441: "python behaviour is not spec-compliant here".

Python signs a card and Go verifies it without trouble in every case, because a2a-go's own canonicalizer does not remove already-present fields. The failures only run in the direction where Go emits a spec-compliant payload (REQUIRED field present at default) and Python's canonicalizer removes what the signer actually signed.

Proposed fix direction

Build the canonical JSON according to the field-presence rules in section 8.4.1: preserve REQUIRED fields even at their default value, preserve explicitly set optional fields, and continue omitting non-required default-valued fields. One implementation could use MessageToDict(..., always_print_fields_with_no_presence=True) followed by descriptor-aware filtering based on field_behavior and field presence.

Related

• a2a-go PR fix: Sync jsonrpc and rest implementation of authenticated agent card #441 discussion, our comment on the Go golden test covering the same interop gap: fix: a2acrypto canonicalization and refactoring a2a-go#441 (comment)
• agent_card_to_dict omits the REQUIRED empty skills field #1261 and [Bug]: AgentCard REQUIRED fields are never validated #1267 are related (same MessageToDict-drops-REQUIRED-empty-fields root behavior) but cover the card-serving and validation paths, not the signing/verification canonicalization function.

[kuangmi-bit]

Independent data point from the Go side of this same defect family, because the fix here has a cross-SDK cost worth seeing before it lands.

I reproduced this on a third-party frozen card (the one from #445): gate_card_20260928.json, 9420 bytes, sha256 2df33ff1…, signed by the JS SDK with a production key, with the matching committed JWKS. Using a2a-python at 0d5473ca (the commit in your permalink), same card, no network needed — the JWKS is a file.

What _canonicalize_agent_card produces today on that card:

a2a-python @ 0d5473ca   6410 bytes   c5d5384a19f3a15c761ff93bf9fec892ec99615b6356d7675fda5b79286b59b1

That is byte-identical to what the JS SDK produces for the same card (canonicalizeAgentCard), and the JS-signed signature verifies against exactly those bytes. So the empty-removal + implicit-presence omission you are proposing to change is not incidental — it is the thing that makes Python and JS currently agree with each other.

The two steps you identify are both load-bearing for that. Splitting them out (same card, same commit):

MessageToDict(always_print=False) + _clean_empty  →  6410  c5d5384a…   (= today's output)
MessageToDict(always_print=True)  + no clean      →  6638  db15bd6c…   (rule-1 style)
MessageToDict(always_print=True)  + _clean_empty  →  6444  bf28623a…

So always_print_fields_with_no_presence=True alone moves the output 228 bytes away from the form the JS SDK signs. On this card those 228 bytes are exactly four leaves, and none of them is a REQUIRED field:

+ /capabilities/extensions/0/required = false
+ /capabilities/extensions/1/required = false
+ /supportedInterfaces/0/tenant = ""
+ /supportedInterfaces/1/tenant = ""

That is the part I would flag: rule 1 is about REQUIRED fields at their default value, but always_print_fields_with_no_presence prints every implicit-presence field, which overshoots the requirement and takes Python out of the JS agreement as a side effect. Scoping the change to actually-REQUIRED fields (so description: "" / skills: [] survive in the payload) keeps the rest of the form intact.

Note also that on this particular card the defect in #1278 does not manifest — description, name, version are non-empty and skills has 5 entries. That is presumably why JS and Python look aligned today, and it means the divergence only appears on cards where a REQUIRED field sits at its default: exactly the case your issue describes, and exactly the case that needs to be in whatever test lands.

Related threads, so the parts can be decided in one place rather than per SDK: #445 (Go: canonicalizing the served JSON as-is gives 6852 bytes and fails the JS signature; projecting through the message and dropping empty values gives 6410 and passes), A2A #2122 (§8.4.1 is under-determined about which form a new signature must use), and a2a-tck #245 (a rule-1 conformance corpus: R1-003/R1-004 isolate exactly the description: "" / skills: [] case — every REQUIRED field present except those two, so the competing resolutions differ in precisely them — plus a MUST-REJECT third reading). Whichever way the spec call goes, a single-SDK fix moves the break to that SDK's boundary instead of removing it — Python and JS agree today, Go does not.

Reproduction, if useful: a2a-python @ 0d5473ca, pip install -e ., load the card with ignore_unknown_fields=True (the card carries url, protocolVersion, preferredTransport, compensation, which this commit's proto does not have — url is rejected by a strict Parse), then call _canonicalize_agent_card and print len(utf8) + sha256. Same for the two variants. I did not run the JS SDK locally; the JS bytes there are the ones published in #445 and independently reconstructed in Go.

[aeoess]

@kuangmi-bit thanks, this is useful. Your result rules out always_print_fields_with_no_presence=True as a fix by itself. On that JS-signed card it adds four non-REQUIRED leaves and changes bytes that Python and JS currently agree on.

It does not rule out the descriptor-aware approach from the issue. The remaining question is Rule 1 itself. a2aproject/A2A#2122 is still deciding how REQUIRED fields at their default value should be represented, and a2aproject/a2a-tck#245 records the competing outcomes for description: "" and skills: [].

So I'd keep #1278 open, but not change Python's canonical bytes until that rule is settled. Once it is, the Python fix can preserve exactly the fields the chosen rule requires without pulling in unrelated implicit-presence defaults.

Thanks for catching the overshoot.