A2UI Types

https://docs.rs/a2ui-types/
Admin
A2UI Types is a Rust crate providing common data types and definitions for user interface (UI)...
Tokens:21,882
Snippets:162
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Define v0.9 Client and Server Capabilities

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/capabilities.rs.html

Structures for representing client and server capabilities in v0.9, including support for catalog IDs and inline catalog configuration.

```rust
1use serde::{Deserialize, Serialize};

use super::catalog::Catalog;

// ---------------------------------------------------------------------------
// Client Capabilities
// ---------------------------------------------------------------------------

/// Client capabilities for v0.9, sent in A2A message metadata under `a2uiClientCapabilities`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClientCapabilities {
    /// The capabilities structure for v0.9.
    #[serde(rename = "v0.9")]
    pub v09: ClientCapabilitiesV09,
}

/// The inner capabilities object for v0.9.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClientCapabilitiesV09 {
    /// URIs of component and function catalogs supported by the client.
    #[serde(rename = "supportedCatalogIds")]
    pub supported_catalog_ids: Vec<String>,

    /// Inline catalog definitions (only if the agent declares `acceptsInlineCatalogs: true`).
    #[serde(rename = "inlineCatalogs", skip_serializing_if = "Option::is_none")]
    pub inline_catalogs: Option<Vec<Catalog>>,
}

// ---------------------------------------------------------------------------
// Server Capabilities
// ---------------------------------------------------------------------------

/// Server capabilities for v0.9, advertised via Agent Card or transport initialization.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ServerCapabilities {
    /// The server capabilities structure for v0.9.
    #[serde(rename = "v0.9")]
    pub v09: ServerCapabilitiesV09,
}

/// The inner server capabilities object for v0.9.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ServerCapabilitiesV09 {
    /// Catalog IDs that the server can generate UI for.
    #[serde(
        rename = "supportedCatalogIds",
        skip_serializing_if = "Option::is_none"
    )]
    pub supported_catalog_ids: Option<Vec<String>>,

    /// Whether the server accepts inline catalogs from the client.
    #[serde(
        rename = "acceptsInlineCatalogs",
        skip_serializing_if = "Option::is_none"
    )]
    pub accepts_inline_catalogs: Option<bool>,
}
```

--------------------------------

### Define ClientToServerMessage and UserAction structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/client_to_server.rs.html?search=u32+-%3E+bool

Structures for handling client-to-server events in v0.8, utilizing serde for serialization.

```rust
1use serde::{Deserialize, Serialize};
2
3use crate::common::SurfaceId;
4
5/// A single client-to-server event message in v0.8.
6/// Must contain exactly one of `user_action` or `error`.
7#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
8#[serde(deny_unknown_fields)]
9pub struct ClientToServerMessage {
10    /// Reports a user-initiated action from a component.
11    #[serde(rename = "userAction", skip_serializing_if = "Option::is_none")]
12    pub user_action: Option<UserAction>,
13
14    /// Reports a client-side error.
15    #[serde(skip_serializing_if = "Option::is_none")]
16    pub error: Option<serde_json::Value>,
17}
18
19/// A user-initiated action event in v0.8.
20#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
21pub struct UserAction {
22    /// The name of the action, taken from the component's action.name property.
23    pub name: String,
24
25    /// The ID of the surface where the event originated.
26    #[serde(rename = "surfaceId")]
27    pub surface_id: SurfaceId,
28
29    /// The ID of the component that triggered the event.
30    #[serde(rename = "sourceComponentId")]
31    pub source_component_id: String,
32
33    /// An ISO 8601 timestamp of when the event occurred.
34    pub timestamp: String,
35
36    /// Key-value pairs from the component's action.context, after resolving all data bindings.
37    pub context: serde_json::Value,
38}
```

--------------------------------

### Define ClientToServerMessage and UserAction structs

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/client_to_server.rs.html

Structures for handling client-to-server events in v0.8, utilizing Serde for serialization and deserialization.

```rust
use serde::{Deserialize, Serialize};

use crate::common::SurfaceId;

/// A single client-to-server event message in v0.8.
/// Must contain exactly one of `user_action` or `error`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ClientToServerMessage {
    /// Reports a user-initiated action from a component.
    #[serde(rename = "userAction", skip_serializing_if = "Option::is_none")]
    pub user_action: Option<UserAction>,

    /// Reports a client-side error.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<serde_json::Value>,
}

/// A user-initiated action event in v0.8.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct UserAction {
    /// The name of the action, taken from the component's action.name property.
    pub name: String,

    /// The ID of the surface where the event originated.
    #[serde(rename = "surfaceId")]
    pub surface_id: SurfaceId,

    /// The ID of the component that triggered the event.
    #[serde(rename = "sourceComponentId")]
    pub source_component_id: String,

    /// An ISO 8601 timestamp of when the event occurred.
    pub timestamp: String,

    /// Key-value pairs from the component's action.context, after resolving all data bindings.
    pub context: serde_json::Value,
}
```

