English | Japanese

yamlsan validates YAML frontmatter in your markdown files against a user-defined schema. Keep your Obsidian vault, blog, or documentation consistent -- no drifting fields, no missing metadata.

Features

• Schema-driven validation -- Define required fields, types, allowed values, and regex patterns in YAML or JSON
• Auto-fix -- Apply default values for missing fields (--dry-run to preview)
• CI-friendly -- --ci flag for minimal output with proper exit codes
• Recursive scanning -- Point at a directory, validate all .md files
• Rich output -- Color-coded table with error/warning breakdown
• Zero external APIs -- Fully offline, no accounts, no cloud

Installation

pip install yamlsan

Or from source:

git clone https://github.com/izag8216/yamlsan.git
cd yamlsan
pip install -e .

Quick Start

1. Create a schema

# schema.yaml
fields:
  title:
    type: string
    required: true
  created:
    type: date
    required: true
    pattern: "^\\d{4}-\\d{2}-\\d{2}$"
  status:
    type: string
    required: true
    allowed: ["draft", "published", "archived"]
  tags:
    type: list
    required: false
    min_length: 1
  priority:
    type: integer
    required: false
    min_value: 1
    max_value: 5
    default: 3

2. Validate your files

yamlsan validate ./vault/ --schema schema.yaml

3. Use in CI

yamlsan validate --ci ./docs/ --schema schema.yaml
# Exit code 0 = all valid, 1 = violations found, 2 = error

4. Auto-fix missing fields

# Preview changes
yamlsan fix ./vault/ --schema schema.yaml --dry-run

# Apply defaults
yamlsan fix ./vault/ --schema schema.yaml

Schema Reference

Each field in the fields mapping supports:

Property	Type	Default	Description
type	string	"any"	string, integer, float, boolean, list, date, enum, any
required	boolean	true	Whether the field must be present
allowed	list	--	Allowed values (enum)
pattern	string	--	Regex pattern the value must match
default	any	--	Default value for auto-fix
min_length	integer	--	Minimum length for strings/lists
max_length	integer	--	Maximum length for strings/lists
min_value	number	--	Minimum value for numbers
max_value	number	--	Maximum value for numbers
severity	string	"error"	"error" or "warning"

Exit Codes

Code	Meaning
0	All files valid (or help/version)
1	Validation violations found
2	Runtime error (file not found, bad schema)

Development

pip install -e ".[dev]"
pytest --cov=yamlsan

License

MIT License -- see LICENSE for details.