docs(spec): document multi-version surface updates and catalog protocol independence - #2375
Open
jacobsimionato wants to merge 5 commits into
Open
docs(spec): document multi-version surface updates and catalog protocol independence#2375jacobsimionato wants to merge 5 commits into
jacobsimionato wants to merge 5 commits into
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive proposal for the A2UI Protocol Versioning and Compatibility Plan, outlining independent wire protocol versions mapping to a universal in-memory representation. It also updates the protocol documentation to detail multi-version surface updates and catalog protocol independence. The review feedback highlights an inconsistency in the proposed JSON schema for renderer capabilities, suggesting the use of patternProperties to enforce version key patterns instead of additionalProperties.
nan-yu
reviewed
Aug 24, 2026
|
|
||
| #### Catalog protocol independence | ||
|
|
||
| Component catalogs are expressed as JSON catalog definition documents formatted according to a specific catalog description version (specified by `protocolVersion` in `catalog_definition.json`). However, the content of a catalog definition is not considered to be tied to a specific protocol version. A catalog originally configured for one protocol version (e.g., `v0.9`) can be targeted by wire messages expressed in a different protocol version (e.g., `v1.0`) without needing to redefine or duplicate the catalog for each protocol version upgrade. |
Collaborator
There was a problem hiding this comment.
What if a catalog references v0.9 common_types? It feels problematic to re-target the catalog to v1.0 protocol.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary & Rationale
Updates the A2UI v1.0 protocol specification (
specification/v1_0/docs/a2ui_protocol.md) to formally document core versioning and compatibility principles:v0.9) can be updated over its lifetime by messages expressed in a different protocol version (e.g.,v1.0). SDKs convert incoming wire payloads across versions into a universal internal state representation (SurfaceModel), enabling long-lived or single-surface views (such as dynamic dashboards) to evolve seamlessly across protocol upgrades.protocolVersionincatalog_definition.json), but once loaded into an SDK they are converted to a universal in-memory representation. This decouples catalog definitions from the wire message protocol version, allowing a catalog written for one protocol version (e.g.,v0.9) to be targeted by messages expressed in a different protocol version (e.g.,v1.0) without requiring re-definition for each protocol upgrade.Proposal doc: go/a2ui-versioning