fix(v0_9): resolve v0.9.1 payload compatibility gap (Issue #1749) by Varun-S10 · Pull Request #1973 · a2ui-project/a2ui

Varun-S10 · 2026-07-09T12:22:26Z

Description

This PR adds support for v0.9.1 protocol payloads in the v0_9 runtime across web_core, react, lit, and angular. Previously, the runtime rejected v0.9.1 messages because of hard-coded version strings and missing catalog aliases.

What changed:

Schemas & Types: Updated Zod validation and TypeScript types from "v0.9" to "v0.9" | "v0.9.1".
Catalog Resolution: Added an alias check in MessageProcessor so surfaces referencing the v0.9.1 basic catalog URL resolve correctly.
Package Exports: Added ./v0_9_1 package subpath exports to web_core, react, and lit.

This change is 100% backward compatible and does not affect any existing v0.9 features.

Fixes #1749

Pre-launch Checklist

One time:

I signed the CLA.
I read the Contributors Guide.
I read the Style Guide.
I have built and run at least one sample.

For this PR:

I have added updates to the CHANGELOG.
I updated/added relevant documentation.
My code changes (if any) have tests.
If my branch is on fork, I have verified that scripts/e2e_test.sh passes.

If you need help, consider asking for advice on the discussion board.

…ct#1749)

gemini-code-assist

Code Review

This pull request adds support for the v0.9.1 specification across the Angular, Lit, React, and Web Core renderers, including basic catalog alias resolution, Zod schema updates to accept both 'v0.9' and 'v0.9.1' versions, and package subpath exports. The feedback suggests improving the protocol version negotiation in MessageProcessor by advertising support for 'v0.9.1' in getClientCapabilities and dynamically returning the negotiated version in getClientDataModel instead of hardcoding 'v0.9'.

gemini-code-assist · 2026-07-09T12:25:49Z

    const capabilities: A2uiClientCapabilities = {
      'v0.9': {
-        supportedCatalogIds: this.catalogs.map(c => c.id),
+        supportedCatalogIds: this.catalogs.flatMap(c =>
+          c.aliases ? [c.id, ...c.aliases] : [c.id],
+        ),
      },
    };


To fully support v0.9.1 clients and servers, the getClientCapabilities method should also advertise support for the 'v0.9.1' protocol version in the returned capabilities object, rather than only advertising 'v0.9'. This ensures that v0.9.1 servers can correctly detect that the client supports this version during the capabilities exchange.

Suggested change

const capabilities: A2uiClientCapabilities = {

'v0.9': {

supportedCatalogIds: this.catalogs.map(c => c.id),

supportedCatalogIds: this.catalogs.flatMap(c =>

c.aliases ? [c.id, ...c.aliases] : [c.id],

),

},

};

const capabilities: Record<string, any> = {

'v0.9': {

supportedCatalogIds: this.catalogs.flatMap(c =>

c.aliases ? [c.id, ...c.aliases] : [c.id],

),

},

};

capabilities['v0.9.1'] = capabilities['v0.9'];

Yes, this would be needed.

gemini-code-assist · 2026-07-09T12:25:49Z

 export const A2uiClientDataModelSchema = z
  .object({
-    version: z.literal('v0.9'),
+    version: z.enum(['v0.9', 'v0.9.1']),


Since A2uiClientDataModelSchema now allows both 'v0.9' and 'v0.9.1' versions, we should ensure that getClientDataModel() in MessageProcessor returns the correct negotiated version dynamically instead of hardcoding 'v0.9'. This prevents potential validation failures on the server side when interacting with a v0.9.1 server.

You can implement this by tracking the version of the last processed message in MessageProcessor (e.g., via a private property updated in processMessage) and returning that version in getClientDataModel().

gspencergoog · 2026-07-09T15:03:18Z

+  /**
+   * An optional array of alias URLs for the catalog.
+   */
+  aliases?: readonly string[];


This isn't correct, since the v0_9_1 catalog and the v0_9 catalog are different and aren't interchangable. They aren't aliases for each other, and need to be treated separately.

gspencergoog · 2026-07-09T15:05:54Z

  id?: string;

+  /**
+   * An optional array of alias URLs for the catalog.


They're not necessarily URLs. They are often written that way, but they can be any string.

gspencergoog · 2026-07-09T15:06:44Z

    const capabilities: A2uiClientCapabilities = {
      'v0.9': {
-        supportedCatalogIds: this.catalogs.map(c => c.id),
+        supportedCatalogIds: this.catalogs.flatMap(c =>
+          c.aliases ? [c.id, ...c.aliases] : [c.id],
+        ),
      },
    };


Yes, this would be needed.

gspencergoog · 2026-07-09T15:08:25Z


 // `__dirname` will be `dist/src/v0_9/schema` when run via `node --test dist/**/*.test.js`
-const SPEC_DIR_V0_9 = resolve(__dirname, '../../../../../../specification/v0_9/json');
+const SPEC_DIR_V0_9 = resolve(__dirname, '../../../../../../specification/v0_9_1/json');


This effectively ignores the v0_9 directory. We should be testing them independently to make sure they are both still valid.

gspencergoog · 2026-07-09T15:09:44Z

      "types": "./dist/src/v0_9/basic_catalog/index.d.ts",
      "default": "./dist/src/v0_9/basic_catalog/index.js"
    },
+    "./v0_9_1": {


This treats the v0_9_1 catalog as if it were the v0_9 catalog. They do have differences, and so this should point to the v0_9_1 catalog.

Why are there differences in the v0.9 and 0.9.1 catalogs? I thought 0.9.1 was only to release the mimetype update?

Yeah, you're right, that's the only difference. Hmm. Maybe in this case the parsing of the catalogs is the same, but I'm thinking of it as "what if we release 0.9.2 and it has extra fields/components?" I don't see that happening for 0.9, but I'm pretty sure it will happen sometime soon, e.g. for v1.1.

I'm wary of just aliasing them like this becoming a pattern.

I really think we should hide/remove any actual implementation code for v0.9.1, and just make 0.9 accept both 0.9 and 0.9.1. The aliasing of the catalog id should be a one-time only thing because of the way 0.9.1 was made (that I guess can live in the v0.9 directory only). Maybe we can leave instructions for agents not to replicate that pattern later? :)

gspencergoog · 2026-07-09T15:12:11Z


-    super(id, components, functions);
+    const aliases = options.aliases ?? [
+      'https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json',


This is saying that if you have a v0_9 renderer you can render v0_9_1 content, and while that is often true (they are similar), where they are different, it will fail.

ditman · 2026-07-09T17:30:42Z

+    "./v0_9_1": {
+      "import": {
+        "types": "./dist/v0_9/index.d.ts",
+        "default": "./dist/v0_9/index.js"
+      },
+      "require": {
+        "types": "./dist/v0_9/index.d.cts",
+        "default": "./dist/v0_9/index.cjs"
+      }
+    },


/cc @gspencergoog for example, I would not recommend adding this alias. People should be importing from v0_9 only.

As we discussed before, IMO the versions of the protocols shouldn't necessarily map to the versions of the renderers.

Yes, I agree in this case that they are functionally the same unless you're using A2A. There is one other minor spec change besides the MIME change: in v0.9 the surfaceId had to be globally unique for the entire lifetime of the renderer, and in v0.9.1 it was relaxed so that the surfaceId only needs to be unique among currently active surfaces. But I think that's backward compatible by design.

I'm OK with just using 0.9 code for 0.9.1 (and 0.9) everywhere except A2A support, but we should probably restructure the spec itself so that there isn't duplication and so it makes it abundantly clear that this is a special case and not the norm. I'm pretty sure that from now on dot releases will contain additional features.

ditman · 2026-07-13T18:03:16Z

I took a stab at some of this here: #1993

fix(v0_9): resolve v0.9.1 payload compatibility gap (Issue a2ui-proje…

9577533

…ct#1749)

github-project-automation Bot added this to A2UI Jul 9, 2026

github-project-automation Bot moved this to Todo in A2UI Jul 9, 2026

gemini-code-assist Bot reviewed Jul 9, 2026

View reviewed changes

style(angular): format basic-catalog.ts with prettier

d911a8c

Varun-S10 mentioned this pull request Jul 9, 2026

a2ui/react: v0.9.1 payload compatibility gap in v0_9 runtime #1749

Closed

gspencergoog reviewed Jul 9, 2026

View reviewed changes

ditman reviewed Jul 9, 2026

View reviewed changes

ditman mentioned this pull request Jul 13, 2026

feat(web_core): Parse both v0.9 and v0.9.1 messages. #1993

Merged

8 tasks

Uh oh!

Conversation

Varun-S10 commented Jul 9, 2026

Description

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ditman commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants