[Feat]: Schema Contract Extension for A2A payloads

### Is your feature request related to a problem? Please describe.

A2A agents can advertise supported representations through inputModes, outputModes, and acceptedOutputModes, but there is no standard mechanism for associating those media types with machine-readable schemas.
For example, application/json tells a client that the representation is JSON, but not:
- what structure the JSON must have;
- where its schema is located;
- which schema language or dialect applies;
- which input and output schemas form one interaction contract;
- how to distinguish multiple contracts that use the same media type;
- when input and output validation must occur; or
- how contract-validation failures should be reported.
Vendor-specific media types provide stronger semantic identity, but A2A still has no convention for locating their schemas or associating input and output representations.
Consequently, clients and servers implement application-specific discovery, serialization, and validation behavior. Provider-native structured-output features can improve model generation, but they are provider-specific and do not establish an interoperable A2A boundary contract.
This proposal is related to:
- #1776, which identifies the gap between media-mode negotiation, schema advertisement, and SDK-native type dispatch.
- Discussion #400, which raises the need for structured task output without encoding structured data inside text and parsing it again.

### Describe the solution you'd like

I propose an A2A Schema Contract Extension that provides
provider-neutral discovery, selection, and validation semantics for application payloads.

The current community draft is available at:

https://github.com/shashikanth-gs/a2a-schema-contract

An agent advertises the extension through
AgentCapabilities.extensions. Its extension parameters contain
either an inline contract catalog or a reference to an external catalog.

Each contract contains:

• an immutable, versioned contract ID;


• optional descriptive associations with Agent Card skill IDs;


• an independent input direction;


• an independent output direction; and


• one or more alternative representations for directions that allow a payload.

Each direction declares one of three presence semantics:

• 
  required — Exactly one primary application
  payload is required.
  


• 
  optional — Zero or one primary application
  payload may be present.
  


• 
  none — The contract defines no primary
  application payload.
  

Every representation has a media type. A validation schema is optional,
allowing structured and schemaless interactions to use the same model.

This supports combinations such as:

• plain text input → schema-constrained JSON output;


• schema-constrained JSON input → plain text output;


• no application input → structured output;


• structured input → no output Artifact;


• optional text input → optional structured output; and


• completely schemaless text, binary, or media interactions.

A schema descriptor can use:

1. an inline schema;


2. an external schema document; or


3. 
   an integrity-pinned external bundle for large JSON Schema graphs or XSD
   include/import families.
   

The representation media type, schema-document media type, schema dialect,
contract ID, and extension URI remain separate identifiers.

The client activates the extension using the normal A2A extension-negotiation
mechanism. Namespaced invocation metadata selects the contract, input
representation, and acceptable output representations. The selected output
must also be compatible with normal A2A media-mode negotiation.

One explicitly identified primary Part is validated. Other text, media, or
citation Parts can remain companion Parts without being accidentally selected
based only on their media type.

For schema-constrained input, validation occurs before model execution, tool
execution, business side effects, or other externally visible processing.

For schema-constrained output, validation occurs before publishing a
successful result. Provider-native structured-output APIs may assist
generation, but final boundary validation remains required.

Validation must not silently coerce types, remove properties, or insert
defaults. Invalid generated output must not be published as a successful
contracted result.

The extension does not modify A2A core structures or enums. It uses existing
extension declarations, activation, media modes, Parts, Tasks, Artifacts, and
namespaced metadata.

The initial draft also defines security requirements for remote schema
resolution, including SSRF prevention, redirect and address validation,
integrity verification, resource limits, cycle detection, safe archive
processing, XML external-entity protection, and sanitized validation errors.

At this stage, I am requesting:

• feedback on the problem statement and scope;


• review of the proposed semantic model;


• guidance on overlap with existing or planned A2A work;


• feedback from A2A SDK maintainers; and


• 
  if appropriate, guidance on seeking maintainer sponsorship for an
  experimental extension.
  

I am not requesting official status for the current draft. Breaking changes
are expected following community review.

### Describe alternatives you've considered

**Plain application/json**

Applications can exchange JSON and agree on its structure out of band. This works within one integration but is not self-describing through A2A discovery and requires custom validation and serialization logic.

**Vendor-specific media types**

Vendor media types provide semantic identity, but media types alone do not define an A2A convention for locating schemas, pairing input and output contracts, or selecting between multiple contracts.

**Embedding all schemas directly in Agent Cards**

This is practical for small schemas but unsuitable for large schemas such as IATA messages, multi-file XSD families, or JSON Schema graphs with external resources. The proposal therefore supports inline and referenced schemas.

**Provider-native structured output**

Claude, OpenAI, Copilot, and other providers expose different structured-output capabilities and schema subsets. These features are useful implementation mechanisms but cannot provide a provider-neutral A2A contract by themselves.

**Tool or function calling**

A tool call models an internal or delegated operation. It does not necessarily describe the application payload exchanged between independent A2A peers or the final Artifact produced by a Task.

**Changing A2A core**

Schema contracts could eventually become a core feature, but an extension allows the semantics to be tested without changing existing A2A structures or requiring immediate support from every implementation.

**SDK-only type registries**

SDKs may map media types or contract IDs to Pydantic models, TypeScript types, Go structs, or similar native types. This is useful, but SDK dispatch first requires a provider-neutral discovery and contract layer. SDK-native type mapping is therefore considered implementation guidance rather than the normative base extension.

### Additional context

Community draft and supporting artifacts:

- Repository: https://github.com/shashikanth-gs/a2a-schema-contract
- Draft specification: https://github.com/shashikanth-gs/a2a-schema-contract/blob/v0.1.0-draft.1/spec/specification.md
- Extension-owned JSON Schemas: https://github.com/shashikanth-gs/a2a-schema-contract/tree/v0.1.0-draft.1/schema
- Examples: https://github.com/shashikanth-gs/a2a-schema-contract/tree/v0.1.0-draft.1/examples
- Initial conformance cases: https://github.com/shashikanth-gs/a2a-schema-contract/tree/v0.1.0-draft.1/conformance
- W3ID registration: https://github.com/perma-id/w3id.org/pull/6601
- Related issue: #1776
- Related discussion: https://github.com/a2aproject/A2A/discussions/400

The current release is v0.1.0-draft.1. It is an independent community draft and is not an official or experimental A2A extension.

The draft uses a versioned /draft/0.1 identifier. The stable /v1 namespace is intentionally reserved until the semantics are declared stable.

A TypeScript reference implementation is planned first, followed by an independent Python implementation.

Feedback would be particularly helpful on:

1. Whether discovery and validation should be one extension or separate profiles.
2. Whether external schema bundles belong in the base extension.
3. Whether optional output is interoperable across current A2A SDKs.
4. Whether explicit primary-Part metadata is preferable to media-type-only selection.
5. Whether contract selection should always be explicit or may be inferred when unambiguous.
6. Whether a minimum JSON Schema vocabulary profile should be defined.
7. How much SDK-native type dispatch belongs in the extension versus SDK guidance.
8. Whether multipart contracts should be addressed now or deferred.
9. Whether the proposed no-application-payload semantics align with intended A2A Task and Message behavior.
10. Whether this should remain a community extension, proceed toward an experimental extension, or inform a future core capability.

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct