wip; add jsonschema for config.toml

codex-rs/core/Cargo.toml

@@ -58,6 +58,7 @@ reqwest = { workspace = true, features = ["json", "stream"] }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 serde_yaml = { workspace = true }
+schemars = { workspace = true }
 sha1 = { workspace = true }
 sha2 = { workspace = true }
 shlex = { workspace = true }

codex-rs/core/src/auth/storage.rs

@@ -1,5 +1,6 @@
 use chrono::DateTime;
 use chrono::Utc;
+use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Serialize;
 use sha2::Digest;
@@ -21,7 +22,7 @@ use codex_keyring_store::DefaultKeyringStore;
 use codex_keyring_store::KeyringStore;
 
 /// Determine where Codex should store CLI auth credentials.
-#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
 #[serde(rename_all = "lowercase")]
 pub enum AuthCredentialsStoreMode {
     #[default]

codex-rs/core/src/config/mod.rs

@@ -43,6 +43,7 @@ use codex_rmcp_client::OAuthCredentialsStoreMode;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use codex_utils_absolute_path::AbsolutePathBufGuard;
 use dirs::home_dir;
+use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Serialize;
 use similar::DiffableStr;
@@ -61,6 +62,7 @@ use toml_edit::DocumentMut;
 mod constraint;
 pub mod edit;
 pub mod profile;
+pub mod schema;
 pub mod service;
 pub mod types;
 pub use constraint::Constrained;
@@ -682,7 +684,7 @@ pub fn set_default_oss_provider(codex_home: &Path, provider: &str) -> std::io::R
 }
 
 /// Base config deserialized from ~/.codex/config.toml.
