{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://a2ui.org/specification/v0_9/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."
    },
    "AccessibilityAttributes": {
      "type": "object",
      "description": "Attributes to enhance accessibility when using assistive technologies like screen readers.",
      "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'."
        }
      }
    },
    "ComponentCommon": {
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/ComponentId"
        },
        "accessibility": {
          "$ref": "#/$defs/AccessibilityAttributes"
        }
      },
      "required": ["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"
        },
        {
          "$ref": "#/$defs/DataBinding"
        },
        {
          "$ref": "#/$defs/FunctionCall"
        }
      ]
    },
    "DynamicString": {
      "description": "Represents a string",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/$defs/DataBinding"
        },
        {
          "allOf": [
            {
              "$ref": "#/$defs/FunctionCall"
            },
            {
              "properties": {
                "returnType": {
                  "const": "string"
                }
              }
            }
          ]
        }
      ]
    },
    "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"
        },
        {
          "allOf": [
            {
              "$ref": "#/$defs/FunctionCall"
            },
            {
              "properties": {
                "returnType": {
                  "const": "number"
                }
              }
            }
          ]
        }
      ]
    },
    "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"
        },
        {
          "allOf": [
            {
              "$ref": "#/$defs/FunctionCall"
            },
            {
              "properties": {
                "returnType": {
                  "const": "boolean"
                }
              }
            }
          ]
        }
      ]
    },
    "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"
        },
        {
          "allOf": [
            {
              "$ref": "#/$defs/FunctionCall"
            },
            {
              "properties": {
                "returnType": {
                  "const": "array"
                }
              }
            }
          ]
        }
      ]
    },
    "FunctionCall": {
      "type": "object",
      "description": "Invokes a named function on the client.",
      "properties": {
        "call": {
          "type": "string",
          "description": "The name of the function to call."
        },
        "args": {
          "type": "object",
          "description": "Arguments passed to the function.",
          "additionalProperties": {
            "anyOf": [
              {
                "$ref": "#/$defs/DynamicValue"
              },
              {
                "type": "object",
                "description": "A literal object argument (e.g. configuration)."
              }
            ]
          }
        },
        "returnType": {
          "type": "string",
          "description": "The expected return type of the function call.",
          "enum": ["string", "number", "boolean", "array", "object", "any", "void"],
          "default": "boolean"
        }
      },
      "required": ["call"],
      "oneOf": [{"$ref": "catalog.json#/$defs/anyFunction"}]
    },
    "CheckRule": {
      "type": "object",
      "description": "A single validation rule applied to an input component.",
      "properties": {
        "condition": {
          "$ref": "#/$defs/DynamicBoolean"
        },
        "message": {
          "type": "string",
          "description": "The error message to display if the check fails."
        }
      },
      "required": ["condition", "message"],
      "additionalProperties": false
    },
    "Checkable": {
      "description": "Properties for components that support client-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 a server-side event or execute a local client-side function.",
      "oneOf": [
        {
          "type": "object",
          "description": "Triggers a server-side event.",
          "properties": {
            "event": {
              "type": "object",
              "description": "The event to dispatch to the server.",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "The name of the action to be dispatched to the server."
                },
                "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 local client-side function.",
          "properties": {
            "functionCall": {
              "$ref": "#/$defs/FunctionCall"
            }
          },
          "required": ["functionCall"],
          "additionalProperties": false
        }
      ]
    }
  }
}