@mcp-native/a2ui 0.1.0 → 0.3.0

package/dist/v1/vendor/common_types.json

@@ -0,0 +1,395 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://a2ui.org/specification/v1_0/common_types.json",
+    "title": "A2UI Common Types",
+    "description": "Common type definitions used across A2UI schemas.",
+    "$defs": {
+        "ComponentId": {
+            "type": "string",
+            "description": "The unique identifier for a component, used for both definitions and references within the same surface."
+        },
+        "CallId": {
+            "type": "string",
+            "description": "The unique identifier for a function call."
+        },
+        "AccessibilityAttributes": {
+            "type": "object",
+            "description": "Attributes to enhance accessibility when using assistive technologies like screen readers or model understanding.",
+            "properties": {
+                "label": {
+                    "$ref": "#/$defs/DynamicString",
+                    "description": "A short string, typically 1 to 3 words, used by assistive technologies to convey the purpose or intent of an element. For example, an input field might have an accessible label of 'User ID' or a button might be labeled 'Submit'."
+                },
+                "description": {
+                    "$ref": "#/$defs/DynamicString",
+                    "description": "Additional information provided by assistive technologies about an element such as instructions, format requirements, or result of an action. For example, a mute button might have a label of 'Mute' and a description of 'Silences notifications about this conversation'."
+                },
+                "live": {
+                    "type": "string",
+                    "enum": ["off", "polite", "assertive"],
+                    "default": "off",
+                    "description": "Controls screen reader announcements for dynamic updates (WAI-ARIA aria-live). 'polite' waits for user pause; 'assertive' interrupts immediately for alerts."
+                },
+                "hidden": {
+                    "$ref": "#/$defs/DynamicBoolean",
+                    "description": "Hides the element and its children from assistive technologies when true. Default is false."
+                }
+            },
+            "additionalProperties": false
+        },
+        "Extensions": {
+            "type": "object",
+            "description": "Optional extension metadata. Keys MUST be Unicode identifiers (UAX #31). Keys starting with 'a2ui_' are reserved for official extensions.",
+            "patternProperties": {
+                "^[\\p{XID_Start}_][\\p{XID_Continue}]*$": {}
+            },
+            "additionalProperties": false
+        },
+        "ComponentCommon": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "$ref": "#/$defs/ComponentId"
+                },
+                "catalogId": {
+                    "type": "string",
+                    "description": "The catalog ID for this component, overriding any surface-level default catalogId."
+                },
+                "accessibility": {
+                    "$ref": "#/$defs/AccessibilityAttributes"
+                },
+                "metadata": {
+                    "type": "object",
+                    "description": "Optional component-level metadata for vendor extensions.",
+                    "properties": {
+                        "extensions": {
+                            "$ref": "#/$defs/Extensions"
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "required": ["id"]
+        },
+        "Child": {
+            "$ref": "#/$defs/ComponentId",
+            "description": "A reference to a single child component ID."
+        },
+        "ChildList": {
+            "oneOf": [
+                {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/ComponentId"
+                    },
+                    "description": "A static list of child component IDs."
+                },
+                {
+                    "type": "object",
+                    "description": "A template for generating a dynamic list of children from a data model list. The `componentId` is the component to use as a template.",
+                    "properties": {
+                        "componentId": {
+                            "$ref": "#/$defs/ComponentId"
+                        },
+                        "path": {
+                            "type": "string",
+                            "description": "The path to the list of component property objects in the data model."
+                        }
+                    },
+                    "required": ["componentId", "path"],
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "DataBinding": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "A JSON Pointer path to a value in the data model."
+                }
+            },
+            "required": ["path"],
+            "additionalProperties": false
+        },
+        "DynamicValue": {
+            "description": "A value that can be a literal, a path, or a function call returning any type.",
+            "oneOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "number"
+                },
+                {
+                    "type": "boolean"
+                },
+                {
+                    "type": "array"
+                },
+                {
+                    "type": "object",
+                    "not": {
+                        "anyOf": [
+                            {
+                                "required": ["path"]
+                            },
+                            {
+                                "required": ["call"]
+                            }
+                        ]
+                    }
+                },
+                {
+                    "$ref": "#/$defs/DataBinding"
+                },
+                {
+                    "$ref": "#/$defs/FunctionCall"
+                }
+            ]
+        },
+        "DynamicString": {
+            "description": "Represents a string",
+            "oneOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "$ref": "#/$defs/DataBinding"
+                },
+                {
+                    "$ref": "#/$defs/FunctionCall"
+                }
+            ]
+        },
+        "DynamicNumber": {
+            "description": "Represents a value that can be either a literal number, a path to a number in the data model, or a function call returning a number.",
+            "oneOf": [
+                {
+                    "type": "number"
+                },
+                {
+                    "$ref": "#/$defs/DataBinding"
+                },
+                {
+                    "$ref": "#/$defs/FunctionCall"
+                }
+            ]
+        },
+        "DynamicBoolean": {
+            "description": "A boolean value that can be a literal, a path, or a function call returning a boolean.",
+            "oneOf": [
+                {
+                    "type": "boolean"
+                },
+                {
+                    "$ref": "#/$defs/DataBinding"
+                },
+                {
+                    "$ref": "#/$defs/FunctionCall"
+                }
+            ]
+        },
+        "DynamicStringList": {
+            "description": "Represents a value that can be either a literal array of strings, a path to a string array in the data model, or a function call returning a string array.",
+            "oneOf": [
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                {
+                    "$ref": "#/$defs/DataBinding"
+                },
+                {
+                    "$ref": "#/$defs/FunctionCall"
+                }
+            ]
+        },
+        "FunctionCommon": {
+            "type": "object",
+            "properties": {
+                "catalogId": {
+                    "type": "string",
+                    "description": "The catalog ID for this function, overriding any surface-level default catalogId."
+                }
+            }
+        },
+        "IndexSystemFunction": {
+            "type": "object",
+            "description": "Returns the 0-based index of the current item when rendering a dynamic list from a template. This function MUST ONLY be available when evaluating template items within a list context.",
+            "returnType": "number",
+            "properties": {
+                "call": {
+                    "const": "@index"
+                },
+                "args": {
+                    "type": "object",
+                    "properties": {
+                        "offset": {
+                            "$ref": "#/$defs/DynamicNumber",
+                            "description": "Optional. An offset to add to the 0-based index (e.g., 1 for 1-based indexing). Defaults to 0.",
+                            "default": 0
+                        }
+                    },
+                    "unevaluatedProperties": false
+                }
+            },
+            "required": ["call"],
+            "unevaluatedProperties": false
+        },
+        "FunctionCall": {
+            "type": "object",
+            "description": "Invokes a named function.",
+            "properties": {
+                "call": {
+                    "type": "string",
+                    "description": "The name of the function to call."
+                },
+                "catalogId": {
+                    "type": "string",
+                    "description": "The catalog ID for this function, overriding any surface-level default catalogId."
+                },
+                "args": {
+                    "type": "object",
+                    "description": "Arguments passed to the function.",
+                    "additionalProperties": {
+                        "anyOf": [
+                            {
+                                "$ref": "#/$defs/DynamicValue"
+                            },
+                            {
+                                "type": "object",
+                                "description": "A literal object argument (e.g. configuration)."
+                            }
+                        ]
+                    }
+                }
+            },
+            "required": ["call"],
+            "oneOf": [
+                { "$ref": "catalog.json#/$defs/anyFunction" },
+                { "$ref": "#/$defs/IndexSystemFunction" }
+            ],
+            "unevaluatedProperties": false
+        },
+        "CheckRule": {
+            "type": "object",
+            "description": "A single validation check rule applied to an input component. The condition function or path evaluates to a ValidationResult object.",
+            "properties": {
+                "condition": {
+                    "oneOf": [{ "$ref": "#/$defs/DataBinding" }, { "$ref": "#/$defs/FunctionCall" }],
+                    "description": "Path or function call evaluating to a ValidationResult object."
+                },
+                "message": {
+                    "type": "string",
+                    "description": "Optional fallback error message."
+                }
+            },
+            "required": ["condition"],
+            "additionalProperties": false
+        },
+        "Checkable": {
+            "description": "Properties for components that support renderer-side checks.",
+            "type": "object",
+            "properties": {
+                "checks": {
+                    "type": "array",
+                    "description": "A list of checks to perform. These are function calls that must return a boolean indicating validity.",
+                    "items": {
+                        "$ref": "#/$defs/CheckRule"
+                    }
+                }
+            }
+        },
+        "Action": {
+            "description": "Defines an interaction handler that can either trigger an agent-side event or execute a local renderer-side function.",
+            "oneOf": [
+                {
+                    "type": "object",
+                    "description": "Triggers an agent-side event.",
+                    "properties": {
+                        "event": {
+                            "type": "object",
+                            "description": "The event to dispatch to the agent.",
+                            "properties": {
+                                "name": {
+                                    "type": "string",
+                                    "description": "The name of the action to be dispatched to the agent."
+                                },
+                                "userMessage": {
+                                    "$ref": "#/$defs/DynamicString",
+                                    "description": "An optional human-readable message describing the action performed by the user, to present in conversation history or user feedback."
+                                },
+                                "context": {
+                                    "type": "object",
+                                    "description": "A JSON object containing the key-value pairs for the action context. Values can be literals or paths. Use literal values unless the value must be dynamically bound to the data model. Do NOT use paths for static IDs.",
+                                    "additionalProperties": {
+                                        "$ref": "#/$defs/DynamicValue"
+                                    }
+                                }
+                            },
+                            "required": ["name"],
+                            "additionalProperties": false
+                        }
+                    },
+                    "required": ["event"],
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "description": "Executes a renderer or agent-side function.",
+                    "properties": {
+                        "functionCall": {
+                            "$ref": "#/$defs/FunctionCall"
+                        }
+                    },
+                    "required": ["functionCall"],
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "Surface": {
+            "title": "Surface Container Component",
+            "description": "The reserved canonical container component representing an A2UI surface. The Surface component is immutable and always has 'child': 'root'.",
+            "type": "object",
+            "allowedParents": [],
+            "properties": {
+                "component": {
+                    "const": "Surface"
+                },
+                "child": {
+                    "const": "root"
+                }
+            },
+            "additionalProperties": false
+        },
+        "FunctionResponse": {
+            "type": "object",
+            "description": "The return response matching a callAgentFunction or callRendererFunction invocation.",
+            "properties": {
+                "functionCallId": {
+                    "$ref": "#/$defs/CallId",
+                    "description": "The unique ID matching the initiating function call."
+                },
+                "value": {
+                    "description": "The return value of the function."
+                },
+                "error": {
+                    "type": "object",
+                    "description": "An error object indicating failure of the function execution.",
+                    "properties": {
+                        "code": { "type": "string" },
+                        "message": { "type": "string" }
+                    },
+                    "required": ["code", "message"],
+                    "additionalProperties": false
+                }
+            },
+            "required": ["functionCallId"],
+            "oneOf": [{ "required": ["value"] }, { "required": ["error"] }],
+            "additionalProperties": false
+        }
+    }
+}

package/dist/v1/vendor/renderer_capabilities.json

@@ -0,0 +1,29 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://a2ui.org/specification/v1_0/renderer_capabilities.json",
+    "title": "A2UI Renderer Capabilities Schema",
+    "description": "A schema for the a2uiRendererCapabilities object, which is sent from the renderer to the agent as part of the A2A metadata to describe the renderer's UI rendering capabilities.",
+    "type": "object",
+    "properties": {
+        "v1.0": {
+            "type": "object",
+            "description": "The capabilities structure for version 1.0 of the A2UI protocol.",
+            "properties": {
+                "supportedCatalogIds": {
+                    "type": "array",
+                    "description": "An array of string identifiers for each of the component and function catalogs supported by the renderer. Multiple catalogs can be mixed in a single surface.",
+                    "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": "https://a2ui.org/specification/v1_0/catalog_definition.json"
+                    }
+                }
+            },
+            "required": ["supportedCatalogIds"]
+        }
+    },
+    "required": ["v1.0"]
+}

