POTENTIALLY BREAKING CHANGE refactor: IANA convention requires mime type application/a2ui+json (a2ui-project#1493)

* refactor: rename mime type application/json+a2ui to application/a2ui+json

* refactor: address PR review feedback for backward compatibility in MIME type checks

* refactor: add deprecated MIME type fallback in Kotlin and Python SDKs

* refactor: ensure backward compatibility in MCP app samples

* refactor: revert old specs & add ui_version based negotiation for old MIME types

* refactor: introduce incremental version v0.9.1 to support application/a2ui+json MIME type

* docs: update catalogs concept guide to reflect consolidated Linking and register-catalogs.js

* style: run pyink and ktfmt to resolve CI formatting checks

Author: dmandar

agent_sdks/agent_sdk_guide.md

@@ -201,7 +201,7 @@ Once validated, the A2UI payload must be transmitted over the network. In typica
 
 ### Standards for Transport
 
-1.  **MIME Type**: Mark A2UI JSON payloads with `application/json+a2ui`. This tells the frontend renderer (e.g., the browser or mobile app) how to interpret the stream.
+1.  **MIME Type**: Mark A2UI JSON payloads with `application/a2ui+json`. This tells the frontend renderer (e.g., the browser or mobile app) how to interpret the stream.
 2.  **Standard Helpers**: Provide a `createA2uiPart` helper to automate this wrapping process.
 3.  **Yielding Strategy**: Support both complete objects (when the LLM finishes speaking) and incremental streaming parser yielding (for partial JSON display).
 

agent_sdks/conformance/suites/a2a_integration.yaml

@@ -17,12 +17,12 @@
   args:
     data: {"foo": "bar"}
   expect:
-    mime_type: "application/json+a2ui"
+    mime_type: "application/a2ui+json"
 
 - name: test_is_a2ui_part
   action: is_a2ui_part
   args:
-    mime_type: "application/json+a2ui"
+    mime_type: "application/a2ui+json"
   expect: true
 
 - name: test_try_activate_extension_success
@@ -58,7 +58,7 @@
       - kind: "text"
         text: "Here is your chart:"
       - kind: "data"
-        mimeType: "application/json+a2ui"
+        mimeType: "application/a2ui+json"
         data: {"beginRendering": {"surfaceId": "sales-dashboard"}}
       - kind: "text"
         text: "Enjoy!"

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/a2a/A2uiA2a.kt

@@ -26,15 +26,22 @@ import kotlinx.serialization.json.JsonElement
 object A2uiA2a {
   const val A2UI_EXTENSION_BASE_URI = "https://a2ui.org/a2a-extension/a2ui/v"
   const val MIME_TYPE_KEY = "mimeType"
-  const val A2UI_MIME_TYPE = "application/json+a2ui"
+  const val A2UI_MIME_TYPE = "application/a2ui+json"
+  const val DEPRECATED_A2UI_MIME_TYPE = "application/json+a2ui"
 
   /** Creates an A2A Part containing A2UI data. */
-  fun createA2uiPart(a2uiData: JsonElement): Part<*> =
-    DataPart(a2uiData, mapOf(MIME_TYPE_KEY to A2UI_MIME_TYPE))
+  @JvmOverloads
+  fun createA2uiPart(a2uiData: JsonElement, version: String? = null): Part<*> {
+    val mimeType =
+      if (version == "0.8" || version == "0.9") DEPRECATED_A2UI_MIME_TYPE else A2UI_MIME_TYPE
+    return DataPart(a2uiData, mapOf(MIME_TYPE_KEY to mimeType))
+  }
 
   /** Checks if an A2A Part contains A2UI data. */
   fun isA2uiPart(part: Part<*>): Boolean =
-    part is DataPart && part.metadata?.get(MIME_TYPE_KEY) == A2UI_MIME_TYPE
+    part is DataPart &&
+      (part.metadata?.get(MIME_TYPE_KEY) == A2UI_MIME_TYPE ||
+        part.metadata?.get(MIME_TYPE_KEY) == DEPRECATED_A2UI_MIME_TYPE)
 
   /** Extracts the A2UI data from an A2A Part if present. */
   fun getA2uiData(part: Part<*>): JsonElement? =

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/basic_catalog/BasicCatalogProvider.kt

@@ -41,6 +41,8 @@ class BundledCatalogProvider(private val version: A2uiVersion) : A2uiCatalogProv
     val filename =
       if (version == A2uiVersion.VERSION_0_9) {
         relPath.substringAfter("specification/v0_9/")
+      } else if (version == A2uiVersion.VERSION_0_9_1) {
+        relPath.substringAfter("specification/v0_9_1/")
       } else {
         relPath.substringAfterLast('/')
       }
@@ -81,6 +83,10 @@ object BasicCatalog {
         ),
       A2uiVersion.VERSION_0_9 to
         mapOf(A2uiConstants.CATALOG_SCHEMA_KEY to "specification/v0_9/catalogs/basic/catalog.json"),
+      A2uiVersion.VERSION_0_9_1 to
+        mapOf(
+          A2uiConstants.CATALOG_SCHEMA_KEY to "specification/v0_9_1/catalogs/basic/catalog.json"
+        ),
     )
 
   /**

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/schema/A2uiConstants.kt

@@ -38,6 +38,7 @@ object A2uiConstants {
 
   const val VERSION_0_8 = "0.8"
   const val VERSION_0_9 = "0.9"
+  const val VERSION_0_9_1 = "0.9.1"
 
   const val A2UI_OPEN_TAG = "<a2ui-json>"
   const val A2UI_CLOSE_TAG = "</a2ui-json>"

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/schema/A2uiSchemaManager.kt

@@ -30,6 +30,7 @@ enum class A2uiVersion(
 ) {
   VERSION_0_8(A2uiConstants.VERSION_0_8, "server_to_client.json"),
   VERSION_0_9(A2uiConstants.VERSION_0_9, "server_to_client.json", "common_types.json"),
+  VERSION_0_9_1(A2uiConstants.VERSION_0_9_1, "server_to_client.json", "common_types.json"),
 }
 
 /**

agent_sdks/python/agent_development.md

@@ -169,7 +169,7 @@ for part in response_parts:
 
 **2. Stream the A2UI Payload**
 
-Wrap the validated payloads in an A2A `DataPart` with the correct MIME type (`application/json+a2ui`) and stream it.
+Wrap the validated payloads in an A2A `DataPart` with the correct MIME type (`application/a2ui+json`) and stream it.
 
 **Recommendation:** Use the `create_a2ui_part` helper.
 

agent_sdks/python/src/a2ui/a2a/parts.py

@@ -26,23 +26,29 @@
 logger = logging.getLogger(__name__)
 
 MIME_TYPE_KEY = "mimeType"
-A2UI_MIME_TYPE = "application/json+a2ui"
+A2UI_MIME_TYPE = "application/a2ui+json"
+DEPRECATED_A2UI_MIME_TYPE = "application/json+a2ui"
 
 
-def create_a2ui_part(a2ui_data: dict[str, Any]) -> Part:
+def create_a2ui_part(a2ui_data: dict[str, Any], version: Optional[str] = None) -> Part:
   """Creates an A2A Part containing A2UI data.
 
   Args:
       a2ui_data: The A2UI data dictionary.
+      version: Optional version string.
 
   Returns:
       An A2A Part with a DataPart containing the A2UI data.
   """
+  mime_type = A2UI_MIME_TYPE
+  if version in ("0.8", "0.9", "v0.8", "v0.9"):
+    mime_type = DEPRECATED_A2UI_MIME_TYPE
+
   return Part(
       root=DataPart(
           data=a2ui_data,
           metadata={
-              MIME_TYPE_KEY: A2UI_MIME_TYPE,
+              MIME_TYPE_KEY: mime_type,
           },
       )
   )
@@ -60,7 +66,8 @@ def is_a2ui_part(part: Part) -> bool:
   return (
       isinstance(part.root, DataPart)
       and part.root.metadata
-      and part.root.metadata.get(MIME_TYPE_KEY) == A2UI_MIME_TYPE
+      and part.root.metadata.get(MIME_TYPE_KEY)
+      in (A2UI_MIME_TYPE, DEPRECATED_A2UI_MIME_TYPE)
   )
 
 
@@ -82,13 +89,15 @@ def parse_response_to_parts(
     content: str,
     validator: Optional[Any] = None,
     fallback_text: Optional[str] = None,
+    version: Optional[str] = None,
 ) -> List[Part]:
   """Helper to parse LLM response content into A2A Parts, with optional validation.
 
   Args:
       content: The LLM response content, potentially containing A2UI delimiters.
       validator: Optional validator to run against extracted JSON payloads.
       fallback_text: Optional text to return if no parts are successfully created.
+      version: Optional version string.
 
   Returns:
       A list of A2A Part objects (TextPart and/or DataPart).
@@ -110,9 +119,9 @@ def parse_response_to_parts(
 
         if isinstance(json_data, list):
           for message in json_data:
-            parts.append(create_a2ui_part(message))
+            parts.append(create_a2ui_part(message, version=version))
         else:
-          parts.append(create_a2ui_part(json_data))
+          parts.append(create_a2ui_part(json_data, version=version))
 
   except Exception as e:
     logger.warning(f"Failed to parse or validate A2UI response: {e}")
@@ -126,12 +135,14 @@ def parse_response_to_parts(
 async def stream_response_to_parts(
     parser: "A2uiStreamParser",
     token_stream: AsyncIterable[str],
+    version: Optional[str] = None,
 ) -> AsyncIterable[Part]:
   """Helper to parse a stream of LLM tokens into A2A Parts incrementally.
 
   Args:
       parser: A2uiStreamParser instance to process the stream.
       token_stream: An async iterable of strings (tokens).
+      version: Optional version string.
 
   Yields:
       A2A Part objects as they are discovered in the stream.
@@ -154,6 +165,6 @@ async def stream_response_to_parts(
 
         if isinstance(json_data, list):
           for message in json_data:
-            yield create_a2ui_part(message)
+            yield create_a2ui_part(message, version=version)
         else:
-          yield create_a2ui_part(json_data)
+          yield create_a2ui_part(json_data, version=version)

agent_sdks/python/src/a2ui/basic_catalog/constants.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ..schema.constants import CATALOG_SCHEMA_KEY, VERSION_0_8, VERSION_0_9
+from ..schema.constants import CATALOG_SCHEMA_KEY, VERSION_0_8, VERSION_0_9, VERSION_0_9_1
 
 BASIC_CATALOG_NAME = "basic"
 
@@ -22,4 +22,7 @@
         CATALOG_SCHEMA_KEY: "specification/v0_8/json/standard_catalog_definition.json"
     },
     VERSION_0_9: {CATALOG_SCHEMA_KEY: "specification/v0_9/catalogs/basic/catalog.json"},
+    VERSION_0_9_1: {
+        CATALOG_SCHEMA_KEY: "specification/v0_9_1/catalogs/basic/catalog.json"
+    },
 }

agent_sdks/python/src/a2ui/schema/constants.py

@@ -32,6 +32,7 @@
 
 VERSION_0_8 = "0.8"
 VERSION_0_9 = "0.9"
+VERSION_0_9_1 = "0.9.1"
 
 SPEC_VERSION_MAP = {
     VERSION_0_8: {
@@ -41,6 +42,10 @@
         SERVER_TO_CLIENT_SCHEMA_KEY: "specification/v0_9/json/server_to_client.json",
         COMMON_TYPES_SCHEMA_KEY: "specification/v0_9/json/common_types.json",
     },
+    VERSION_0_9_1: {
+        SERVER_TO_CLIENT_SCHEMA_KEY: "specification/v0_9_1/json/server_to_client.json",
+        COMMON_TYPES_SCHEMA_KEY: "specification/v0_9_1/json/common_types.json",
+    },
 }
 
 SPECIFICATION_DIR = "specification"