Add version fields (google#581)

Author: gspencergoog

specification/v0_9/docs/a2ui_extension_specification.md

@@ -89,12 +89,14 @@ Example DataPart:
 {
   "data": [
     {
+      "version": "v0.9",
       "createSurface": {
         "surfaceId": "example_surface",
         "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json"
       }
     },
     {
+      "version": "v0.9",
       "updateComponents": {
         "surfaceId": "example_surface",
         "components": [
@@ -125,6 +127,7 @@ Example `action` DataPart:
 {
   "data": [
     {
+      "version": "v0.9",
       "action": {
         "name": "submit_form",
         "surfaceId": "contact_form_1",

specification/v0_9/docs/a2ui_protocol.md

@@ -189,6 +189,7 @@ This message signals the client to create a new surface and begin rendering it.
 
 ```json
 {
+  "version": "v0.9",
   "createSurface": {
     "surfaceId": "user_profile_card",
     "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
@@ -213,6 +214,7 @@ This message provides a list of UI components to be added to or updated within a
 
 ```json
 {
+  "version": "v0.9",
   "updateComponents": {
     "surfaceId": "user_profile_card",
     "components": [
@@ -250,6 +252,7 @@ This message is used to send or update the data that populates the UI components
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "user_profile_card",
     "path": "/user/name",
@@ -270,6 +273,7 @@ This message instructs the client to remove a surface and all its associated com
 
 ```json
 {
+  "version": "v0.9",
   "deleteSurface": {
     "surfaceId": "user_profile_card"
   }
@@ -281,10 +285,10 @@ This message instructs the client to remove a surface and all its associated com
 The following example demonstrates a complete interaction to render a Contact Form, expressed as a JSONL stream.
 
 ```jsonl
-{"createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.org/specification/v0_9/standard_catalog.json"}}
-{"updateComponents":{"surfaceId":"contact_form_1","components":[{"id":"root","component":"Card","child":"form_container"},{"id":"form_container","component":"Column","children":["header_row","name_row","email_group","phone_group","pref_group","divider_1","newsletter_checkbox","submit_button"],"justify":"start","align":"stretch"},{"id":"header_row","component":"Row","children":["header_icon","header_text"],"align":"center"},{"id":"header_icon","component":"Icon","name":"mail"},{"id":"header_text","component":"Text","text":"# Contact Us","variant":"h2"},{"id":"name_row","component":"Row","children":["first_name_group","last_name_group"],"justify":"spaceBetween"},{"id":"first_name_group","component":"Column","children":["first_name_label","first_name_field"],"weight":1},{"id":"first_name_label","component":"Text","text":"First Name","variant":"caption"},{"id":"first_name_field","component":"TextField","label":"First Name","value":{"path":"/contact/firstName"},"variant":"shortText"},{"id":"last_name_group","component":"Column","children":["last_name_label","last_name_field"],"weight":1},{"id":"last_name_label","component":"Text","text":"Last Name","variant":"caption"},{"id":"last_name_field","component":"TextField","label":"Last Name","value":{"path":"/contact/lastName"},"variant":"shortText"},{"id":"email_group","component":"Column","children":["email_label","email_field"]},{"id":"email_label","component":"Text","text":"Email Address","variant":"caption"},{"id":"email_field","component":"TextField","label":"Email","value":{"path":"/contact/email"},"variant":"shortText","checks":[{"call":"required","args":{"value":{"path":"/contact/email"}},"message":"Email is required."},{"call":"email","args":{"value":{"path":"/contact/email"}},"message":"Please enter a valid email address."}]},{"id":"phone_group","component":"Column","children":["phone_label","phone_field"]},{"id":"phone_label","component":"Text","text":"Phone Number","variant":"caption"},{"id":"phone_field","component":"TextField","label":"Phone","value":{"path":"/contact/phone"},"variant":"shortText","checks":[{"call":"regex","args":{"value":{"path":"/contact/phone"},"pattern":"^\\d{10}$"},"message":"Phone number must be 10 digits."}]},{"id":"pref_group","component":"Column","children":["pref_label","pref_picker"]},{"id":"pref_label","component":"Text","text":"Preferred Contact Method","variant":"caption"},{"id":"pref_picker","component":"ChoicePicker","variant":"mutuallyExclusive","options":[{"label":"Email","value":"email"},{"label":"Phone","value":"phone"},{"label":"SMS","value":"sms"}],"value":{"path":"/contact/preference"}},{"id":"divider_1","component":"Divider","axis":"horizontal"},{"id":"newsletter_checkbox","component":"CheckBox","label":"Subscribe to our newsletter","value":{"path":"/contact/subscribe"}},{"id":"submit_button_label","component":"Text","text":"Send Message"},{"id":"submit_button","component":"Button","child":"submit_button_label","variant":"primary","action":{"event":{"name":"submitContactForm","context":{"formId":"contact_form_1","clientTime":{"call":"now","args":{},"returnType":"string"},"isNewsletterSubscribed":{"path":"/contact/subscribe"}}}}}]}}
-{"updateDataModel":{"surfaceId":"contact_form_1","path":"/contact","value":{"firstName":"John","lastName":"Doe","email":"john.doe@example.com","phone":"1234567890","preference":["email"],"subscribe":true}}}
-{"deleteSurface":{"surfaceId":"contact_form_1"}}
+{"version": "v0.9", "createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.org/specification/v0_9/standard_catalog.json"}}
+{"version": "v0.9", "updateComponents":{"surfaceId":"contact_form_1","components":[{"id":"root","component":"Card","child":"form_container"},{"id":"form_container","component":"Column","children":["header_row","name_row","email_group","phone_group","pref_group","divider_1","newsletter_checkbox","submit_button"],"justify":"start","align":"stretch"},{"id":"header_row","component":"Row","children":["header_icon","header_text"],"align":"center"},{"id":"header_icon","component":"Icon","name":"mail"},{"id":"header_text","component":"Text","text":"# Contact Us","variant":"h2"},{"id":"name_row","component":"Row","children":["first_name_group","last_name_group"],"justify":"spaceBetween"},{"id":"first_name_group","component":"Column","children":["first_name_label","first_name_field"],"weight":1},{"id":"first_name_label","component":"Text","text":"First Name","variant":"caption"},{"id":"first_name_field","component":"TextField","label":"First Name","value":{"path":"/contact/firstName"},"variant":"shortText"},{"id":"last_name_group","component":"Column","children":["last_name_label","last_name_field"],"weight":1},{"id":"last_name_label","component":"Text","text":"Last Name","variant":"caption"},{"id":"last_name_field","component":"TextField","label":"Last Name","value":{"path":"/contact/lastName"},"variant":"shortText"},{"id":"email_group","component":"Column","children":["email_label","email_field"]},{"id":"email_label","component":"Text","text":"Email Address","variant":"caption"},{"id":"email_field","component":"TextField","label":"Email","value":{"path":"/contact/email"},"variant":"shortText","checks":[{"call":"required","args":{"value":{"path":"/contact/email"}},"message":"Email is required."},{"call":"email","args":{"value":{"path":"/contact/email"}},"message":"Please enter a valid email address."}]},{"id":"phone_group","component":"Column","children":["phone_label","phone_field"]},{"id":"phone_label","component":"Text","text":"Phone Number","variant":"caption"},{"id":"phone_field","component":"TextField","label":"Phone","value":{"path":"/contact/phone"},"variant":"shortText","checks":[{"call":"regex","args":{"value":{"path":"/contact/phone"},"pattern":"^\\d{10}$"},"message":"Phone number must be 10 digits."}]},{"id":"pref_group","component":"Column","children":["pref_label","pref_picker"]},{"id":"pref_label","component":"Text","text":"Preferred Contact Method","variant":"caption"},{"id":"pref_picker","component":"ChoicePicker","variant":"mutuallyExclusive","options":[{"label":"Email","value":"email"},{"label":"Phone","value":"phone"},{"label":"SMS","value":"sms"}],"value":{"path":"/contact/preference"}},{"id":"divider_1","component":"Divider","axis":"horizontal"},{"id":"newsletter_checkbox","component":"CheckBox","label":"Subscribe to our newsletter","value":{"path":"/contact/subscribe"}},{"id":"submit_button_label","component":"Text","text":"Send Message"},{"id":"submit_button","component":"Button","child":"submit_button_label","variant":"primary","action":{"event":{"name":"submitContactForm","context":{"formId":"contact_form_1","clientTime":{"call":"now","args":{},"returnType":"string"},"isNewsletterSubscribed":{"path":"/contact/subscribe"}}}}}]}}
+{"version": "v0.9", "updateDataModel":{"surfaceId":"contact_form_1","path":"/contact","value":{"firstName":"John","lastName":"Doe","email":"john.doe@example.com","phone":"1234567890","preference":["email"],"subscribe":true}}}
+{"version": "v0.9", "deleteSurface":{"surfaceId":"contact_form_1"}}
 ```
 
 ## Component model
@@ -531,6 +535,7 @@ _Update a specific field:_
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "surface_123",
     "path": "/user/firstName",
@@ -543,6 +548,7 @@ _Remove a field:_
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "surface_123",
     "path": "/user/tempData"
@@ -554,6 +560,7 @@ _Replace the entire data model:_
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "surface_123",
     "value": {

specification/v0_9/docs/evolution_guide.md

@@ -103,6 +103,7 @@ Version 0.9 represents a fundamental philosophical shift from "Structured Output
 
 ```json
 {
+  "version": "v0.9",
   "createSurface": {
     "surfaceId": "user_profile_card",
     "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
@@ -155,6 +156,7 @@ Specifying an unknown surfaceId will cause an error. It is recommended that clie
 
 ```json
 {
+  "version": "v0.9",
   "updateComponents": {
     "surfaceId": "main",
     "components": [

specification/v0_9/eval/src/generation_flow.ts

@@ -56,6 +56,7 @@ Standard Instructions:
 13. Do NOT use a 'style' property. Use standard properties like 'align', 'justify', 'variant', etc.
 14. Do NOT invent properties that are not in the schema. Check the 'properties' list for each component type.
 15. Use 'checks' property for validation rules if required.
+16. EVERY message object MUST include the property "version": "v0.9" at the top level.
 ${catalogRules ? `\nInstructions specific to this catalog:\n${catalogRules}` : ""}
 
 Schemas:

specification/v0_9/json/a2ui_client_capabilities.json

@@ -5,18 +5,25 @@
   "description": "A schema for the a2uiClientCapabilities object, which is sent from the client to the server as part of the A2A metadata to describe the client's UI rendering capabilities.",
   "type": "object",
   "properties": {
-    "supportedCatalogIds": {
-      "type": "array",
-      "description": "The URI of each of the component and function catalogs that is supported by the client.",
-      "items": { "type": "string" }
-    },
-    "inlineCatalogs": {
-      "type": "array",
-      "description": "An array of inline catalog definitions, which can contain both components and functions. This should only be provided if the agent declares 'acceptsInlineCatalogs: true' in its capabilities.",
-      "items": { "$ref": "#/$defs/Catalog" }
+    "v0.9": {
+      "type": "object",
+      "description": "The capabilities structure for version 0.9 of the A2UI protocol.",
+      "properties": {
+        "supportedCatalogIds": {
+          "type": "array",
+          "description": "The URI of each of the component and function catalogs that is supported by the client.",
+          "items": { "type": "string" }
+        },
+        "inlineCatalogs": {
+          "type": "array",
+          "description": "An array of inline catalog definitions, which can contain both components and functions. This should only be provided if the agent declares 'acceptsInlineCatalogs: true' in its capabilities.",
+          "items": { "$ref": "#/$defs/Catalog" }
+        }
+      },
+      "required": ["supportedCatalogIds"]
     }
   },
-  "required": ["supportedCatalogIds"],
+  "required": ["v0.9"],
   "$defs": {
     "FunctionDefinition": {
       "type": "object",

specification/v0_9/json/a2ui_client_data_model.json

@@ -5,6 +5,9 @@
   "description": "Schema for attaching the client data model to A2A message metadata. This object should be placed in the `a2uiClientDataModel` field of the metadata.",
   "type": "object",
   "properties": {
+    "version": {
+      "const": "v0.9"
+    },
     "surfaces": {
       "type": "object",
       "description": "A map of surface IDs to their current data models.",
@@ -14,6 +17,6 @@
       }
     }
   },
-  "required": ["surfaces"],
+  "required": ["version", "surfaces"],
   "additionalProperties": false
 }

specification/v0_9/json/client_to_server.json

@@ -2,9 +2,12 @@
   "title": "A2UI (Agent to UI) Client-to-Server Event Schema",
   "description": "Describes a JSON payload for a client-to-server event message.",
   "type": "object",
-  "minProperties": 1,
-  "maxProperties": 1,
+  "minProperties": 2,
+  "maxProperties": 2,
   "properties": {
+    "version": {
+      "const": "v0.9"
+    },
     "action": {
       "type": "object",
       "description": "Reports a user-initiated action from a component.",
@@ -92,10 +95,10 @@
   },
   "oneOf": [
     {
-      "required": ["action"]
+      "required": ["action", "version"]
     },
     {
-      "required": ["error"]
+      "required": ["error", "version"]
     }
   ]
 }

specification/v0_9/json/server_to_client.json

@@ -14,6 +14,9 @@
     "CreateSurfaceMessage": {
       "type": "object",
       "properties": {
+        "version": {
+          "const": "v0.9"
+        },
         "createSurface": {
           "type": "object",
           "description": "Signals the client to create a new surface and begin rendering it. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.",
@@ -40,12 +43,15 @@
           "additionalProperties": false
         }
       },
-      "required": ["createSurface"],
+      "required": ["createSurface", "version"],
       "additionalProperties": false
     },
     "UpdateComponentsMessage": {
       "type": "object",
       "properties": {
+        "version": {
+          "const": "v0.9"
+        },
         "updateComponents": {
           "type": "object",
           "description": "Updates a surface with a new set of components. This message can be sent multiple times to update the component tree of an existing surface. One of the components in one of the components lists MUST have an 'id' of 'root' to serve as the root of the component tree. The createSurface message MUST have been previously sent with the 'catalogId' that is in this message.",
@@ -68,12 +74,15 @@
           "additionalProperties": false
         }
       },
-      "required": ["updateComponents"],
+      "required": ["updateComponents", "version"],
       "additionalProperties": false
     },
     "UpdateDataModelMessage": {
       "type": "object",
       "properties": {
+        "version": {
+          "const": "v0.9"
+        },
         "updateDataModel": {
           "type": "object",
           "description": "Updates the data model for an existing surface. This message can be sent multiple times to update the data model. The createSurface message MUST have been previously sent with the 'catalogId' that is in this message.",
@@ -95,12 +104,15 @@
           "additionalProperties": false
         }
       },
-      "required": ["updateDataModel"],
+      "required": ["updateDataModel", "version"],
       "additionalProperties": false
     },
     "DeleteSurfaceMessage": {
       "type": "object",
       "properties": {
+        "version": {
+          "const": "v0.9"
+        },
         "deleteSurface": {
           "type": "object",
           "description": "Signals the client to delete the surface identified by 'surfaceId'. The createSurface message MUST have been previously sent with the 'catalogId' that is in this message.",
@@ -114,7 +126,7 @@
           "additionalProperties": false
         }
       },
-      "required": ["deleteSurface"],
+      "required": ["deleteSurface", "version"],
       "additionalProperties": false
     }
   }

specification/v0_9/test/cases/button_checks.json

@@ -5,6 +5,7 @@
       "description": "Button with nested valid checks",
       "valid": true,
       "data": {
+        "version": "v0.9",
         "updateComponents": {
           "surfaceId": "test_surface",
           "components": [
@@ -49,6 +50,7 @@
       "description": "Button with deprecated enabled property (should fail)",
       "valid": false,
       "data": {
+        "version": "v0.9",
         "updateComponents": {
           "surfaceId": "test_surface",
           "components": [
@@ -68,6 +70,7 @@
       "description": "Button with invalid check structure (invalid returnType)",
       "valid": false,
       "data": {
+        "version": "v0.9",
         "updateComponents": {
           "surfaceId": "test_surface",
           "components": [
@@ -93,6 +96,7 @@
       "description": "Button with invalid nested structure (extra property)",
       "valid": false,
       "data": {
+        "version": "v0.9",
         "updateComponents": {
           "surfaceId": "test_surface",
           "components": [
@@ -118,6 +122,7 @@
       "description": "Button with variant 'primary'",
       "valid": true,
       "data": {
+        "version": "v0.9",
         "updateComponents": {
           "surfaceId": "test_surface",
           "components": [
@@ -137,6 +142,7 @@
       "description": "Button with variant 'borderless'",
       "valid": true,
       "data": {
+        "version": "v0.9",
         "updateComponents": {
           "surfaceId": "test_surface",
           "components": [
@@ -156,6 +162,7 @@
       "description": "Button with deprecated 'primary' property (should fail)",
       "valid": false,
       "data": {
+        "version": "v0.9",
         "updateComponents": {
           "surfaceId": "test_surface",
           "components": [