--------------------------------

### Define ClientCapabilities and InlineCatalog structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/capabilities.rs.html?search=std%3A%3Avec

Defines the Rust structures for v0.8 client capabilities, including support for catalog IDs and optional inline catalog definitions.

```rust
1use serde::{Deserialize, Serialize};

/// Client capabilities for v0.8, sent in A2A message metadata.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClientCapabilities {
    /// The URIs of catalogs supported by the client.
    #[serde(rename = "supportedCatalogIds")]
    pub supported_catalog_ids: Vec<String>,

    /// Inline catalog definitions (only if the agent declares `acceptsInlineCatalogs: true`).
    #[serde(rename = "inlineCatalogs", skip_serializing_if = "Option::is_none")]
    pub inline_catalogs: Option<Vec<InlineCatalog>>,
}

/// An inline catalog definition provided by the client in v0.8.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InlineCatalog {
    /// Unique identifier for this catalog.
    #[serde(rename = "catalogId")]
    pub catalog_id: String,

    /// Component definitions, keyed by component type name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub components: Option<serde_json::Value>,

    /// Style definitions.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub styles: Option<serde_json::Value>,
}
```

--------------------------------

### Define v0.9 Client and Server Capabilities

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/capabilities.rs.html?search=std%3A%3Avec

Structures for serializing and deserializing v0.9 capability metadata for A2A communication.

```rust
1use serde::{Deserialize, Serialize};
2
3use super::catalog::Catalog;
4
5// ---------------------------------------------------------------------------
6// Client Capabilities
7// ---------------------------------------------------------------------------
8
9/// Client capabilities for v0.9, sent in A2A message metadata under `a2uiClientCapabilities`.
10#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
11pub struct ClientCapabilities {
12    /// The capabilities structure for v0.9.
13    #[serde(rename = "v0.9")]
14    pub v09: ClientCapabilitiesV09,
15}
16
17/// The inner capabilities object for v0.9.
18#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
19pub struct ClientCapabilitiesV09 {
20    /// URIs of component and function catalogs supported by the client.
21    #[serde(rename = "supportedCatalogIds")]
22    pub supported_catalog_ids: Vec<String>,
23
24    /// Inline catalog definitions (only if the agent declares `acceptsInlineCatalogs: true`).
25    #[serde(rename = "inlineCatalogs", skip_serializing_if = "Option::is_none")]
26    pub inline_catalogs: Option<Vec<Catalog>>,
27}
28
29// ---------------------------------------------------------------------------
30// Server Capabilities
31// ---------------------------------------------------------------------------
32
33/// Server capabilities for v0.9, advertised via Agent Card or transport initialization.
34#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
35pub struct ServerCapabilities {
36    /// The server capabilities structure for v0.9.
37    #[serde(rename = "v0.9")]
38    pub v09: ServerCapabilitiesV09,
39}
40
41/// The inner server capabilities object for v0.9.
42#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
43pub struct ServerCapabilitiesV09 {
44    /// Catalog IDs that the server can generate UI for.
45    #[serde(
46        rename = "supportedCatalogIds",
47        skip_serializing_if = "Option::is_none"
48    )]
49    pub supported_catalog_ids: Option<Vec<String>>,
50
51    /// Whether the server accepts inline catalogs from the client.
52    #[serde(
53        rename = "acceptsInlineCatalogs",
54        skip_serializing_if = "Option::is_none"
55    )]
56    pub accepts_inline_catalogs: Option<bool>,
57}
```

--------------------------------

### Define Action and ActionContextEntry structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/data_model.rs.html

Structures for defining server-dispatched actions and their associated context entries.

```rust
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Action {
    /// The name of the action to dispatch to the server.
    pub name: String,

    /// Key-value pairs for the action context. Values can be literals or data-bound.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub context: Option<Vec<ActionContextEntry>>,
}

/// A single entry in an action's context array.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionContextEntry {
    /// The key name.
    pub key: String,

    /// The value, which can be literal or data-bound.
    pub value: BoundValue,
}
```

--------------------------------

### Define Action and ActionContextEntry structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/data_model.rs.html?search=

Structures for representing server-side actions and their associated context entries.

```rust
pub struct Action {
    /// The name of the action to dispatch to the server.
    pub name: String,

    /// Key-value pairs for the action context. Values can be literals or data-bound.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub context: Option<Vec<ActionContextEntry>>,
}

/// A single entry in an action's context array.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionContextEntry {
    /// The key name.
    pub key: String,

    /// The value, which can be literal or data-bound.
    pub value: BoundValue,
}
```

--------------------------------

### Define Client and Server Capabilities for v0.9

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/capabilities.rs.html?search=

Structures for representing client and server capabilities in A2A message metadata, utilizing Serde for JSON serialization.

