From 53b3bc5ef7b29f4c24cabf4e2108da63be784cd2 Mon Sep 17 00:00:00 2001
From: wrenj <wrenj@google.com>
Date: Tue, 9 Dec 2025 15:32:49 +0000
Subject: [PATCH] Expand extension specification docs and unify URL (#246)

---
 .../src/main/java/org/a2ui/A2uiExtension.java |  2 +-
 .../0.8/docs/a2ui_extension_specification.md  | 30 +++++++++++++++++--
 specification/0.8/docs/a2ui_protocol.md       |  2 +-
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/a2a_agents/java/src/main/java/org/a2ui/A2uiExtension.java b/a2a_agents/java/src/main/java/org/a2ui/A2uiExtension.java
index 12ef671..9397361 100644
--- a/a2a_agents/java/src/main/java/org/a2ui/A2uiExtension.java
+++ b/a2a_agents/java/src/main/java/org/a2ui/A2uiExtension.java
@@ -32,7 +32,7 @@ import java.util.logging.Logger;
 public final class A2uiExtension {
   private static final Logger logger = Logger.getLogger(A2uiExtension.class.getName());
 
-  public static final String A2UI_EXTENSION_URI = "https://a2ui.org/a2a-extension/v0.1";
+  public static final String A2UI_EXTENSION_URI = "https://a2ui.org/a2a-extension/a2ui/v0.8";
   public static final String MIME_TYPE_KEY = "mimeType";
   public static final String A2UI_MIME_TYPE = "application/json+a2ui";
 
diff --git a/specification/0.8/docs/a2ui_extension_specification.md b/specification/0.8/docs/a2ui_extension_specification.md
index bfa9625..2d87828 100644
--- a/specification/0.8/docs/a2ui_extension_specification.md
+++ b/specification/0.8/docs/a2ui_extension_specification.md
@@ -6,7 +6,7 @@ This extension implements the A2UI (Agent-to-Agent UI) spec, a format for agents
 
 ## Extension URI
 
-The URI of this extension is https://a2ui.org/ext/a2a-ui/v0.8
+The URI of this extension is https://a2ui.org/a2a-extension/a2ui/v0.8
 
 This is the only URI accepted for this extension.
 
@@ -36,7 +36,7 @@ Example AgentExtension block:
 
 ```json
 {
-  "uri": "https://a2ui.org/ext/a2a-ui/v0.8",
+  "uri": "https://a2ui.org/a2a-extension/a2ui/v0.8",
   "description": "Ability to render A2UI",
   "required": false,
   "params": {
@@ -61,3 +61,29 @@ For JSON-RPC and HTTP transports, this is indicated via the X-A2A-Extensions HTT
 For gRPC, this is indicated via the X-A2A-Extensions metadata value.
 
 Activating this extension implies that the server can send A2UI-specific messages (like surfaceUpdate) and the client is expected to send A2UI-specific events (like userAction).
+
+## Data Encoding
+
+A2UI messages are encoded as an A2A `DataPart`.
+
+To identify a `DataPart` as containing A2UI data, it must have the following metadata:
+
+- `mimeType`: `application/json+a2ui`
+
+The `data` field of the `DataPart` contains the A2UI JSON message (e.g., `surfaceUpdate`, `userAction`).
+
+Example A2UI DataPart:
+
+```json
+{
+  "data": {
+    "beginRendering": {
+      "surfaceId": "outlier_stores_map_surface",
+    }
+  },
+  "kind": "data",
+  "metadata": {
+    "mimeType": "application/json+a2ui"
+  }
+}
+```
\ No newline at end of file
diff --git a/specification/0.8/docs/a2ui_protocol.md b/specification/0.8/docs/a2ui_protocol.md
index 8b41b7a..fedb4ad 100644
--- a/specification/0.8/docs/a2ui_protocol.md
+++ b/specification/0.8/docs/a2ui_protocol.md
@@ -192,7 +192,7 @@ The server (agent) advertises its capabilities in its Agent Card as part of the
   "capabilities": {
     "extensions": [
       {
-        "uri": "https://a2ui.org/ext/a2a-ui/v0.8",
+        "uri": "https://a2ui.org/a2a-extension/a2ui/v0.8",
         "params": {
           "supportedCatalogIds": [
             "https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json",