Skip to content
Putting technology to work.
Insights to guide decisions and action.

Search articles

Migrating to A2UI v1.0: validating theme and @-prefixed keys with the schema

Table of contents · 7 items

If you are prototyping a feature in which an AI agent displays input forms or confirmation cards in an internal help desk or request screen, the question becomes which version of the specification to validate the agent's output against. If the JSON the agent returns differs from the shape the UI-side rendering library expects, you get bugs such as components not appearing or entered values not reaching the agent.

A2UI (Agent-to-User Interface) is an open-source framework in which agents send UI components as data (JSON) rather than code, and the app-side rendering library (the renderer) displays them using its own components. Version 1.0 of the specification (status: "Current") includes incompatible changes from v0.9. This article summarizes the key points of the official migration guide and the results of actually validating messages against the specification's JSON Schema.

A2UI basics

The README of the repository (a2ui-project/a2ui) describes A2UI as an "open-source generative UI framework" and cites, as a use case, agents that are remote or third-party and cross trust boundaries. It says "A2UI expresses UI using data, not code." The components an agent can use are defined by a catalog (a list of components and their specifications), and their shape is constrained by the schema.

In the v1.0 specification, the basic messages from the agent to the UI are createSurface (create a display surface), updateComponents (add or update components), updateDataModel (update data) and deleteSurface (delete). v1.0 adds bidirectional function calls (callRendererFunction, callAgentFunction and their respective responses).

What needs rewriting from v0.9

The main changes affecting agent output, taken from the "Migration guide" in the migration guide (evolution_guide.md), are as follows.

Changev0.9v1.0
Message version"version": "v0.9""version": "1.0"
Stylingtheme in createSurface (such as primaryColor)Removed. Appearance is left to the rendering side's components
Common component fieldsaccessibility・checks@accessibility, @checks (@catalogId and @metadata added)
Deleting datavalue could be omittedvalue is required. Deletion requires an explicit null
MIME typeapplication/json+a2uiapplication/a2ui+json

In addition, validationRegexp in TextField was removed and replaced by the @checks and regex functions, and value in TextField became required. The openUrl function is treated as requiring user interaction (requiresUserActivation: true). On November 19, the migration guide was updated to note that headings h1 to h5 had been removed from variant in Text, leaving only caption and body. Headings are written in Text.text Markdown (such as ## 見出し). When we checked on November 20, components using "variant": "h2" were rejected by both the main schema and the 0.15.0 bundled schema discussed in the next section. If you build your own catalog, you need to specify "protocolVersion": "1.0", and the guide states "Catalogs authored for v0.9 cannot be used directly with v1.0 protocol runtimes."

There is a caution about how to apply @. The guide warns, "Do not migrate v0.9 payloads with a blanket find-and-replace of "path": → "@path":." @ is added only at data binding (DataBinding) and function call positions, and to the common fields directly under a component. It is not added to path in updateDataModel or to path in list templates.

Results of schema validation

On November 14, 2026, we loaded the specification's JSON Schema (agent_to_renderer.json and common_types.json fetched from the repository's main branch, plus the basic catalog catalogs/basic/v1/catalog.json) into ajv 8.20 (JSON Schema 2020-12) and validated seven messages, running on Node.js 22.23.4. On November 20, we fetched the main schema again and validated the same seven messages (Node.js 22.23.5, ajv 8.20.0), confirming that the results had not changed.

INVALID  A: v0.9の形のまま(version "v0.9"・theme あり)
INVALID  B: version だけ "1.0" にして theme を残す   ← theme が追加の項目として拒否
valid    C: theme を外し、部品とデータを createSurface の1通に入れる
INVALID  D: updateDataModel で value を省く           ← value が必須
valid    E: updateDataModel で value: null(削除)
INVALID  F: 部品に v0.9 の書き方の accessibility    ← 評価されない項目として拒否
valid    G: 部品に v1.0 の書き方の @accessibility

Output in which only the version number has been rewritten, as in B, fails strict validation. The specification states, "A createSurface carrying theme fails strict validation; relaxed renderers drop it." With lenient rendering libraries, theme may simply be discarded silently without an error. This creates a gap where output passes in tests but fails in environments with stricter validation.

Validation results against the A2UI v1.0 schema. A v0.9-style message, one with only version changed to 1.0 and theme left in, an updateDataModel with value omitted, and accessibility without @ were rejected by the specification's main schema. A message with theme removed and components and data in one message, deletion with value: null, and @accessibility passed. With the schema bundled in @a2ui/web_core 0.15.0 on npm, the verdicts for accessibility and @accessibility were reversed

