@mcp-native/a2ui 0.0.3 → 0.2.0

package/schemas/7541f953050cd58b80f0bf5d85fe2d63192af305/json/agent_capabilities.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2ui.org/specification/v1_0/agent_capabilities.json",
+  "title": "A2UI Agent Capabilities Schema",
+  "description": "A schema for the agent capabilities object, which is used by an A2UI Agent to advertise its supported UI features to renderers. This can be embedded in an Agent Card for A2A or used in other transport protocols like MCP.",
+  "type": "object",
+  "properties": {
+    "v1.0": {
+      "type": "object",
+      "description": "The agent capabilities structure for version 1.0 of the A2UI protocol.",
+      "properties": {
+        "supportedCatalogIds": {
+          "type": "array",
+          "description": "An array of strings, where each is an ID identifying a Catalog for which the agent can generate content. This is not a resolvable URI. Multiple catalogs can be mixed in a single surface.",
+          "items": {"type": "string"}
+        },
+        "acceptsInlineCatalogs": {
+          "type": "boolean",
+          "description": "A boolean indicating if the agent can accept an 'inlineCatalogs' array in the renderer's a2uiRendererCapabilities. If omitted, this defaults to false.",
+          "default": false
+        }
+      }
+    }
+  },
+  "required": ["v1.0"]
+}

package/schemas/7541f953050cd58b80f0bf5d85fe2d63192af305/json/agent_to_renderer.json

@@ -0,0 +1,216 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2ui.org/specification/v1_0/agent_to_renderer.json",
+  "title": "A2UI Message Schema",
+  "description": "Describes a JSON payload for an A2UI (Agent to UI) message, which is used to dynamically construct and update user interfaces.",
+  "type": "object",
+  "oneOf": [
+    {"$ref": "#/$defs/CreateSurfaceMessage"},
+    {"$ref": "#/$defs/UpdateComponentsMessage"},
+    {"$ref": "#/$defs/UpdateDataModelMessage"},
+    {"$ref": "#/$defs/DeleteSurfaceMessage"},
+    {"$ref": "#/$defs/CallRendererFunctionMessage"},
+    {"$ref": "#/$defs/AgentFunctionResponseMessage"}
+  ],
+  "$defs": {
+    "CreateSurfaceMessage": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": "v1.0"
+        },
+        "createSurface": {
+          "type": "object",
+          "description": "Signals the renderer to create a new surface and begin rendering it. Creating a surface implicitly instantiates the canonical 'Surface' container component ('common_types.json#/$defs/Surface') with 'child': 'root'. It is an error to try to create a surface with an existing ID without first deleting it; surfaceId MUST be globally unique for the renderer's lifetime. When this message is sent, the renderer expects 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId to define the component tree.",
+          "properties": {
+            "surfaceId": {
+              "type": "string",
+              "description": "The unique identifier for the UI surface to be rendered. It must be globally unique for the renderer's lifetime."
+            },
+            "catalogId": {
+              "description": "A string that uniquely identifies the default catalog for this surface. It is recommended to prefix this with an internet domain that you own, to avoid conflicts e.g. 'mycompany.com:somecatalog'. Components and function calls that do not explicitly specify a catalogId will use this surface-level default catalogId.",
+              "type": "string"
+            },
+            "sendDataModel": {
+              "type": "boolean",
+              "description": "If true, the renderer will send the full data model of this surface in the metadata of every A2A message sent to the agent that created the surface. Defaults to false."
+            },
+            "components": {
+              "$ref": "#/$defs/ComponentsList"
+            },
+            "dataModel": {
+              "type": "object",
+              "description": "The initial root data model object for the surface.",
+              "additionalProperties": true
+            },
+            "metadata": {
+              "type": "object",
+              "description": "Optional surface-level metadata.",
+              "properties": {
+                "extensions": {
+                  "$ref": "common_types.json#/$defs/Extensions"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "required": ["surfaceId"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["createSurface", "version"],
+      "additionalProperties": false
+    },
+    "Component": {
+      "description": "A UI component for the surface, combining baseline envelope properties with the catalog component definition.",
+      "allOf": [
+        {
+          "$ref": "common_types.json#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "catalog.json#/$defs/anyComponent"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "component": {
+              "not": {
+                "const": "Surface"
+              }
+            }
+          }
+        }
+      ],
+      "unevaluatedProperties": false
+    },
+    "ComponentsList": {
+      "type": "array",
+      "description": "A list containing UI components for the surface.",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/Component"
+      }
+    },
+    "UpdateComponentsMessage": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": "v1.0"
+        },
+        "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 for this surfaceId.",
+          "properties": {
+            "surfaceId": {
+              "type": "string",
+              "description": "The unique identifier for the UI surface to be updated. It must be globally unique for the renderer's lifetime."
+            },
+            "components": {
+              "$ref": "#/$defs/ComponentsList"
+            }
+          },
+          "required": ["surfaceId", "components"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["updateComponents", "version"],
+      "additionalProperties": false
+    },
+    "UpdateDataModelMessage": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": "v1.0"
+        },
+        "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 for this surfaceId.",
+          "properties": {
+            "surfaceId": {
+              "type": "string",
+              "description": "The unique identifier for the UI surface this data model update applies to. It must be globally unique for the renderer's lifetime."
+            },
+            "path": {
+              "type": "string",
+              "description": "An optional path to a location within the data model (e.g., '/user/name'). If omitted, or set to '/', refers to the entire data model."
+            },
+            "value": {
+              "description": "The data to be updated in the data model. To delete the key/value at 'path', set 'value' explicitly to null."
+            }
+          },
+          "required": ["surfaceId", "value"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["updateDataModel", "version"],
+      "additionalProperties": false
+    },
+    "DeleteSurfaceMessage": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": "v1.0"
+        },
+        "deleteSurface": {
+          "type": "object",
+          "description": "Signals the renderer to delete the surface identified by 'surfaceId'. The createSurface message MUST have been previously sent for this surfaceId.",
+          "properties": {
+            "surfaceId": {
+              "type": "string",
+              "description": "The unique identifier for the UI surface to be deleted. It must be globally unique for the renderer's lifetime."
+            }
+          },
+          "required": ["surfaceId"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["deleteSurface", "version"],
+      "additionalProperties": false
+    },
+    "CallRendererFunctionMessage": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": "v1.0"
+        },
+        "callRendererFunction": {
+          "type": "object",
+          "description": "Signals the renderer to execute a function locally on behalf of the agent.",
+          "properties": {
+            "functionCallId": {
+              "$ref": "common_types.json#/$defs/CallId",
+              "description": "Unique ID for this instance of the function call. The renderer MUST copy this ID into the return response."
+            },
+            "callFunction": {
+              "allOf": [
+                {
+                  "$ref": "common_types.json#/$defs/FunctionCall"
+                },
+                {
+                  "required": ["catalogId"]
+                }
+              ]
+            }
+          },
+          "required": ["functionCallId", "callFunction"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["callRendererFunction", "version"],
+      "additionalProperties": false
+    },
+    "AgentFunctionResponseMessage": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": "v1.0"
+        },
+        "agentFunctionResponse": {
+          "$ref": "common_types.json#/$defs/FunctionResponse"
+        }
+      },
+      "required": ["agentFunctionResponse", "version"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/7541f953050cd58b80f0bf5d85fe2d63192af305/json/agent_to_renderer_list.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2ui.org/specification/v1_0/json/agent_to_renderer_list.json",
+  "title": "A2UI Agent-to-Renderer Message List",
+  "description": "A list of A2UI Agent-to-Renderer messages.",
+  "type": "array",
+  "items": {
+    "$ref": "https://a2ui.org/specification/v1_0/agent_to_renderer.json"
+  }
+}

