ConfDoc - Configuration Validation and Documentation Generator

A CLI tool that validates JSON/YAML/TOML configuration files against a schema and auto-generates human-readable documentation. It provides schema validation with clear error messages and generates markdown documentation from the schema itself, solving configuration management challenges for developers and DevOps teams.

Features

• Multi-format Support: Parse and validate JSON, YAML, and TOML configuration files
• Schema Validation: Validate configs against JSON Schema with detailed, actionable error messages
• Documentation Generation: Auto-generate markdown documentation from your schemas
• Environment Profiles: Built-in development, staging, and production profiles
• Type Checking: Extract and validate types from schemas with default values

Installation

pip install confdoc

Or from source:

pip install -e .

Quick Start

Validate a Configuration File

# Validate a config file against a schema
confdoc validate config.json --schema schema.json

# Specify format explicitly
confdoc validate config.yaml --schema schema.json --format yaml

# Apply a profile
confdoc validate config.json --schema schema.json --profile production

# JSON output
confdoc validate config.json --schema schema.json --output json

Generate Documentation

# Generate documentation from a schema
confdoc doc schema.json

# Write to a file
confdoc doc schema.json --output CONFIG.md

# Custom title
confdoc doc schema.json --title "My App Configuration"

Initialize a Schema

# Create a starter schema
confdoc init schema.json

# Generate schema from existing config
confdoc init schema.json --config config.json

Usage

Commands

Command	Description
confdoc validate <config>	Validate a configuration file
confdoc doc <schema>	Generate documentation from schema
confdoc init [output]	Initialize a new schema file

Options

Validate Command

Option	Description
--schema, -s	Path to schema file (default: schema.json)
--format, -f	Config format: json, yaml, toml, auto
--profile, -p	Profile to apply: development, staging, production
--output, -o	Output format: text, json

Doc Command

Option	Description
--output, -o	Output file path
--title, -t	Document title
--format, -f	Output format (default: markdown)

Init Command

Option	Description
--config, -c	Generate schema from existing config file

Examples

Example Configuration (JSON)

{
  "app": {
    "name": "myapp",
    "version": "1.0.0",
    "debug": true
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}

Example Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Application Configuration",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "name": {"type": "string", "description": "Application name"},
        "version": {"type": "string", "description": "Version"},
        "debug": {"type": "boolean", "description": "Debug mode", "default": false}
      },
      "required": ["name"]
    },
    "database": {
      "type": "object",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "integer", "minimum": 1, "maximum": 65535}
      }
    }
  },
  "required": ["app"]
}

Error Output

When validation fails, ConfDoc provides clear, actionable error messages:

✗ Configuration validation failed
  - 'port' is not of type 'string' in app.database
    → Expected type string, but got integer.

Configuration

Environment Variables

Variable	Description
CONFDOC_CONFIG_PATH	Default config path
CONFDOC_DEFAULT_SCHEMA	Default schema file

Configuration Files

ConfDoc looks for configuration in:

1. confdoc.yaml
2. .confdocrc
3. pyproject.toml section [tool.confdoc]

Profiles

ConfDoc includes built-in profiles for different environments:

Development

• Relaxed validation (additionalProperties allowed)
• Debug mode enabled by default
• DEBUG log level

Staging

• Strict validation
• Debug disabled
• INFO log level

Production

• Strict validation
• Debug disabled
• WARNING log level

Create custom profiles:

from confdoc.profiles import ProfileManager

manager = ProfileManager()
manager.save_profile("custom", {
    "name": "Custom",
    "validation": {"strict": True},
    "overrides": {"custom_key": "value"}
})

Schema Reference

ConfDoc supports JSON Schema draft-07 with these commonly used keywords:

Keyword	Description
type	Value type (string, integer, boolean, object, array)
required	Array of required property names
properties	Object property definitions
description	Property description for docs
default	Default value
enum	Allowed values
minimum	Minimum value (numbers)
maximum	Maximum value (numbers)
minLength	Minimum string length
maxLength	Maximum string length
pattern	Regex pattern

Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/confdoc --cov-report=term-missing

# Run specific test file
pytest tests/test_parsers.py -v

Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes
4. Write tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.