sot-validator

Validator for Source of Truth (.sot) files — epistemic quality verification for AI-safe documentation.

What is a .sot file?

A Source of Truth (.sot) file is a markdown document structured to communicate explicit confidence levels for all claims, enabling readers (human or AI) to calibrate their trust appropriately.

Part of the Clarity Gate ecosystem for epistemic quality verification.

Installation

pip install sot-validator

CLI Usage

# Validate a single file
sot-validator project.sot

# Validate multiple files
sot-validator docs/*.sot

# Output as JSON
sot-validator project.sot --json

# Quiet mode (errors only)
sot-validator project.sot -q

Python API

from sot_validator import validate, is_valid, detect, validate_file

# Full validation with errors and warnings
result = validate(file_content)
print(result.valid)     # bool
print(result.errors)    # list of ValidationError
print(result.warnings)  # list of ValidationError

# Quick check
if is_valid(file_content):
    print('Document passes validation')

# Detect if content is .sot format
if detect(file_content):
    print('This appears to be a .sot file')

# Validate from file path
result = validate_file('project.sot')

Validation Rules

Required Elements

• -- Source of Truth header
• **Last Updated:** field
• **Owner:** field
• **Status:** field
• ## Verification Status section

Warnings

• Unqualified "VERIFIED" status (should be "with noted exceptions")
• Estimates in Verified Data section
• Missing staleness markers ([STABLE], [VOLATILE], etc.)

Related

• Clarity Gate - Pre-ingestion verification for RAG systems
• Source of Truth Creator - Create .sot files
• cgd-validator - Validate .cgd files

File Format Specification

See the SOT and CGD File Format Specification.

License

CC BY 4.0 — Use freely with attribution.

Author

Francesco Marinoni Moretto
GitHub: @frmoretto