@polyxd/a2ui 0.1.0

package/vendor/a2ui/v1_0-04e6f07/json/common_types.json

@@ -0,0 +1,386 @@
+{
+  "$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",
+      "description": "Baseline envelope properties common to all function calls. Function-specific argument schemas ('args') are defined individually by each function in the active catalog.",
+      "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."
+        }
+      },
+      "required": ["call"]
+    },
+    "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, combining common function properties with the catalog function definition.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/FunctionCommon"
+        },
+        {
+          "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
+    }
+  }
+}