jsonschema-annotator

WARNING: This project was vibe-coded with claude with minimal review, use at your own risk!

Annotate YAML and TOML configuration files with comments derived from JSON Schema title and description fields.

Example

Given a schema:

{
  "properties": {
    "server": {
      "title": "Server Configuration",
      "description": "HTTP server settings",
      "properties": {
        "port": {
          "title": "Port",
          "description": "The port number to listen on"
        }
      }
    }
  }
}

And a config:

[server]
port = 8080

Produces:

# Server Configuration
# HTTP server settings
[server]
# Port
# The port number to listen on
port = 8080

Installation

cargo install jsonschema-annotator

Or build from source:

git clone https://github.com/kellpossible/jsonschema-annotator
cd jsonschema-annotator
cargo build --release

CLI Usage

# Annotate a TOML file, output to stdout
jsonschema-annotator -s schema.json -i config.toml

# Annotate a YAML file, write to output file
jsonschema-annotator -s schema.json -i config.yaml -o config.annotated.yaml

# Read from stdin (defaults to YAML format)
cat config.yaml | jsonschema-annotator -s schema.json -i -

# Only include titles (no descriptions)
jsonschema-annotator -s schema.json -i config.toml --include title

# Custom line width for description wrapping
jsonschema-annotator -s schema.json -i config.toml --max-width 60

CLI Options

Options:
  -s, --schema <SCHEMA>        Path to JSON Schema file (JSON or YAML)
  -i, --input <INPUT>          Path to config file to annotate (YAML or TOML), or - for stdin
  -o, --output <OUTPUT>        Output path (default: stdout)
      --include <INCLUDE>      What to include in comments [default: both] [possible values: title, description, both]
      --max-width <MAX_WIDTH>  Maximum line width for description wrapping [default: 80]
      --force                  Overwrite output file if it exists
  -h, --help                   Print help
  -V, --version                Print version

Library Usage

use jsonschema_annotator::{annotate, TargetFormat, AnnotatorConfig};
use schemars::Schema;

let schema_json = r#"{
    "properties": {
        "port": {
            "title": "Port",
            "description": "Server port number"
        }
    }
}"#;

let schema: Schema = serde_json::from_str(schema_json).unwrap();
let config_str = "port = 8080";

let annotated = annotate(
    &schema,
    config_str,
    TargetFormat::Toml,
    AnnotatorConfig::default(),
).unwrap();

assert!(annotated.contains("# Port"));
assert!(annotated.contains("# Server port number"));

Configuration Options

let config = AnnotatorConfig {
    include_title: true,        // Include schema titles
    include_description: true,  // Include schema descriptions
    max_line_width: Some(80),   // Wrap descriptions at 80 chars
    preserve_existing: true,    // Keep existing comments
};

Features

• TOML & YAML support: Annotate both formats with the same schema
• $ref resolution: Local JSON Schema $ref pointers are resolved automatically
• Schema composition: oneOf, allOf, and anyOf are supported
• Format preservation: Uses toml_edit and string-based YAML injection to preserve formatting
• Configurable output: Include title, description, or both
• Line wrapping: Long descriptions are wrapped at configurable width
• Existing comments: Optionally preserve existing comments in the file

Limitations

• Only local $ref (starting with #) are supported; external file/URL references are not
• YAML inline tables and complex structures may not be annotated

License

MIT License - see LICENSE for details.