-#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)]
 pub struct ConfigToml {
     /// Optional override of model selection.
     pub model: Option<String>,
@@ -741,6 +743,7 @@ pub struct ConfigToml {
 
     /// Definition for MCP servers that Codex can reach out to for tool calls.
     #[serde(default)]
+    #[schemars(schema_with = "crate::config::schema::mcp_servers_schema")]
     pub mcp_servers: HashMap<String, McpServerConfig>,
 
     /// Preferred backend for storing MCP OAuth credentials.
@@ -808,6 +811,7 @@ pub struct ConfigToml {
 
     /// Centralized feature flags (new). Prefer this over individual toggles.
     #[serde(default)]
+    #[schemars(schema_with = "crate::config::schema::features_schema")]
     pub features: Option<FeaturesToml>,
 
     /// Settings for ghost snapshots (used for undo).
@@ -881,7 +885,7 @@ impl From<ConfigToml> for UserSavedConfig {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
 pub struct ProjectConfig {
     pub trust_level: Option<TrustLevel>,
 }
@@ -896,7 +900,7 @@ impl ProjectConfig {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)]
 pub struct ToolsToml {
     #[serde(default, alias = "web_search_request")]
     pub web_search: Option<bool>,
@@ -915,7 +919,7 @@ impl From<ToolsToml> for Tools {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
 pub struct GhostSnapshotToml {
     /// Exclude untracked files larger than this many bytes from ghost snapshots.
     #[serde(alias = "ignore_untracked_files_over_bytes")]

codex-rs/core/src/config/profile.rs

@@ -1,4 +1,5 @@
 use codex_utils_absolute_path::AbsolutePathBuf;
+use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Serialize;
 
@@ -10,7 +11,7 @@ use codex_protocol::openai_models::ReasoningEffort;
 
 /// Collection of common configuration options that a user can define as a unit
 /// in `config.toml`.
-#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct ConfigProfile {
     pub model: Option<String>,
     /// The key in the `model_providers` map identifying the
@@ -32,6 +33,7 @@ pub struct ConfigProfile {
     pub analytics: Option<crate::config::types::AnalyticsConfigToml>,
     /// Optional feature toggles scoped to this profile.
     #[serde(default)]
+    #[schemars(schema_with = "crate::config::schema::features_schema")]
     pub features: Option<crate::features::FeaturesToml>,
     pub oss_provider: Option<String>,
 }

codex-rs/core/src/config/schema.rs

@@ -0,0 +1,158 @@
+#[cfg(test)]
+use crate::config::ConfigToml;
+use crate::features::FEATURES;
+use schemars::JsonSchema;
+use schemars::r#gen::SchemaGenerator;
+#[cfg(test)]
+use schemars::r#gen::SchemaSettings;
+use schemars::schema::InstanceType;
+use schemars::schema::ObjectValidation;
+#[cfg(test)]
+use schemars::schema::RootSchema;
+use schemars::schema::Schema;
+use schemars::schema::SchemaObject;
+use schemars::schema::SubschemaValidation;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::HashMap;
+#[cfg(test)]
+use std::path::Path;
+
+#[cfg(test)]
+pub(crate) fn config_schema() -> RootSchema {
+    SchemaSettings::draft07()
+        .with(|settings| {
+            settings.option_add_null_type = false;
+        })
+        .into_generator()
+        .into_root_schema_for::<ConfigToml>()
+}
+
+#[cfg(test)]
+pub(crate) fn write_config_schema(out_path: &Path) -> anyhow::Result<()> {
+    let schema = config_schema();
+    let json = serde_json::to_vec_pretty(&schema)?;
+    std::fs::write(out_path, json)?;
+    Ok(())
+}
+
+pub(crate) fn features_schema(schema_gen: &mut SchemaGenerator) -> Schema {
+    let mut object = SchemaObject {
+        instance_type: Some(InstanceType::Object.into()),
+        ..Default::default()
+    };
+
+    let mut validation = ObjectValidation::default();
+    for feature in FEATURES {
+        validation
+            .properties
+            .insert(feature.key.to_string(), schema_gen.subschema_for::<bool>());
+    }
+    validation.additional_properties = Some(Box::new(schema_gen.subschema_for::<bool>()));
+    object.object = Some(Box::new(validation));
+
+    Schema::Object(object)
+}
+
+pub(crate) fn mcp_servers_schema(schema_gen: &mut SchemaGenerator) -> Schema {
+    let mut object = SchemaObject {
+        instance_type: Some(InstanceType::Object.into()),
+        ..Default::default()
+    };
+
+    let validation = ObjectValidation {
+        additional_properties: Some(Box::new(mcp_server_schema(schema_gen))),
+        ..Default::default()
+    };
+    object.object = Some(Box::new(validation));
+
+    Schema::Object(object)
+}
+
+fn mcp_server_schema(schema_gen: &mut SchemaGenerator) -> Schema {
+    let server = SchemaObject {
+        subschemas: Some(Box::new(SubschemaValidation {
+            one_of: Some(vec![
+                schema_gen.subschema_for::<McpServerStdioSchema>(),
+                schema_gen.subschema_for::<McpServerStreamableHttpSchema>(),
+            ]),
+            ..Default::default()
+        })),
+        ..Default::default()
+    };
+    Schema::Object(server)
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+struct McpServerStdioSchema {
+    command: String,
+    #[serde(default)]
+    args: Option<Vec<String>>,
+    #[serde(default)]
+    env: Option<HashMap<String, String>>,
+    #[serde(default)]
+    env_vars: Option<Vec<String>>,
+    #[serde(default)]
+    cwd: Option<String>,
+    #[serde(default)]
+    enabled: Option<bool>,
+    #[serde(default)]
+    startup_timeout_sec: Option<f64>,
+    #[serde(default)]
+    startup_timeout_ms: Option<u64>,
+    #[serde(default)]
+    tool_timeout_sec: Option<f64>,
+    #[serde(default)]
+    enabled_tools: Option<Vec<String>>,
+    #[serde(default)]
+    disabled_tools: Option<Vec<String>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+struct McpServerStreamableHttpSchema {
+    url: String,
+    #[serde(default)]
+    bearer_token_env_var: Option<String>,
+    #[serde(default)]
+    http_headers: Option<HashMap<String, String>>,
+    #[serde(default)]
+    env_http_headers: Option<HashMap<String, String>>,
+    #[serde(default)]
+    enabled: Option<bool>,
+    #[serde(default)]
+    startup_timeout_sec: Option<f64>,
+    #[serde(default)]
+    startup_timeout_ms: Option<u64>,
+    #[serde(default)]
+    tool_timeout_sec: Option<f64>,
+    #[serde(default)]
+    enabled_tools: Option<Vec<String>>,
+    #[serde(default)]
+    disabled_tools: Option<Vec<String>>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn config_schema_matches_fixture() {
+        let schema = config_schema();
+        let schema_value = serde_json::to_value(schema).expect("serialize config schema");
+        let fixture_path = codex_utils_cargo_bin::find_resource!("../../docs/config.schema.json")
+            .expect("resolve config schema fixture path");
+        let fixture = std::fs::read_to_string(fixture_path).expect("read config schema fixture");
+        let fixture_value: serde_json::Value =
+            serde_json::from_str(&fixture).expect("parse config schema fixture");
+        assert_eq!(fixture_value, schema_value);
+    }
+
+    #[test]
+    #[ignore]
+    fn write_config_schema_fixture() {
+        let fixture_path = codex_utils_cargo_bin::find_resource!("../../docs/config.schema.json")
+            .expect("resolve config schema fixture path");
+        write_config_schema(&fixture_path).expect("write config schema fixture");
+    }
+}

codex-rs/core/src/config/types.rs

@@ -11,6 +11,7 @@ use std::path::PathBuf;
 use std::time::Duration;
 use wildmatch::WildMatchPattern;
 
+use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Deserializer;
 use serde::Serialize;
@@ -164,7 +165,7 @@ const fn default_enabled() -> bool {
     true
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
 #[serde(untagged, deny_unknown_fields, rename_all = "snake_case")]
 pub enum McpServerTransportConfig {
     /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
@@ -222,7 +223,7 @@ mod option_duration_secs {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq)]
+#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, JsonSchema)]
 pub enum UriBasedFileOpener {
     #[serde(rename = "vscode")]
     VsCode,
@@ -254,7 +255,7 @@ impl UriBasedFileOpener {
 }
 
 /// Settings that govern if and what will be written to `~/.codex/history.jsonl`.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 pub struct History {
     /// If true, history entries will not be written to disk.
     pub persistence: HistoryPersistence,
@@ -264,7 +265,7 @@ pub struct History {
     pub max_bytes: Option<usize>,
 }
 
-#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Default, JsonSchema)]
 #[serde(rename_all = "kebab-case")]
 pub enum HistoryPersistence {
     /// Save all history entries to disk.
@@ -277,7 +278,7 @@ pub enum HistoryPersistence {
 // ===== Analytics configuration =====
 
 /// Analytics settings loaded from config.toml. Fields are optional so we can apply defaults.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 pub struct AnalyticsConfigToml {
     /// When `false`, disables analytics across Codex product surfaces in this profile.
     pub enabled: Option<bool>,
@@ -291,7 +292,7 @@ pub struct FeedbackConfigToml {
 
 // ===== OTEL configuration =====
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
 #[serde(rename_all = "kebab-case")]
 pub enum OtelHttpProtocol {
     /// Binary payload
@@ -300,7 +301,7 @@ pub enum OtelHttpProtocol {
     Json,
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 #[serde(rename_all = "kebab-case")]
 pub struct OtelTlsConfig {
     pub ca_certificate: Option<AbsolutePathBuf>,
@@ -309,7 +310,7 @@ pub struct OtelTlsConfig {
 }
 
 /// Which OTEL exporter to use.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
 #[serde(rename_all = "kebab-case")]
 pub enum OtelExporterKind {
     None,
@@ -332,7 +333,7 @@ pub enum OtelExporterKind {
 }
 
 /// OTEL settings loaded from config.toml. Fields are optional so we can apply defaults.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 pub struct OtelConfigToml {
     /// Log user prompt in traces
     pub log_user_prompt: Option<bool>,
@@ -369,7 +370,7 @@ impl Default for OtelConfig {
     }
 }
 
-#[derive(Serialize, Debug, Clone, PartialEq, Eq, Deserialize)]
+#[derive(Serialize, Debug, Clone, PartialEq, Eq, Deserialize, JsonSchema)]
 #[serde(untagged)]
 pub enum Notifications {
     Enabled(bool),
@@ -387,7 +388,7 @@ impl Default for Notifications {
 /// Terminals generally encode both mouse wheels and trackpads as the same "scroll up/down" mouse
 /// button events, without a magnitude. This setting controls whether Codex uses a heuristic to
 /// infer wheel vs trackpad per stream, or forces a specific behavior.
-#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum ScrollInputMode {
     /// Infer wheel vs trackpad behavior per scroll stream.
@@ -405,7 +406,7 @@ impl Default for ScrollInputMode {
 }
 
 /// Collection of settings that are specific to the TUI.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 pub struct Tui {
     /// Enable desktop notifications from the TUI when the terminal is unfocused.
     /// Defaults to `true`.
@@ -544,7 +545,7 @@ const fn default_true() -> bool {
 /// Settings for notices we display to users via the tui and app-server clients
 /// (primarily the Codex IDE extension). NOTE: these are different from
 /// notifications - notices are warnings, NUX screens, acknowledgements, etc.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 pub struct Notice {
     /// Tracks whether the user has acknowledged the full access warning prompt.
     pub hide_full_access_warning: Option<bool>,
@@ -567,7 +568,7 @@ impl Notice {
     pub(crate) const TABLE_KEY: &'static str = "notice";
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 pub struct SandboxWorkspaceWrite {
     #[serde(default)]
     pub writable_roots: Vec<AbsolutePathBuf>,
@@ -590,7 +591,7 @@ impl From<SandboxWorkspaceWrite> for codex_app_server_protocol::SandboxSettings
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 #[serde(rename_all = "kebab-case")]
 pub enum ShellEnvironmentPolicyInherit {
     /// "Core" environment variables for the platform. On UNIX, this would
@@ -607,7 +608,7 @@ pub enum ShellEnvironmentPolicyInherit {
 
 /// Policy for building the `env` when spawning a process via either the
 /// `shell` or `local_shell` tool.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
 pub struct ShellEnvironmentPolicyToml {
     pub inherit: Option<ShellEnvironmentPolicyInherit>,
 

codex-rs/core/src/features.rs

@@ -8,6 +8,7 @@
 use crate::config::ConfigToml;
 use crate::config::profile::ConfigProfile;
 use codex_otel::OtelManager;
+use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Serialize;
 use std::collections::BTreeMap;
@@ -292,7 +293,7 @@ pub fn is_known_feature_key(key: &str) -> bool {
 }
 
 /// Deserializable features table for TOML.
-#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)]
 pub struct FeaturesToml {
     #[serde(flatten)]
     pub entries: BTreeMap<String, bool>,

codex-rs/core/src/model_provider_info.rs

@@ -12,6 +12,7 @@ use codex_app_server_protocol::AuthMode;
 use http::HeaderMap;
 use http::header::HeaderName;
 use http::header::HeaderValue;
+use schemars::JsonSchema;
 use serde::Deserialize;
 use serde::Serialize;
 use std::collections::HashMap;
@@ -36,7 +37,7 @@ const OPENAI_PROVIDER_NAME: &str = "OpenAI";
 /// *Responses* API. The two protocols use different request/response shapes
 /// and *cannot* be auto-detected at runtime, therefore each provider entry
 /// must declare which one it expects.
-#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
 #[serde(rename_all = "lowercase")]
 pub enum WireApi {
     /// The Responses API exposed by OpenAI at `/v1/responses`.
@@ -48,7 +49,7 @@ pub enum WireApi {
 }
 
 /// Serializable representation of a provider definition.
-#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema)]
 pub struct ModelProviderInfo {
     /// Friendly display name.
     pub name: String,