Differences from the schema bundled with distributed libraries

We also validated the same seven messages against the v1.0 schema (src/v1_0/schemas/) bundled with @a2ui/web_core 0.15.0 (released November 2, 2026), distributed on npm. A to E gave the same results, but F and G were reversed. With the 0.15.0 bundled schema, accessibility without @ passes and @accessibility is rejected. The bundled common_types.json defines "accessibility" but has no definitions for @accessibility, @checks, @catalogId or @metadata.

The migration guide's "Component envelope mixin keys" section describes the move to @-prefixed keys as a change from "early v1.0 drafts." According to the repository history, the change that switched the specification and SDKs to @-prefixed keys ("feat!: emit @-prefixed v1.0 component envelope keys across spec and SDKs") landed on November 11, after the release of 0.15.0 (November 2). The 0.15.0 bundled schema appears to reflect the content before this change. For the transition period, the guide says rendering libraries and the Core SDK will accept old keys without @ if the component schema has no field of the same name, will reject components that have both, and that the agent-side SDK outputs only @-prefixed keys. We did not check the actual behavior of rendering libraries this time.

On the agent side, the release notes for a2ui-agent-sdk 0.12.0 for Python (released November 17) announce a BREAKING CHANGE that outputs @catalogId, @metadata, @accessibility and @checks on v1.0 components. If you validate output from an agent using the updated SDK against the 0.15.0 bundled schema, @accessibility will be rejected, just as in G.

The latest versions of @a2ui/react and @a2ui/lit for React and Lit are also 0.15.0 (released November 2), and @a2ui/angular for Angular is at 0.14.0. Proceed on the assumption that there is a gap between the specification's main branch and the versions of the distributed libraries.

How to approach the migration (editorial suggestion)

  1. Match the schema used for validation to the rendering library version. If you validate agent output in CI, use the schema bundled with the rendering library version you use in production. Validating against the specification's main schema can produce the opposite verdict from your production rendering library, as with F and G here. When updating the agent-side SDK (such as a2ui-agent-sdk 0.12.0), also validate in combination with the rendering library version.
  2. Update agent instructions and catalogs at the same time. If your instructions to the model (prompts) include catalogs or output examples, remove examples containing theme or lacking @, and replace them with v1.0 examples. Output with only the version number changed is rejected, as in B.
  3. Do not use bulk replacement. Replacing "path": with "@path": in bulk also changes path in updateDataModel. Compare against the migration guide's list of target positions and fix things while passing validation.
  4. Check how data deletion is written. Processing that deleted data by omitting value in updateDataModel should be changed to value: null.

We covered aligning the shapes of AI agent components and tool inputs and outputs across languages in our article on Google ADK's support for five languages, and how to verify the effect of skills given to agents in our article on evaluating agent skills.

Scope of verification

On November 14, 2026, we fetched and reviewed the README, specification (specification/v1_0/docs/a2ui_protocol.md), migration guide (specification/v1_0/docs/evolution_guide.md) and JSON Schema (specification/v1_0/json/ and catalogs/basic/v1/catalog.json) of a2ui-project/a2ui from main (desk research). We also fetched @a2ui/web_core 0.15.0 from npm and validated seven messages with ajv 8.20 against both the bundled schema and the main schema (Node.js 22.23.4). We did not check rendering in a rendering library, output from the agent SDK, or output generated by a model. On November 20, we redid validation against the main schema and checked the migration guide update (November 19), GitHub releases (such as a2ui-agent-sdk 0.12.0), the latest npm versions (@a2ui/web_core, @a2ui/react and @a2ui/lit at 0.15.0, @a2ui/angular still at 0.14.0) and the official site (a2ui.org). The official site shows v1.0 as "Current," but we have not found an announcement of the v1.0 release date.

GleamHub’s development, AI and automation consulting covers designing how AI agents fit into your internal business screens and building ways to verify their output. Please reach out through our contact form.

References

Share this articleXFacebook
Kakeru Suzuki

Fascinated by the possibilities of technology, has had a deep interest in programming and digital art since student days

Turn this article's theme into your company's next step

Concrete steps forward for your organization.

We organize your desired architecture, legacy systems, and operational requirements to formulate your next steps toward execution.

  • Desired architecture
  • Integration with existing environments
  • Operational requirements
Consult on development & operations initiatives

You can consult with us from the initial conceptual stage. Details from this article will be carried over to the inquiry form.

Receive the latest articles by email