package/dist/v1/vendor/renderer_to_agent.json

@@ -0,0 +1,161 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://a2ui.org/specification/v1_0/renderer_to_agent.json",
+    "title": "A2UI (Agent to UI) Renderer-to-Agent Event Schema",
+    "description": "Describes a JSON payload for a renderer-to-agent event message.",
+    "type": "object",
+    "minProperties": 2,
+    "maxProperties": 2,
+    "properties": {
+        "version": {
+            "const": "v1.0"
+        },
+        "action": {
+            "type": "object",
+            "description": "Reports a user-initiated action from a component.",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "The name of the action, taken from the component's action.event.name property."
+                },
+                "userMessage": {
+                    "type": "string",
+                    "description": "An optional human-readable string describing the action performed by the user, taken from the component's action.event.userMessage property after resolving bindings."
+                },
+                "surfaceId": {
+                    "type": "string",
+                    "description": "The id of the surface where the event originated. It must be globally unique for the renderer's lifetime."
+                },
+                "sourceComponentId": {
+                    "type": "string",
+                    "description": "The id of the component that triggered the event."
+                },
+                "timestamp": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "An ISO 8601 timestamp of when the event occurred."
+                },
+                "context": {
+                    "type": "object",
+                    "description": "A JSON object containing the key-value pairs from the component's action.event.context, after resolving all data bindings.",
+                    "additionalProperties": true
+                },
+                "metadata": {
+                    "type": "object",
+                    "description": "Optional client-side metadata to send back to the agent with the action.",
+                    "properties": {
+                        "extensions": {
+                            "$ref": "common_types.json#/$defs/Extensions"
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "required": ["name", "surfaceId", "sourceComponentId", "timestamp", "context"]
+        },
+        "callAgentFunction": {
+            "type": "object",
+            "description": "Signals the agent to execute a function remotely on behalf of the renderer.",
+            "properties": {
+                "surfaceId": {
+                    "type": "string",
+                    "description": "The surface ID where the call originated."
+                },
+                "functionCallId": {
+                    "$ref": "common_types.json#/$defs/CallId",
+                    "description": "Unique ID for this instance of the function call. The agent MUST copy this ID into the return response."
+                },
+                "callFunction": {
+                    "$ref": "common_types.json#/$defs/FunctionCall"
+                }
+            },
+            "required": ["surfaceId", "functionCallId", "callFunction"],
+            "additionalProperties": false
+        },
+        "rendererFunctionResponse": {
+            "$ref": "common_types.json#/$defs/FunctionResponse"
+        },
+        "error": {
+            "description": "Reports a renderer-side error.",
+            "oneOf": [
+                {
+                    "type": "object",
+                    "title": "Validation Failed Error",
+                    "properties": {
+                        "code": {
+                            "enum": ["VALIDATION_FAILED", "UNALLOWED_PARENT", "UNALLOWED_CHILD"]
+                        },
+                        "surfaceId": {
+                            "type": "string",
+                            "description": "The id of the surface where the error occurred. It must be globally unique for the renderer's lifetime."
+                        },
+                        "path": {
+                            "type": "string",
+                            "description": "The JSON pointer to the field that failed validation (e.g. '/components/0/text')."
+                        },
+                        "message": {
+                            "type": "string",
+                            "description": "A short one or two sentence description of why validation failed."
+                        }
+                    },
+                    "required": ["code", "path", "message", "surfaceId"],
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "title": "Generic Error",
+                    "properties": {
+                        "code": {
+                            "type": "string",
+                            "not": {
+                                "enum": ["VALIDATION_FAILED", "UNALLOWED_PARENT", "UNALLOWED_CHILD"]
+                            }
+                        },
+                        "message": {
+                            "type": "string",
+                            "description": "A short one or two sentence description of why the error occurred."
+                        },
+                        "surfaceId": {
+                            "type": "string",
+                            "description": "The id of the surface where the error occurred. It must be globally unique for the renderer's lifetime."
+                        },
+                        "functionCallId": {
+                            "$ref": "common_types.json#/$defs/CallId",
+                            "description": "The unique ID of the function invocation, which must be identical to the value specified in the function invocation."
+                        }
+                    },
+                    "required": ["code", "message"],
+                    "oneOf": [
+                        {
+                            "required": ["surfaceId"],
+                            "not": {
+                                "required": ["functionCallId"]
+                            }
+                        },
+                        {
+                            "required": ["functionCallId"],
+                            "not": {
+                                "required": ["surfaceId"]
+                            }
+                        }
+                    ],
+                    "additionalProperties": true
+                }
+            ]
+        }
+    },
+    "oneOf": [
+        {
+            "required": ["action", "version"]
+        },
+        {
+            "required": ["callAgentFunction", "version"]
+        },
+        {
+            "required": ["rendererFunctionResponse", "version"]
+        },
+        {
+            "required": ["error", "version"]
+        }
+    ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-native/a2ui",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A2UI parsing and bindings for MCP Native.",
   "keywords": [
     "a2ui",
@@ -21,6 +21,7 @@
   },
   "files": [
     "dist",
+    "schemas",
     "README.md"
   ],
   "type": "module",
@@ -37,6 +38,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mcp-native/core": "^0.1.0"
+    "@mcp-native/core": "^0.3.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
   }
 }

