添加配置 Schema 与 IDE 补全支持

- 生成 Draft 7 JSON Schema 并新增 config-schema 子命令

- 为 TOML/YAML 模板写入 schema 绑定指令

- 同步 examples、README 与中英文手册

Author: developerworks

Cargo.toml

@@ -17,6 +17,7 @@ clap_complete = "4.6.3"
 confique = { version = "0.4.0", features = ["json5", "toml", "yaml"] }
 dotenvy = "0.15.7"
 figment = { version = "0.10.19", features = ["env", "json", "toml", "yaml"] }
+schemars = { version = "1", features = ["derive"] }
 serde_json = "1.0.149"
 tracing = "0.1.44"
 

README.md

@@ -14,7 +14,9 @@ It handles:
 - loading a `confique` schema into a directly usable config object through
   Figment runtime providers
 - `config-template`, `completions`, and `install-completions` command handlers
+- Draft 7 JSON Schema generation for editor completion and validation
 - config template generation for YAML, TOML, JSON, and JSON5
+- schema directives for TOML and YAML templates without adding runtime fields
 - recursive include traversal
 - `.env` loading before environment values are merged
 - source tracking through Figment metadata
@@ -36,6 +38,7 @@ implementing `ConfigSchema` to expose the schema's include field.
 rust-config-tree = "0.1"
 confique = { version = "0.4", features = ["yaml", "toml", "json5"] }
 figment = { version = "0.10", features = ["yaml", "env"] }
+schemars = { version = "1", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 clap = { version = "4", features = ["derive"] }
 ```
@@ -198,6 +201,19 @@ output format is inferred from the output path:
 - `.json` and `.json5` generate JSON5-compatible templates
 - unknown or missing extensions generate YAML
 
+Use `write_config_schema` to create one Draft 7 JSON Schema that can be shared
+by TOML, YAML, and JSON configuration files:
+
+```rust
+use rust_config_tree::write_config_schema;
+
+fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    write_config_schema::<AppConfig>("schemas/myapp.schema.json")?;
+
+    Ok(())
+}
+```
+
 Use `write_config_templates` to create a root template and every template file
 reachable from its include tree:
 
@@ -211,6 +227,28 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 }
 ```
 
+Use `write_config_templates_with_schema` when generated TOML and YAML templates
+should bind that schema for IDE completion and validation:
+
+```rust
+use rust_config_tree::write_config_templates_with_schema;
+
+fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    write_config_templates_with_schema::<AppConfig>(
+        "config.toml",
+        "config.example.toml",
+        "schemas/myapp.schema.json",
+    )?;
+
+    Ok(())
+}
+```
+
+TOML targets receive `#:schema ./schemas/myapp.schema.json`. YAML targets
+receive `# yaml-language-server: $schema=./schemas/myapp.schema.json`. JSON and
+JSON5 targets intentionally do not receive a `$schema` field; bind them with
+editor settings such as VS Code `json.schemas`.
+
 Template generation chooses its source tree in this order:
 
 - an existing config path
@@ -262,6 +300,7 @@ sections. Nested children are placed under their parent file stem, for example
 Flatten `ConfigCommand` into your existing clap command enum to add:
 
 - `config-template`
+- `config-schema`
 - `completions`
 - `install-completions`
 
@@ -285,9 +324,10 @@ use std::path::PathBuf;
 
 use clap::{Parser, Subcommand};
 use confique::Config;
+use schemars::JsonSchema;
 use rust_config_tree::{ConfigCommand, ConfigSchema, handle_config_command, load_config};
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -337,7 +377,11 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 
 `config-template --output <path>` writes templates to the selected path. If no
 output path is provided, it writes `config.example.yaml` in the current
-directory.
+directory. Add `--schema <path>` to bind TOML and YAML templates to a generated
+JSON Schema without adding a runtime `$schema` field.
+
+`config-schema --output <path>` writes a Draft 7 JSON Schema. If no output path
+is provided, it writes `schemas/config.schema.json`.
 
 `completions <shell>` prints completions to stdout.
 

README.zh.md

