{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://a2ui.org/specification/v1_0/client_to_server.json",
    "title": "A2UI (Agent to UI) Client-to-Server Event Schema",
    "description": "Describes a JSON payload for a client-to-server 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."
                },
                "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
                },
                "wantResponse": {
                    "type": "boolean",
                    "description": "If true, the client expects an actionResponse from the server.",
                    "default": false
                },
                "actionId": {
                    "type": "string",
                    "description": "Unique ID for this action call. Only needed if wantResponse is true."
                }
            },
            "required": ["name", "surfaceId", "sourceComponentId", "timestamp", "context"]
        },
        "functionResponse": {
            "properties": {
                "functionCallId": {
                    "$ref": "common_types.json#/$defs/CallId",
                    "description": "Unique ID for the instance of this function. MUST be copied verbatim from the function invocation."
                },
                "call": {
                    "type": "string",
                    "description": "The name of the function which was called. MUST be copied verbatim from the function invocation. Useful for logging."
                },
                "value": {
                    "description": "The return value of the function invocation.",
                    "type": ["string", "number", "boolean", "array", "object", "null"]
                }
            },
            "required": ["functionCallId", "call", "value"],
            "unevaluatedProperties": false
        },
        "error": {
            "description": "Reports a client-side error.",
            "oneOf": [
                {
                    "type": "object",
                    "title": "Validation Failed Error",
                    "properties": {
                        "code": {
                            "const": "VALIDATION_FAILED"
                        },
                        "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": {
                            "not": {
                                "const": "VALIDATION_FAILED"
                            }
                        },
                        "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": ["functionResponse", "version"]
        },
        {
            "required": ["error", "version"]
        }
    ]
}