package/schemas/7541f953050cd58b80f0bf5d85fe2d63192af305/CHECKSUMS.sha256

@@ -0,0 +1,13 @@
+29e01ac2cf69dc5860ad060f5a60c67fa5cdaa8a78ecab1018f531b178fa5c00  catalogs/basic/catalog.json
+86318a04b2fda504bededba936880e1d9cd5bcbb856b6aac6377f60e0426fbe9  json/agent_capabilities.json
+468c8e544dbe0b02d5d5586ebcdca399ecfa6d07a7b875d887089ce3bd2df160  json/agent_to_renderer.json
+3d3fef882fe5cc22932d3a91713defaeeb329126200954c06bf9f2c56df51c56  json/agent_to_renderer_list.json
+e306af2521e731db673415115d55b3d0e66453945c071e34298b4cb1dff88014  json/agent_to_renderer_list_wrapper.json
+a41e8b4dfa9a88377e6563f578222eee16642d22bbbc7e47d117dba8e9143be2  json/catalog_definition.json
+169ff987a7f8fb93a040ca33352ae4aeb684ff9742bff8cf5925b5cd2612e7d8  json/common_types.json
+923293ac283424ca08b68a951bc110f8885350baf4c8a9cb678c1647f0b22b3b  json/renderer_capabilities.json
+be0890fce16c10f903bd30808e0ec012c7766212fb95c983319db73faac485eb  json/renderer_data_model.json
+b23e1ca3e311f20d8a3b48620f4ca2e13a4188acd55de973075db421a0ed7e69  json/renderer_to_agent.json
+98899d7d16222207af3bfd9aab12aa7b8f68dc8b5267dcf76d867236235ec5d8  json/renderer_to_agent_list.json
+a0dbcaf2340def4485c287c19888aa81041ddee75e5717129457d4a39fbcc593  json/renderer_to_agent_list_wrapper.json
+7df58a955dfcd5241bfd5631df8fd291eb02d66f2f9a12304d5395517d64202f  json/sample.json

package/schemas/7541f953050cd58b80f0bf5d85fe2d63192af305/PROVENANCE.md

@@ -0,0 +1,12 @@
+# A2UI schema provenance
+
+| Field | Value |
+| --- | --- |
+| Upstream | https://github.com/a2ui-project/a2ui |
+| Commit | `7541f953050cd58b80f0bf5d85fe2d63192af305` |
+| Paths | `specification/v1_0/json/*`, `specification/v1_0/catalogs/basic/catalog.json` |
+| Fetched | 2026-08-26 |
+
+These files are an exact pin of the A2UI v1.0 Candidate revision used by MCP Native's project-owned binding (`A2UI_MCP_SCHEMA_REVISION`). `CHECKSUMS.sha256` records every pinned JSON file. `npm run schemas:verify` checks those hashes, rejects untracked JSON, verifies the exported revision, and requires the runtime copies to remain byte-for-byte identical.
+
+Runtime validation embeds copies of `common_types.json`, `agent_to_renderer.json`, `renderer_to_agent.json`, and `catalogs/basic/catalog.json` under `packages/a2ui/src/v1/vendor/` for static import. Do not silently retarget a moving branch; bump the pin, checksums, runtime copies, and documentation through a reviewed protocol change.