@@ -13,7 +13,9 @@
 - 通过 Figment runtime provider 将 `confique` schema 加载成可直接使用的
   config 对象
 - `config-template`、`completions` 和 `install-completions` 命令处理
+- 生成 Draft 7 JSON Schema，供编辑器补全和校验使用
 - YAML、TOML、JSON 和 JSON5 配置模板生成
+- 为 TOML 和 YAML 模板生成 schema directive，不写入运行时字段
 - 递归 include 遍历
 - 合并环境变量前加载 `.env`
 - 通过 Figment metadata 追踪配置来源
@@ -35,6 +37,7 @@
 rust-config-tree = "0.1"
 confique = { version = "0.4", features = ["yaml", "toml", "json5"] }
 figment = { version = "0.10", features = ["yaml", "env"] }
+schemars = { version = "1", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 clap = { version = "4", features = ["derive"] }
 ```
@@ -168,6 +171,19 @@ command-line overrides
 - `.json` 和 `.json5` 生成 JSON5-compatible 模板
 - 未知或缺失扩展名生成 YAML
 
+使用 `write_config_schema` 生成一份 Draft 7 JSON Schema，TOML、YAML 和
+JSON 配置文件可以共用它：
+
+```rust
+use rust_config_tree::write_config_schema;
+
+fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    write_config_schema::<AppConfig>("schemas/myapp.schema.json")?;
+
+    Ok(())
+}
+```
+
 使用 `write_config_templates` 创建 root 模板和 include tree 中的子模板：
 
 ```rust
@@ -180,6 +196,28 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 }
 ```
 
+如果生成的 TOML 和 YAML 模板需要绑定 schema，用
+`write_config_templates_with_schema`：
+
+```rust
+use rust_config_tree::write_config_templates_with_schema;
+
+fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    write_config_templates_with_schema::<AppConfig>(
+        "config.toml",
+        "config.example.toml",
+        "schemas/myapp.schema.json",
+    )?;
+
+    Ok(())
+}
+```
+
+TOML 目标会写入 `#:schema ./schemas/myapp.schema.json`。YAML 目标会写入
+`# yaml-language-server: $schema=./schemas/myapp.schema.json`。JSON 和 JSON5
+目标不会写 `$schema` 字段；这类文件应通过 VS Code `json.schemas` 等编辑器
+设置绑定。
+
 模板生成按这个顺序选择 source tree：
 
 - 已存在的 config path
@@ -192,6 +230,7 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 `rust-config-tree` 只提供可复用的 `ConfigCommand` 子命令：
 
 - `config-template`
+- `config-schema`
 - `completions`
 - `install-completions`
 
@@ -213,9 +252,10 @@ use std::path::PathBuf;
 
 use clap::{Parser, Subcommand};
 use confique::Config;
+use schemars::JsonSchema;
 use rust_config_tree::{ConfigCommand, ConfigSchema, handle_config_command, load_config};
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -264,7 +304,11 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 ```
 
 `config-template --output <path>` 将模板写入指定路径。未提供 output path 时，
-写入当前目录下的 `config.example.yaml`。
+写入当前目录下的 `config.example.yaml`。添加 `--schema <path>` 后，TOML 和
+YAML 模板会绑定生成的 JSON Schema，但不会加入运行时 `$schema` 字段。
+
+`config-schema --output <path>` 写入 Draft 7 JSON Schema。未提供 output path
+时，写入 `schemas/config.schema.json`。
 
 `completions <shell>` 将 completions 输出到 stdout。
 

examples/README.md

@@ -9,6 +9,7 @@ Run them from the repository root:
 cargo run --example basic_loading
 cargo run --example cli_overrides -- --server-port 9000
 cargo run --example config_commands -- config-template --output /tmp/config.example.yaml
+cargo run --example config_commands -- config-schema --output /tmp/myapp.schema.json
 cargo run --example generate_templates
 cargo run --example tree_api
 ```
@@ -19,5 +20,6 @@ The examples cover:
 - `cli_overrides.rs`: merge application CLI flags as the highest-priority
   Figment provider.
 - `config_commands.rs`: flatten `ConfigCommand` into an application clap CLI.
