---
schema_version: "1"
id: 2a8cb74a6157d58af90b400327461a32b2d94ea947fb1fbec43f9ce72041b28f
title: A2A v1 Schema Validation Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-schema-validation.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-schema-validation
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 45c910ec7e7f2616be8ba8d62994c01fa6805e1f9a929ba6297ad3251203905a
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Verifies that requests to the agent are compliant with the A2A v1.0 specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-schema-validation-release-notes">A2A v1 Schema Validation Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request: Invalid request parameters or malformed JSON</p></td></tr><tr><td><p>404 - Not Found: Unknown or invalid method name</p></td></tr></tbody></table>

## Summary

The A2A v1 Schema Validation policy validates incoming requests against the A2A v1.0 specification
across all three supported transports: JSON-RPC, HTTP+JSON, and gRPC. The policy rejects requests
that don’t comply with the strict structural validation rules defined in the A2A v1.0 specification.
Valid requests flow through unchanged.

The policy performs the following validations:

- **JSON-RPC**: Validates the JSON-RPC 2.0 envelope structure and that method names use the
  PascalCase format specified in A2A v1.0 (for example, `SendMessage`, `GetTask`). Request bodies
  are deserialized against the matching request schema.

- **HTTP+JSON**: Validates that URLs match A2A v1.0 HTTP+JSON routes and that request bodies conform
  to the schema for the matched route.

- **gRPC**: Validates that the protobuf payload decodes successfully against the A2A v1.0 gRPC
  service definition.

When validation fails, the policy returns an error response with the appropriate HTTP status code in
the same transport format as the request.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. If you need to support pre-v1.0 agents,
> use the [A2A Schema Validation](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-schema-validation) policy instead. Do not
> apply both policies to the same agent.

### When to Use This Policy

Apply this policy when:

- You want to enforce strict compliance with the A2A v1.0 specification at the gateway level.

- You need to protect backend agents from malformed or invalid requests.

- You want consistent validation across JSON-RPC, HTTP+JSON, and gRPC transports.

- You need to return validation errors before requests reach backend services.

## Transport-Specific Validation

The policy handles each transport differently:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Transport</th><th>Detection Criteria</th><th>Validation Behavior</th></tr></thead><tbody><tr><td><div><div><p>JSON-RPC</p></div></div></td><td><div><div><p><code>POST</code> request with JSON-RPC 2.0 envelope (<code>{"jsonrpc":"2.0", …​}</code>)</p></div></div></td><td><div><div><p>Validates PascalCase method names (A2A v1.0 §9.1) when tagged with <code>a2a-version: 1.0</code>.<br><br>v0.3 path-style method names are rejected with error code <code>-32601</code> (Method not found).<br><br>Request body is deserialized against the matching request schema with strict validation.</p></div></div></td></tr><tr><td><div><div><p>HTTP+JSON</p></div></div></td><td><div><div><p>URL matches an A2A v1.0 HTTP+JSON route</p></div></div></td><td><div><div><p>Performs route lookup and validates the request body schema.<br><br>Path-bound parameters (like <code>id</code> in <code>:cancel</code> or <code>:subscribe</code> routes) are validated.<br><br>Requests tagged as v1 that don’t match a known route are rejected with HTTP 404.</p></div></div></td></tr><tr><td><div><div><p>gRPC</p></div></div></td><td><div><div><p><code>content-type: application/grpc</code> with path <code>/a2a.A2AService/&lt;RPC&gt;</code></p></div></div></td><td><div><div><p>Decodes the protobuf payload against the A2A v1.0 gRPC service definition.<br><br>Successful decode confirms schema compliance.</p></div></div></td></tr><tr><td><div><div><p>Other traffic</p></div></div></td><td><div><div><p>Doesn’t match any A2A transport pattern</p></div></div></td><td><div><div><p>Passes through without validation.</p></div></div></td></tr></tbody></table>

## Error Responses

When validation fails, the policy returns errors in the request’s transport format:

- **JSON-RPC InvalidParams** (HTTP 400): Returns error code `-32602` with `ErrorInfo` details

- **JSON-RPC ParseError** (HTTP 400): Returns error code `-32700` when JSON decode fails

- **JSON-RPC MethodNotFound** (HTTP 404): Returns error code `-32601` for unknown or invalid method
  names

- **HTTP+JSON errors**: Returns the same error structure wrapped in a `google.rpc.Status` envelope
  (A2A v1.0 §11.5)

- **gRPC errors**: Returns HTTP 200 with `grpc-status` header (`3` for INVALID\_ARGUMENT, `12` for
  UNIMPLEMENTED) and `grpc-message` header with error details

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Schema Validation policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

This policy has no configurable parameters.

## Example Validation Errors

### Invalid JSON-RPC Method Name

Request with v0.3-style path method name:

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "/send-message",
  "params": {...}
}
```

Response (HTTP 404):

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "METHOD_NOT_FOUND",
        "metadata": {
          "detail": "Invalid methods: `/send-message`. Valid Methods: SendMessage, GetTask, ..."
        }
      }
    ]
  }
}
```

### Invalid Request Parameters

Request with missing required field:

```json
{
  "jsonrpc": "2.0",
  "id": "456",
  "method": "SendMessage",
  "params": {
    "message": {}
  }
}
```

Response (HTTP 400):

```json
{
  "jsonrpc": "2.0",
  "id": "456",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "INVALID_PARAMS",
        "metadata": {
          "detail": "missing field `text`"
        }
      }
    ]
  }
}
```