Skip to content

docs(schema): mark DefaultOnNull lists with an x-deserialize hint #2569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benbrandt merged 1 commit into from
Oct 27, 2026
Merged

docs(schema): mark DefaultOnNull lists with an x-deserialize hint #2569

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions agent-client-protocol-schema/src/v1/agent.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -719,11 +719,13 @@ pub struct AuthMethodTerminal {
pub description: Option<String>,
/// Additional arguments to append to the configured agent invocation for terminal auth.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub args: Vec<String>,
/// Additional environment variables to set on the configured agent invocation for terminal auth.
/// These values override same-named variables in the base launch configuration.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "HashMap::is_empty")]
pub env: HashMap<String, String>,
/// The _meta property is reserved by ACP to allow clients and agents to attach additional
Expand Down Expand Up @@ -807,10 +809,12 @@ pub struct NewSessionRequest {
/// remains the base for relative paths. When omitted or empty, no
/// additional roots are activated for the new session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub additional_directories: Vec<PathBuf>,
/// List of MCP (Model Context Protocol) servers the agent should connect to.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
pub mcp_servers: Vec<McpServer>,
/// **UNSTABLE**
///
Expand Down Expand Up @@ -987,6 +991,7 @@ impl NewSessionResponse {
pub struct LoadSessionRequest {
/// List of MCP servers to connect to for this session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
pub mcp_servers: Vec<McpServer>,
/// The working directory for this session. Must be an absolute path.
pub cwd: PathBuf,
Expand All @@ -997,6 +1002,7 @@ pub struct LoadSessionRequest {
/// session. It may differ from any previously used or reported list as long as
/// the request `cwd` matches the session's `cwd`.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub additional_directories: Vec<PathBuf>,
/// The ID of the session to load.
Expand Down Expand Up @@ -1184,10 +1190,12 @@ pub struct ForkSessionRequest {
/// this is the complete resulting additional-root list for the forked
/// session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub additional_directories: Vec<PathBuf>,
/// List of MCP servers to connect to for this session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mcp_servers: Vec<McpServer>,
/// **UNSTABLE**
Expand Down Expand Up @@ -1381,10 +1389,12 @@ pub struct ResumeSessionRequest {
/// session. It may differ from any previously used or reported list as long as
/// the request `cwd` matches the session's `cwd`.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub additional_directories: Vec<PathBuf>,
/// List of MCP servers to connect to for this session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mcp_servers: Vec<McpServer>,
/// **UNSTABLE**
Expand Down Expand Up @@ -2790,6 +2800,7 @@ pub struct McpServerHttp {
pub url: String,
/// HTTP headers to set when making requests to the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
pub headers: Vec<HttpHeader>,
/// The _meta property is reserved by ACP to allow clients and agents to attach additional
/// metadata to their interactions. Implementations MUST NOT make assumptions about values at
Expand Down Expand Up @@ -2848,6 +2859,7 @@ pub struct McpServerSse {
pub url: String,
/// HTTP headers to set when making requests to the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
pub headers: Vec<HttpHeader>,
/// The _meta property is reserved by ACP to allow clients and agents to attach additional
/// metadata to their interactions. Implementations MUST NOT make assumptions about values at
Expand Down Expand Up @@ -2990,9 +3002,11 @@ pub struct McpServerStdio {
pub command: PathBuf,
/// Command-line arguments to pass to the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
pub args: Vec<String>,
/// Environment variables to set when launching the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
pub env: Vec<EnvVariable>,
/// The _meta property is reserved by ACP to allow clients and agents to attach additional
/// metadata to their interactions. Implementations MUST NOT make assumptions about values at
Expand Down
2 changes: 2 additions & 0 deletions agent-client-protocol-schema/src/v1/client.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2702,10 +2702,12 @@ pub struct CreateTerminalRequest {
pub command: String,
/// Array of command arguments.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub args: Vec<String>,
/// Environment variables for the command.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub env: Vec<EnvVariable>,
/// Working directory for the command. Must be an absolute path.
Expand Down
11 changes: 11 additions & 0 deletions agent-client-protocol-schema/src/v2/agent.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -751,12 +751,14 @@ pub struct AuthMethodTerminal {
pub description: Option<String>,
/// Additional arguments to append to the configured agent invocation for terminal auth.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub args: Vec<String>,
/// Additional environment variables to set on the configured agent invocation for terminal auth.
/// Names MUST be unique. These values override same-named variables in the
/// base launch configuration.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub env: Vec<EnvVariable>,
/// The _meta property is reserved by ACP to allow clients and agents to attach additional
Expand Down Expand Up @@ -841,10 +843,12 @@ pub struct NewSessionRequest {
/// remains the base for relative paths. When omitted or empty, no
/// additional roots are activated for the new session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub additional_directories: Vec<AbsolutePath>,
/// List of MCP (Model Context Protocol) servers the agent should connect to.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mcp_servers: Vec<McpServer>,
/// **UNSTABLE**
Expand Down Expand Up @@ -1041,10 +1045,12 @@ pub struct ForkSessionRequest {
/// this is the complete resulting additional-root list for the forked
/// session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub additional_directories: Vec<AbsolutePath>,
/// List of MCP servers to connect to for this session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mcp_servers: Vec<McpServer>,
/// **UNSTABLE**
Expand Down Expand Up @@ -1237,10 +1243,12 @@ pub struct ResumeSessionRequest {
/// session. It may differ from any previously used or reported list as long as
/// the request `cwd` matches the session's `cwd`.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub additional_directories: Vec<AbsolutePath>,
/// List of MCP servers to connect to for this session.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mcp_servers: Vec<McpServer>,
/// Inclusive cursor describing where conversation replay should begin.
Expand Down Expand Up @@ -2953,6 +2961,7 @@ pub struct McpServerHttp {
pub url: String,
/// HTTP headers to set when making requests to the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub headers: Vec<HttpHeader>,
/// The _meta property is reserved by ACP to allow clients and agents to attach additional
Expand Down Expand Up @@ -3096,10 +3105,12 @@ pub struct McpServerStdio {
pub command: AbsolutePath,
/// Command-line arguments to pass to the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub args: Vec<String>,
/// Environment variables to set when launching the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
#[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub env: Vec<EnvVariable>,
/// The _meta property is reserved by ACP to allow clients and agents to attach additional
Expand Down
40 changes: 27 additions & 13 deletions schema/v1/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1172,14 +1172,16 @@
"type": "array",
"items": {
"type": "string"
}
},
"x-deserialize-default-on-null": true
},
"env": {
"description": "Environment variables for the command.",
"type": "array",
"items": {
"$ref": "#/$defs/EnvVariable"
}
},
"x-deserialize-default-on-null": true
},
"cwd": {
"description": "Working directory for the command. Must be an absolute path.",
Expand Down Expand Up @@ -2751,11 +2753,13 @@
"type": "array",
"items": {
"type": "string"
}
},
"x-deserialize-default-on-null": true
},
"env": {
"description": "Additional environment variables to set on the configured agent invocation for terminal auth.\nThese values override same-named variables in the base launch configuration.",
"type": "object",
"x-deserialize-default-on-null": true,
"additionalProperties": {
"type": "string"
}
Expand Down Expand Up @@ -4990,14 +4994,16 @@
"type": "array",
"items": {
"type": "string"
}
},
"x-deserialize-default-on-null": true
},
"mcpServers": {
"description": "List of MCP (Model Context Protocol) servers the agent should connect to.",
"type": "array",
"items": {
"$ref": "#/$defs/McpServer"
}
},
"x-deserialize-default-on-null": true
},
"_meta": {
"description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)",
Expand Down Expand Up @@ -5094,7 +5100,8 @@
"type": "array",
"items": {
"$ref": "#/$defs/HttpHeader"
}
},
"x-deserialize-default-on-null": true
},
"_meta": {
"description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)",
Expand Down Expand Up @@ -5122,7 +5129,8 @@
"type": "array",
"items": {
"$ref": "#/$defs/HttpHeader"
}
},
"x-deserialize-default-on-null": true
},
"_meta": {
"description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)",
Expand Down Expand Up @@ -5150,14 +5158,16 @@
"type": "array",
"items": {
"type": "string"
}
},
"x-deserialize-default-on-null": true
},
"env": {
"description": "Environment variables to set when launching the MCP server.",
"type": "array",
"items": {
"$ref": "#/$defs/EnvVariable"
}
},
"x-deserialize-default-on-null": true
},
"_meta": {
"description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)",
Expand All @@ -5177,7 +5187,8 @@
"type": "array",
"items": {
"$ref": "#/$defs/McpServer"
}
},
"x-deserialize-default-on-null": true
},
"cwd": {
"description": "The working directory for this session. Must be an absolute path.",
Expand All @@ -5188,7 +5199,8 @@
"type": "array",
"items": {
"type": "string"
}
},
"x-deserialize-default-on-null": true
},
"sessionId": {
"description": "The ID of the session to load.",
Expand Down Expand Up @@ -5275,14 +5287,16 @@
"type": "array",
"items": {
"type": "string"
}
},
"x-deserialize-default-on-null": true
},
"mcpServers": {
"description": "List of MCP servers to connect to for this session.",
"type": "array",
"items": {
"$ref": "#/$defs/McpServer"
}
},
"x-deserialize-default-on-null": true
},
"_meta": {
"description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)",
Expand Down
Loading
Loading