-- `generate_templates.rs`: write split config templates from a schema.
+- `generate_templates.rs`: write one JSON Schema and schema-bound TOML/YAML
+  templates from a schema.
 - `tree_api.rs`: use the lower-level, format-agnostic include tree API.

examples/config_commands.rs

@@ -7,6 +7,7 @@ use std::{
 use clap::{Parser, Subcommand};
 use confique::Config;
 use rust_config_tree::{ConfigCommand, ConfigSchema, handle_config_command, load_config};
+use schemars::JsonSchema;
 
 #[derive(Debug, Parser)]
 #[command(name = "config-commands")]
@@ -26,7 +27,7 @@ enum Command {
     Config(ConfigCommand),
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -38,7 +39,7 @@ struct AppConfig {
     server: ServerConfig,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct ServerConfig {
     #[config(default = "127.0.0.1")]
     bind: String,

examples/generate_templates.rs

@@ -5,9 +5,10 @@ use std::{
 };
 
 use confique::Config;
-use rust_config_tree::{ConfigSchema, write_config_templates};
+use rust_config_tree::{ConfigSchema, write_config_schema, write_config_templates_with_schema};
+use schemars::JsonSchema;
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 #[allow(dead_code)]
 struct AppConfig {
     #[config(default = [])]
@@ -23,7 +24,7 @@ struct AppConfig {
     log: LogConfig,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 #[allow(dead_code)]
 struct ServerConfig {
     /// HTTP bind address.
@@ -37,7 +38,7 @@ struct ServerConfig {
     port: u16,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 #[allow(dead_code)]
 struct DatabaseConfig {
     /// Database URL.
@@ -50,7 +51,7 @@ struct DatabaseConfig {
     pool_size: u32,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 #[allow(dead_code)]
 struct LogConfig {
     /// Log level.
@@ -68,11 +69,22 @@ impl ConfigSchema for AppConfig {
 fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     let dir = temp_example_dir("generate-templates")?;
     let config_path = dir.join("config.yaml");
-    let output_path = dir.join("config.example.yaml");
-
-    write_config_templates::<AppConfig>(&config_path, &output_path)?;
+    let schema_path = dir.join("schemas").join("myapp.schema.json");
+
+    write_config_schema::<AppConfig>(&schema_path)?;
+    for file_name in [
+        "config.example.toml",
+        "config.example.yaml",
+        "config.example.json",
+    ] {
+        write_config_templates_with_schema::<AppConfig>(
+            &config_path,
+            dir.join(file_name),
+            &schema_path,
+        )?;
+    }
 
-    println!("template root: {}", output_path.display());
+    println!("schema: {}", schema_path.display());
     for path in generated_files(&dir)? {
         println!("{}", path.display());
     }

manual/en/SUMMARY.md

@@ -8,6 +8,7 @@
 - [Environment Variables](environment.md)
 - [Source Tracking](source-tracking.md)
 - [Template Generation](templates.md)
+- [IDE Completions](ide-completions.md)
 - [CLI Integration](cli.md)
 - [Tree API](tree-api.md)
 - [GitHub Pages](github-pages.md)

manual/en/cli.md

@@ -5,6 +5,7 @@
 `ConfigCommand` provides reusable clap subcommands:
 
 - `config-template`
+- `config-schema`
 - `completions`
 - `install-completions`
 
@@ -31,9 +32,10 @@ use std::path::PathBuf;
 
 use clap::{Parser, Subcommand};
 use confique::Config;
+use schemars::JsonSchema;
 use rust_config_tree::{ConfigCommand, ConfigSchema, handle_config_command, load_config};
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -87,7 +89,18 @@ demo config-template --output config.example.yaml
 ```
 
 If no output path is provided, the command writes `config.example.yaml` in the
-current directory.
+current directory. Add `--schema schemas/myapp.schema.json` to bind generated
+TOML and YAML templates to the JSON Schema.
+
+```bash
+demo config-template --output config.example.toml --schema schemas/myapp.schema.json
+```
+
+Generate the shared JSON Schema:
+
+```bash
+demo config-schema --output schemas/myapp.schema.json
+```
 
 ## Shell Completions