```rust
use serde::{Deserialize, Serialize};

use super::catalog::Catalog;

// ---------------------------------------------------------------------------
// Client Capabilities
// ---------------------------------------------------------------------------

/// Client capabilities for v0.9, sent in A2A message metadata under `a2uiClientCapabilities`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClientCapabilities {
    /// The capabilities structure for v0.9.
    #[serde(rename = "v0.9")]
    pub v09: ClientCapabilitiesV09,
}

/// The inner capabilities object for v0.9.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClientCapabilitiesV09 {
    /// URIs of component and function catalogs supported by the client.
    #[serde(rename = "supportedCatalogIds")]
    pub supported_catalog_ids: Vec<String>,

    /// Inline catalog definitions (only if the agent declares `acceptsInlineCatalogs: true`).
    #[serde(rename = "inlineCatalogs", skip_serializing_if = "Option::is_none")]
    pub inline_catalogs: Option<Vec<Catalog>>,
}

// ---------------------------------------------------------------------------
// Server Capabilities
// ---------------------------------------------------------------------------

/// Server capabilities for v0.9, advertised via Agent Card or transport initialization.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ServerCapabilities {
    /// The server capabilities structure for v0.9.
    #[serde(rename = "v0.9")]
    pub v09: ServerCapabilitiesV09,
}

/// The inner server capabilities object for v0.9.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ServerCapabilitiesV09 {
    /// Catalog IDs that the server can generate UI for.
    #[serde(
        rename = "supportedCatalogIds",
        skip_serializing_if = "Option::is_none"
    )]
    pub supported_catalog_ids: Option<Vec<String>>,

    /// Whether the server accepts inline catalogs from the client.
    #[serde(
        rename = "acceptsInlineCatalogs",
        skip_serializing_if = "Option::is_none"
    )]
    pub accepts_inline_catalogs: Option<bool>,
}
```

--------------------------------

### Define ServerCapabilitiesV09 struct

Source: https://docs.rs/a2ui-types/latest/a2ui_types/v09/capabilities/struct.ServerCapabilitiesV09.html

The structure definition for server capabilities in v0.9.

```rust
pub struct ServerCapabilitiesV09 {
    pub supported_catalog_ids: Option<Vec<String>>,
    pub accepts_inline_catalogs: Option<bool>,
}
```

--------------------------------

### SurfaceId::new

Source: https://docs.rs/a2ui-types/latest/a2ui_types/common/struct.SurfaceId.html?search=std%3A%3Avec

Creates a new SurfaceId instance from a string-like input.

```APIDOC
## pub fn new(id: impl Into<String>) -> Self

### Description
Creates a new instance of SurfaceId using the provided identifier.

### Parameters
- **id** (impl Into<String>) - Required - The identifier string to wrap.
```

--------------------------------

### Define ClientCapabilities and InlineCatalog structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/capabilities.rs.html

These structures are used for serializing and deserializing client capabilities in A2A message metadata. They require the serde crate for JSON serialization.

```rust
use serde::{Deserialize, Serialize};

/// Client capabilities for v0.8, sent in A2A message metadata.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClientCapabilities {
    /// The URIs of catalogs supported by the client.
    #[serde(rename = "supportedCatalogIds")]
    pub supported_catalog_ids: Vec<String>,

    /// Inline catalog definitions (only if the agent declares `acceptsInlineCatalogs: true`).
    #[serde(rename = "inlineCatalogs", skip_serializing_if = "Option::is_none")]
    pub inline_catalogs: Option<Vec<InlineCatalog>>,
}

/// An inline catalog definition provided by the client in v0.8.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InlineCatalog {
    /// Unique identifier for this catalog.
    #[serde(rename = "catalogId")]
    pub catalog_id: String,

    /// Component definitions, keyed by component type name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub components: Option<serde_json::Value>,

    /// Style definitions.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub styles: Option<serde_json::Value>,
}
```

--------------------------------

### Define ClientDataModel struct

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/client_data_model.rs.html?search=u32+-%3E+bool

Represents the client data model schema with versioning and surface data mapping. Requires serde for serialization and deserialization.

```rust
1use std::collections::HashMap;
2
3use serde::{Deserialize, Serialize};
4
5/// Schema for attaching the client data model to transport metadata.
6/// Placed in the `a2uiClientDataModel` field of the metadata.
7#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
8#[serde(deny_unknown_fields)]
9pub struct ClientDataModel {
10    /// Protocol version — always `"v0.9"`.
11    pub version: String,
12
13    /// A map of surface IDs to their current data models.
14    pub surfaces: HashMap<String, serde_json::Value>,
15}
```

--------------------------------

### SurfaceId::new

Source: https://docs.rs/a2ui-types/latest/a2ui_types/common/struct.SurfaceId.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new SurfaceId instance from a string-like value.

```APIDOC
## pub fn new(id: impl Into<String>) -> Self

### Description
Creates a new instance of `SurfaceId` using the provided identifier.

### Parameters
- **id** (impl Into<String>) - Required - The identifier string to wrap in a SurfaceId.
```

--------------------------------

### Define Action and ActionEvent structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/common_types.rs.html

Structures for dispatching server-side events or executing local client-side functions.

```rust
/// An event to dispatch to the server.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionEvent {
    /// The name of the action to dispatch.
    pub name: String,

    /// Key-value pairs for the action context.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub context: Option<serde_json::Value>,
}

/// Defines an interaction handler: either a server-side event or a local function call.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Action {
    /// Triggers a server-side event.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub event: Option<ActionEvent>,

    /// Executes a local client-side function.
    #[serde(rename = "functionCall", skip_serializing_if = "Option::is_none")]
    pub function_call: Option<FunctionCall>,
}
```

--------------------------------

### Define library modules

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/lib.rs.html?search=

Exposes the common, v08, and v09 modules within the library crate.

```rust
pub mod common;
pub mod v08;
pub mod v09;
```

--------------------------------

### Define Action and ActionEvent structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/common_types.rs.html?search=

Structures for dispatching server-side events or executing client-side function calls.

```rust
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionEvent {
    /// The name of the action to dispatch.
    pub name: String,

    /// Key-value pairs for the action context.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub context: Option<serde_json::Value>,
}

/// Defines an interaction handler: either a server-side event or a local function call.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Action {
    /// Triggers a server-side event.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub event: Option<ActionEvent>,

    /// Executes a local client-side function.
    #[serde(rename = "functionCall", skip_serializing_if = "Option::is_none")]
    pub function_call: Option<FunctionCall>,
}
```

--------------------------------

### Define ClientDataModel struct

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/client_data_model.rs.html

Defines the schema for the client data model, including versioning and surface data mapping.

```rust
use std::collections::HashMap;

use serde::{Deserialize, Serialize};

/// Schema for attaching the client data model to transport metadata.
/// Placed in the `a2uiClientDataModel` field of the metadata.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ClientDataModel {
    /// Protocol version — always `"v0.9"`.
    pub version: String,

    /// A map of surface IDs to their current data models.
    pub surfaces: HashMap<String, serde_json::Value>,
}
```

--------------------------------

### Define Catalog and Function structures in Rust

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/catalog.rs.html?search=u32+-%3E+bool

Structures for representing a catalog of UI components and functions, utilizing Serde for JSON serialization and deserialization.

```rust
1use serde::{Deserialize, Serialize};

use super::common_types::FunctionReturnType;

/// A collection of component and function definitions that make up a catalog.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Catalog {
    /// Unique identifier for this catalog.
    #[serde(rename = "catalogId")]
    pub catalog_id: String,

    /// Definitions for UI components supported by this catalog.
    /// Each key is a component type name, each value is its JSON Schema.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub components: Option<serde_json::Value>,

    /// Definitions for functions supported by this catalog.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub functions: Option<Vec<FunctionDefinition>>,

    /// Theme schema — each key is a theme property name, each value is its JSON Schema.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub theme: Option<serde_json::Value>,
}

/// Describes a function's interface within a catalog.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FunctionDefinition {
    /// The unique name of the function.
    pub name: String,

    /// A human-readable description of what the function does.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// A JSON Schema describing the expected arguments.
    pub parameters: serde_json::Value,

    /// The type of value this function returns.
    #[serde(rename = "returnType")]
    pub return_type: FunctionReturnType,
}
```

--------------------------------

### ClientCapabilitiesV09 Struct Definition

Source: https://docs.rs/a2ui-types/latest/a2ui_types/v09/capabilities/struct.ClientCapabilitiesV09.html

The primary structure representing client capabilities for version 0.9.

```rust
pub struct ClientCapabilitiesV09 {
    pub supported_catalog_ids: Vec<String>,
    pub inline_catalogs: Option<Vec<Catalog>>,
}
```

--------------------------------

### ClientToServerMessage and UserAction Structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/client_to_server.rs.html?search=

Defines the message envelope and the user action payload for v0.8 client-to-server communication.

```rust
1use serde::{Deserialize, Serialize};

use crate::common::SurfaceId;

/// A single client-to-server event message in v0.8.
/// Must contain exactly one of `user_action` or `error`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ClientToServerMessage {
    /// Reports a user-initiated action from a component.
    #[serde(rename = "userAction", skip_serializing_if = "Option::is_none")]
    pub user_action: Option<UserAction>,

    /// Reports a client-side error.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<serde_json::Value>,
}

/// A user-initiated action event in v0.8.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct UserAction {
    /// The name of the action, taken from the component's action.name property.
    pub name: String,

    /// The ID of the surface where the event originated.
    #[serde(rename = "surfaceId")]
    pub surface_id: SurfaceId,

    /// The ID of the component that triggered the event.
    #[serde(rename = "sourceComponentId")]
    pub source_component_id: String,

    /// An ISO 8601 timestamp of when the event occurred.
    pub timestamp: String,

    /// Key-value pairs from the component's action.context, after resolving all data bindings.
    pub context: serde_json::Value,
}
```

