A2UI VALIDATION GUIDE
How to validate A2UI JSON.
An A2UI payload is normally a stream of JSON objects. In the stable v0.9 protocol, each line represents one server-to-client message and contains a version plus exactly one message key. Validation therefore has two layers: determine whether each object matches its message shape, then determine whether the ordered stream makes sense as a whole.
1. Parse the wire format correctly
The message reference defines JSON Lines as the wire-friendly representation: one complete JSON object per line. A log collector may wrap those messages in a JSON array, while a debugging console may show a single object. A useful validator can accept all three formats without treating pretty-printed JSON as multiple protocol messages.
2. Check the envelope discriminator
A v0.9 server message must use exactly one of createSurface, updateComponents, updateDataModel, or deleteSurface. The official JSON Schema sets additionalProperties to false, so unrelated envelope keys are errors rather than harmless metadata. The stable schema requires "version": "v0.9".
3. Track the surface lifecycle
A surface must be created before it receives component or data-model updates. Creating the same active surfaceId twice is invalid. If the client receives deleteSurface, later updates to that ID need a new createSurface. This state cannot be verified by validating each line independently.
4. Reconstruct the component graph
Components are sent as a flat adjacency list. Their id fields identify nodes and container fields reference child IDs. The root convention uses the ID root. Forward references are expected during progressive rendering, so a validator should wait until the pasted stream ends before classifying a child as missing. Cycles and components unreachable from root are also worth reporting.
5. Validate data paths and the catalog
updateDataModel.path follows JSON Pointer conventions. An omitted path or / refers to the entire model; a more specific path begins with a slash. Component-specific fields come from the catalog selected by catalogId. A protocol validator can check common component identity and graph rules, but a deployment should also validate against the exact catalog schema used by its renderer.
Recommended validation loop
- Generate fixture messages without secrets or personal information.
- Run structural and lifecycle validation.
- Resolve remaining graph errors after the full progressive stream is available.
- Validate catalog-specific properties.
- Render in a test client and exercise bindings and actions.