package/schemas/7541f953050cd58b80f0bf5d85fe2d63192af305/json/agent_to_renderer_list_wrapper.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2ui.org/specification/v1_0/json/agent_to_renderer_list_wrapper.json",
+  "title": "A2UI Agent-to-Renderer Message List Wrapper",
+  "description": "An object wrapping a list of A2UI Agent-to-Renderer messages. Intended for protocols that require a top-level JSON object instead of a raw array.",
+  "type": "object",
+  "properties": {
+    "messages": {
+      "$ref": "agent_to_renderer_list.json"
+    }
+  },
+  "additionalProperties": false,
+  "required": ["messages"]
+}

package/schemas/7541f953050cd58b80f0bf5d85fe2d63192af305/json/catalog_definition.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2ui.org/specification/v1_0/catalog_definition.json",
+  "title": "A2UI Catalog Definition Schema",
+  "description": "A collection of component and function definitions.",
+  "type": "object",
+  "properties": {
+    "$schema": {"type": "string"},
+    "$id": {"type": "string"},
+    "protocolVersion": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:\\.(0|[1-9][0-9]*))?(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
+      "default": "0.9",
+      "description": "The A2UI specification version of this catalog definition (e.g. '1.0'). Defaults to '0.9' if omitted."
+    },
+    "$defs": {
+      "type": "object",
+      "description": "Standardized schema definitions referenced from outside the catalog file.",
+      "properties": {
+        "anyComponent": {
+          "title": "A2UI Any Component Schema",
+          "description": "Unified validation schema for all components.",
+          "$ref": "https://json-schema.org/draft/2020-12/schema"
+        },
+        "anyFunction": {
+          "title": "A2UI Any Function Schema",
+          "description": "Unified validation schema for all functions.",
+          "$ref": "https://json-schema.org/draft/2020-12/schema"
+        }
+      },
+      "required": ["anyComponent", "anyFunction"],
+      "additionalProperties": false
+    },
+    "title": {
+      "type": "string",
+      "description": "The title of the catalog."
+    },
+    "description": {
+      "type": "string",
+      "description": "A human-readable description of the catalog."
+    },
+    "catalogId": {
+      "type": "string",
+      "description": "Unique identifier for this catalog."
+    },
+    "instructions": {
+      "type": "string",
+      "description": "Markdown-formatted design guidelines or instructions specific to this catalog."
+    },
+    "components": {
+      "type": "object",
+      "description": "Definitions for UI components supported by this catalog.",
+      "propertyNames": {
+        "not": {
+          "const": "Surface"
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/ComponentDefinition"
+      }
+    },
+    "functions": {
+      "type": "object",
+      "description": "Definitions for functions supported by this catalog.",
+      "additionalProperties": {
+        "$ref": "#/$defs/FunctionDefinition"
+      }
+    }
+  },
+  "required": ["catalogId"],
+  "additionalProperties": false,
+  "$defs": {
+    "FunctionCallValidationSchema": {
+      "type": "object",
+      "description": "JSON Schema structure that validates a wire-level FunctionCall object.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "const": "object"
+            },
+            "description": {
+              "type": "string"
+            },
+            "properties": {
+              "type": "object",
+              "properties": {
+                "call": {
+                  "type": "object",
+                  "properties": {
+                    "const": {"type": "string"}
+                  },
+                  "required": ["const"]
+                },
+                "catalogId": {
+                  "type": "object",
+                  "description": "Optional catalog ID override for this function call."
+                },
+                "args": {
+                  "type": "object",
+                  "description": "A JSON Schema describing the expected arguments (args) for this function.",
+                  "$ref": "https://json-schema.org/draft/2020-12/schema"
+                }
+              },
+              "required": ["call"],
+              "additionalProperties": false
+            },
+            "required": {
+              "type": "array",
+              "items": {"type": "string"},
+              "contains": {"const": "call"}
+            },
+            "unevaluatedProperties": {
+              "type": "boolean"
+            },
+            "additionalProperties": {
+              "type": "boolean"
+            }
+          },
+          "required": ["type", "properties", "required"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "const": "object"
+            },
+            "description": {
+              "type": "string"
+            },
+            "allOf": {
+              "type": "array",
+              "items": {"type": "object"},
+              "minItems": 1
+            },
+            "unevaluatedProperties": {
+              "type": "boolean"
+            },
+            "additionalProperties": {
+              "type": "boolean"
+            }
+          },
+          "required": ["type", "allOf"]
+        }
+      ]
+    },
+    "FunctionDefinition": {
+      "type": "object",
+      "description": "Describes a function's validation schema and interface metadata.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/FunctionCallValidationSchema"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "returnType": {
+              "type": "string",
+              "enum": [
+                "string",
+                "number",
+                "boolean",
+                "array",
+                "object",
+                "validationResult",
+                "any",
+                "void"
+              ],
+              "description": "The type of value this function returns."
+            },
+            "allowedCallers": {
+              "type": "string",
+              "enum": ["rendererOnly", "agentOnly", "rendererOrAgent"],
+              "default": "rendererOnly",
+              "description": "Specifies which roles are authorized to invoke this function."
+            },
+            "requiresUserActivation": {
+              "type": "boolean",
+              "default": false,
+              "description": "Specifies whether this function requires a user activation context to execute."
+            }
+          },
+          "required": ["returnType"]
+        },
+        {
+          "if": {
+            "properties": {
+              "requiresUserActivation": {"const": true}
+            }
+          },
+          "then": {
+            "properties": {
+              "allowedCallers": {"enum": ["rendererOnly"]}
+            }
+          }
+        }
+      ],
+      "unevaluatedProperties": false
+    },
+    "ComponentDefinition": {
+      "type": "object",
+      "description": "Describes a component's validation schema and composition constraints.",
+      "allOf": [
+        {
+          "$ref": "https://json-schema.org/draft/2020-12/schema"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "allowedParents": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "The list of parent component type names that can contain this component type. If omitted, all parent component types are allowed. To restrict a component so it can appear only as the top-level component (id='root') of a surface, set \"allowedParents\": [\"Surface\"]. To allow a component as either the top-level component of a surface or a child of a specific container, specify both (e.g., \"allowedParents\": [\"Surface\", \"CanvasContainer\"]).",
+              "uniqueItems": true
+            },
+            "allowedChildren": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "The list of child component type names allowed inside this container or slot. If omitted, all child component types are allowed.",
+              "uniqueItems": true
+            },
+            "metadata": {
+              "type": "object",
+              "description": "Optional static metadata.",
+              "properties": {
+                "extensions": {
+                  "$ref": "common_types.json#/$defs/Extensions"
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      ]
+    },
+    "ValidationResult": {
+      "type": "object",
+      "description": "Dynamic validation result object returned by a validation condition function or data binding.",
+      "properties": {
+        "valid": {
+          "type": "boolean",
+          "description": "Whether the check passed."
+        },
+        "code": {
+          "type": "string",
+          "description": "Machine-readable error code (e.g. EXPIRED_CARD, OUT_OF_RANGE)."
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable error or warning message."
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["error", "warning", "info"],
+          "default": "error",
+          "description": "Severity level of the validation result."
+        }
+      },
+      "required": ["valid"]
+    }
+  }
+}