--------------------------------

### SurfaceId::new

Source: https://docs.rs/a2ui-types/latest/a2ui_types/common/struct.SurfaceId.html?search=u32+-%3E+bool

Creates a new instance of SurfaceId from a string-like value.

```APIDOC
## pub fn new(id: impl Into<String>) -> Self

### Description
Creates a new SurfaceId instance using the provided identifier.

### Parameters
- **id** (impl Into<String>) - Required - The identifier string to wrap.
```

--------------------------------

### Define Specification Version

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/common.rs.html?search=std%3A%3Avec

Enumeration representing supported A2UI specification versions with display formatting.

```rust
/// The A2UI spec version this library supports.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SpecVersion {
    V0_8,
    V0_9,
}

impl std::fmt::Display for SpecVersion {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            SpecVersion::V0_8 => write!(f, "v0.8"),
            SpecVersion::V0_9 => write!(f, "v0.9"),
        }
    }
}
```

--------------------------------

### CatalogId::new

Source: https://docs.rs/a2ui-types/latest/a2ui_types/common/struct.CatalogId.html?search=u32+-%3E+bool

Creates a new instance of CatalogId from a string-like input.

```APIDOC
## pub fn new(id: impl Into<String>) -> Self

### Description
Creates a new CatalogId instance using the provided identifier.

### Parameters
- **id** (impl Into<String>) - Required - The identifier string for the catalog.
```

--------------------------------

### ClientCapabilities Struct Definition

Source: https://docs.rs/a2ui-types/latest/a2ui_types/v09/capabilities/struct.ClientCapabilities.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The primary structure used to encapsulate version 0.9 client capabilities.

```rust
pub struct ClientCapabilities {
    pub v09: ClientCapabilitiesV09,
}
```

--------------------------------

### Define ServerCapabilities struct

Source: https://docs.rs/a2ui-types/latest/a2ui_types/v09/capabilities/struct.ServerCapabilities.html

The structure definition for ServerCapabilities, containing the v09 field.

```rust
pub struct ServerCapabilities {
    pub v09: ServerCapabilitiesV09,
}
```

--------------------------------

### Define Specification Version

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/common.rs.html?search=u32+-%3E+bool

SpecVersion tracks supported A2UI versions and implements Display for string formatting.

```rust
84/// The A2UI spec version this library supports.
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
86pub enum SpecVersion {
87    V0_8,
88    V0_9,
89}
90
91impl std::fmt::Display for SpecVersion {
92    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
93        match self {
94            SpecVersion::V0_8 => write!(f, "v0.8"),
95            SpecVersion::V0_9 => write!(f, "v0.9"),
96        }
97    }
98}
```

--------------------------------

### Define Client-to-Server Message Structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/client_to_server.rs.html?search=u32+-%3E+bool

Defines the core message envelope and the specific structures for actions and errors in the v0.9 protocol.

```rust
use serde::{Deserialize, Serialize};

use crate::common::SurfaceId;

/// A single client-to-server message in v0.9.
/// Must contain `version` and exactly one of `action` or `error`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ClientToServerMessage {
    /// Protocol version — always `"v0.9"`.
    pub version: String,

    /// Reports a user-initiated action from a component.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub action: Option<ActionMessage>,

    /// Reports a client-side error.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<ErrorMessage>,
}

/// A user-initiated action event in v0.9.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionMessage {
    /// The name of the action.
    pub name: String,

    /// The ID of the surface where the action originated.
    #[serde(rename = "surfaceId")]
    pub surface_id: SurfaceId,

    /// The ID of the component that triggered the action.
    #[serde(rename = "sourceComponentId")]
    pub source_component_id: String,

    /// An ISO 8601 timestamp of when the event occurred.
    pub timestamp: String,

    /// Key-value pairs from the component's action context, after resolving data bindings.
    pub context: serde_json::Value,
}

/// A client-side error report in v0.9.
/// Supports both `VALIDATION_FAILED` and generic errors.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ErrorMessage {
    /// The error code (e.g., `"VALIDATION_FAILED"`).
    pub code: String,

    /// The ID of the surface where the error occurred.
    #[serde(rename = "surfaceId")]
    pub surface_id: SurfaceId,

    /// A short description of the error.
    pub message: String,

    /// For `VALIDATION_FAILED`: the JSON pointer to the field that failed validation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
}
```

--------------------------------

### ActionMessage Struct Definition

Source: https://docs.rs/a2ui-types/latest/a2ui_types/v09/client_to_server/struct.ActionMessage.html?search=

The core data structure for representing user-initiated action events in v0.9.

```rust
pub struct ActionMessage {
    pub name: String,
    pub surface_id: SurfaceId,
    pub source_component_id: String,
    pub timestamp: String,
    pub context: Value,
}
```

--------------------------------

### Define Client-to-Server Message Structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/client_to_server.rs.html

The primary message structure and its associated action and error types for v0.9 protocol communication.

```rust
1use serde::{Deserialize, Serialize};
2
3use crate::common::SurfaceId;
4
5/// A single client-to-server message in v0.9.
6/// Must contain `version` and exactly one of `action` or `error`.
7#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
8#[serde(deny_unknown_fields)]
9pub struct ClientToServerMessage {
10    /// Protocol version — always `"v0.9"`.
11    pub version: String,
12
13    /// Reports a user-initiated action from a component.
14    #[serde(skip_serializing_if = "Option::is_none")]
15    pub action: Option<ActionMessage>,
16
17    /// Reports a client-side error.
18    #[serde(skip_serializing_if = "Option::is_none")]
19    pub error: Option<ErrorMessage>,
20}
21
22/// A user-initiated action event in v0.9.
23#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
24pub struct ActionMessage {
25    /// The name of the action.
26    pub name: String,
27
28    /// The ID of the surface where the action originated.
29    #[serde(rename = "surfaceId")]
30    pub surface_id: SurfaceId,
31
32    /// The ID of the component that triggered the action.
33    #[serde(rename = "sourceComponentId")]
34    pub source_component_id: String,
35
36    /// An ISO 8601 timestamp of when the event occurred.
37    pub timestamp: String,
38
39    /// Key-value pairs from the component's action context, after resolving data bindings.
40    pub context: serde_json::Value,
41}
42
43/// A client-side error report in v0.9.
44/// Supports both `VALIDATION_FAILED` and generic errors.
45#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
46pub struct ErrorMessage {
47    /// The error code (e.g., `"VALIDATION_FAILED"`).
48    pub code: String,
49
50    /// The ID of the surface where the error occurred.
51    #[serde(rename = "surfaceId")]
52    pub surface_id: SurfaceId,
53
54    /// A short description of the error.
55    pub message: String,
56
57    /// For `VALIDATION_FAILED`: the JSON pointer to the field that failed validation.
58    #[serde(skip_serializing_if = "Option::is_none")]
59    pub path: Option<String>,
60}
```

--------------------------------

### Define Server-to-Client Message Structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/server_to_client.rs.html

The core message envelope and associated structs for the v0.8 A2UI protocol, utilizing Serde for JSON serialization.

```rust
use serde::{Deserialize, Serialize};

use crate::common::SurfaceId;

use super::data_model::DataEntry;

/// A single server-to-client message in the v0.8 A2UI JSONL stream.
/// Each message must contain exactly one of the four message types.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ServerToClientMessage {
    /// Signals the client to begin rendering a surface.
    #[serde(rename = "beginRendering", skip_serializing_if = "Option::is_none")]
    pub begin_rendering: Option<BeginRendering>,

    /// Updates a surface with a new set of components.
    #[serde(rename = "surfaceUpdate", skip_serializing_if = "Option::is_none")]
    pub surface_update: Option<SurfaceUpdate>,

    /// Updates the data model for a surface.
    #[serde(rename = "dataModelUpdate", skip_serializing_if = "Option::is_none")]
    pub data_model_update: Option<DataModelUpdate>,

    /// Signals the client to delete a surface.
    #[serde(rename = "deleteSurface", skip_serializing_if = "Option::is_none")]
    pub delete_surface: Option<DeleteSurface>,
}

/// Signals the client to begin rendering a surface with a root component and styles.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BeginRendering {
    /// The unique identifier for the UI surface to be rendered.
    #[serde(rename = "surfaceId")]
    pub surface_id: SurfaceId,

    /// The identifier of the component catalog to use for this surface.
    /// If omitted, defaults to the standard catalog for v0.8.
    #[serde(rename = "catalogId", skip_serializing_if = "Option::is_none")]
    pub catalog_id: Option<String>,

    /// The ID of the root component to render.
    pub root: String,

    /// Styling information for the UI.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub styles: Option<serde_json::Value>,
}

/// Updates a surface with a new set of components.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SurfaceUpdate {
    /// The unique identifier for the UI surface to be updated.
    #[serde(rename = "surfaceId", skip_serializing_if = "Option::is_none")]
    pub surface_id: Option<SurfaceId>,

    /// A list of component instances.
    pub components: Vec<ComponentInstance>,
}

/// A single component instance in the adjacency list.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ComponentInstance {
    /// Unique identifier for this component.
    pub id: String,

    /// The relative weight within a Row or Column (CSS flex-grow).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub weight: Option<f64>,

    /// A wrapper object containing exactly one key (the component type name)
    /// and its properties as the value. Generic because component types are
    /// defined by the catalog, not the protocol.
    pub component: serde_json::Value,
}

/// Updates the data model for a surface.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DataModelUpdate {
    /// The unique identifier for the UI surface this data model update applies to.
    #[serde(rename = "surfaceId")]
    pub surface_id: SurfaceId,

    /// An optional path to a location within the data model.
    /// If omitted, the update applies to the root.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,

    /// An array of data entries arranged as an adjacency list.
    pub contents: Vec<DataEntry>,
}

/// Signals the client to delete a surface.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DeleteSurface {
    /// The unique identifier for the UI surface to be deleted.
    #[serde(rename = "surfaceId")]
    pub surface_id: SurfaceId,
}
```

--------------------------------

### Define BoundValue and helper methods

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/data_model.rs.html

Represents a value that can be either a literal or a path to the data model. Use the provided implementation methods to construct instances from literals or paths.

```rust
use serde::{Deserialize, Serialize};

/// A value that can be either a literal or bound to the data model.
/// Used in v0.8 for component properties like `text`, `label`, etc.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BoundValue {
    /// A static string value.
    #[serde(rename = "literalString", skip_serializing_if = "Option::is_none")]
    pub literal_string: Option<String>,

    /// A static number value.
    #[serde(rename = "literalNumber", skip_serializing_if = "Option::is_none")]
    pub literal_number: Option<f64>,

    /// A static boolean value.
    #[serde(rename = "literalBoolean", skip_serializing_if = "Option::is_none")]
    pub literal_boolean: Option<bool>,

    /// A static array value.
    #[serde(rename = "literalArray", skip_serializing_if = "Option::is_none")]
    pub literal_array: Option<Vec<serde_json::Value>>,

    /// A JSON Pointer path to a value in the data model.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
}

impl BoundValue {
    /// Create a BoundValue from a literal string.
    pub fn from_literal_string(s: impl Into<String>) -> Self {
        Self {
            literal_string: Some(s.into()),
            literal_number: None,
            literal_boolean: None,
            literal_array: None,
            path: None,
        }
    }

    /// Create a BoundValue from a data model path.
    pub fn from_path(path: impl Into<String>) -> Self {
        Self {
            literal_string: None,
            literal_number: None,
            literal_boolean: None,
            literal_array: None,
            path: Some(path.into()),
        }
    }

    /// Create a BoundValue with both a path and a literal string (initialization shorthand).
    pub fn from_path_with_default(path: impl Into<String>, default: impl Into<String>) -> Self {
        Self {
            literal_string: Some(default.into()),
            literal_number: None,
            literal_boolean: None,
            literal_array: None,
            path: Some(path.into()),
        }
    }
}
```

--------------------------------

### Define Surface, Component, and Catalog Identifiers

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/common.rs.html

Transparent wrappers for string-based identifiers that implement standard traits for serialization and conversion.

```rust
1use serde::{Deserialize, Serialize};

/// Unique identifier for a UI surface.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct SurfaceId(pub String);

impl SurfaceId {
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl From<&str> for SurfaceId {
    fn from(s: &str) -> Self {
        Self(s.to_owned())
    }
}

impl From<String> for SurfaceId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

/// Unique identifier for a component within a surface.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ComponentId(pub String);

impl ComponentId {
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl From<&str> for ComponentId {
    fn from(s: &str) -> Self {
        Self(s.to_owned())
    }
}

impl From<String> for ComponentId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

/// Unique identifier for a component catalog.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct CatalogId(pub String);

impl CatalogId {
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl From<&str> for CatalogId {
    fn from(s: &str) -> Self {
        Self(s.to_owned())
    }
}

impl From<String> for CatalogId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

/// The A2UI spec version this library supports.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SpecVersion {
    V0_8,
    V0_9,
}

impl std::fmt::Display for SpecVersion {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            SpecVersion::V0_8 => write!(f, "v0.8"),
            SpecVersion::V0_9 => write!(f, "v0.9"),
        }
    }
}
```

--------------------------------

### CatalogId::new

Source: https://docs.rs/a2ui-types/latest/a2ui_types/common/struct.CatalogId.html?search=

Creates a new instance of CatalogId from a string-like value.

```APIDOC
## pub fn new(id: impl Into<String>) -> Self

### Description
Creates a new CatalogId instance from any type that can be converted into a String.

### Parameters
- **id** (impl Into<String>) - Required - The identifier string for the catalog.
```

--------------------------------

### CreateSurface Struct Definition

Source: https://docs.rs/a2ui-types/latest/a2ui_types/v09/server_to_client/struct.CreateSurface.html

Defines the structure for signaling the client to create and render a new UI surface.

```rust
pub struct CreateSurface {
    pub surface_id: SurfaceId,
    pub catalog_id: String,
    pub theme: Option<Value>,
    pub send_data_model: Option<bool>,
}
```

--------------------------------

### Define Dynamic Data Binding and Function Call Types

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/common_types.rs.html

Structures for referencing data model paths and invoking client-side functions with optional return type validation.

```rust
1use serde::{Deserialize, Serialize};
2
3use crate::common::ComponentId;
4
5// ---------------------------------------------------------------------------
6// Dynamic value types — the core of v0.9 data binding
7// ---------------------------------------------------------------------------
8
9/// A data binding reference to the data model via JSON Pointer.
10#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
11#[serde(deny_unknown_fields)]
12pub struct DataBinding {
13    /// A JSON Pointer path to a value in the data model.
14    pub path: String,
15}
16
17/// Invokes a named function on the client.
18#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
19pub struct FunctionCall {
20    /// The name of the function to call.
21    pub call: String,
22
23    /// Arguments passed to the function.
24    #[serde(skip_serializing_if = "Option::is_none")]
25    pub args: Option<serde_json::Value>,
26
27    /// The expected return type of the function call.
28    #[serde(rename = "returnType", skip_serializing_if = "Option::is_none")]
29    pub return_type: Option<FunctionReturnType>,
30}
31
32/// Possible return types for a function call.
33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(rename_all = "lowercase")]
35pub enum FunctionReturnType {
36    String,
37    Number,
38    Boolean,
39    Array,
40    Object,
41    Any,
42    Void,
43}
```

--------------------------------

### Define ClientToServerMessage Struct

Source: https://docs.rs/a2ui-types/latest/a2ui_types/v09/client_to_server/struct.ClientToServerMessage.html

The structure definition for a client-to-server message, containing the protocol version and optional action or error fields.

```rust
pub struct ClientToServerMessage {
    pub version: String,
    pub action: Option<ActionMessage>,
    pub error: Option<ErrorMessage>,
}
```

--------------------------------

### Define Children and ChildTemplate structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v08/data_model.rs.html

Manages component children via either an explicit list or a dynamic template. The template requires a data binding path and a component ID.

```rust
/// Defines the children of a container component.
/// Must contain exactly one of `explicit_list` or `template`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Children {
    /// An ordered list of component IDs that are direct children.
    #[serde(rename = "explicitList", skip_serializing_if = "Option::is_none")]
    pub explicit_list: Option<Vec<String>>,

    /// A template for rendering dynamic lists of children.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub template: Option<ChildTemplate>,
}

impl Children {
    /// Create children from an explicit list of component IDs.
    pub fn from_explicit_list(ids: Vec<String>) -> Self {
        Self {
            explicit_list: Some(ids),
            template: None,
        }
    }

    /// Create children from a template.
    pub fn from_template(template: ChildTemplate) -> Self {
        Self {
            explicit_list: None,
            template: Some(template),
        }
    }
}

/// A template for generating dynamic lists of children from a data-bound list.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ChildTemplate {
    /// The path to a list in the data model.
    #[serde(rename = "dataBinding")]
    pub data_binding: String,

    /// The ID of the component to use as a template for each item.
    #[serde(rename = "componentId")]
    pub component_id: String,
}
```

--------------------------------

### ComponentId::as_str

Source: https://docs.rs/a2ui-types/latest/a2ui_types/common/struct.ComponentId.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the string representation of the ComponentId.

```APIDOC
## pub fn as_str(&self) -> &str

### Description
Returns the underlying string slice of the `ComponentId`.
```

--------------------------------

### ComponentId::new

Source: https://docs.rs/a2ui-types/latest/a2ui_types/common/struct.ComponentId.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new ComponentId instance from a type that can be converted into a String.

```APIDOC
## pub fn new(id: impl Into<String>) -> Self

### Description
Creates a new instance of `ComponentId` using the provided identifier.

### Parameters
- **id** (impl Into<String>) - Required - The identifier string for the component.
```

--------------------------------

### Define Catalog and FunctionDefinition structures

Source: https://docs.rs/a2ui-types/latest/src/a2ui_types/v09/catalog.rs.html?search=

Defines the Catalog struct for component collections and the FunctionDefinition struct for function interfaces.

```rust
use serde::{Deserialize, Serialize};

use super::common_types::FunctionReturnType;

/// A collection of component and function definitions that make up a catalog.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Catalog {
    /// Unique identifier for this catalog.
    #[serde(rename = "catalogId")]
    pub catalog_id: String,

    /// Definitions for UI components supported by this catalog.
    /// Each key is a component type name, each value is its JSON Schema.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub components: Option<serde_json::Value>,

    /// Definitions for functions supported by this catalog.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub functions: Option<Vec<FunctionDefinition>>,

    /// Theme schema — each key is a theme property name, each value is its JSON Schema.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub theme: Option<serde_json::Value>,
}

/// Describes a function's interface within a catalog.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FunctionDefinition {
    /// The unique name of the function.
    pub name: String,

    /// A human-readable description of what the function does.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// A JSON Schema describing the expected arguments.
    pub parameters: serde_json::Value,

    /// The type of value this function returns.
    #[serde(rename = "returnType")]
    pub return_type: FunctionReturnType,
}
```
Tokens:
Raw