Blathers

Ontology documentation & validation CLI -- bridges auto-extracted OWL/SHACL definitions with Markdown narrative.

Features

• 5 validators -- SHACL, consistency, completeness, naming conventions, and overlap detection
• Sidecar Markdown -- author rich narrative alongside your ontology using YAML frontmatter
• Static HTML output -- generates a self-contained documentation site with ReSpec-style layout
• RDF/OWL extraction -- parses classes, properties, and named individuals via rdflib
• Content negotiation -- generates Apache, nginx, and w3id configuration

Quick start

pip install blathers

Scaffold a new project:

blathers init my-ontology
cd my-ontology

Validate your ontology:

blathers validate

Build the documentation site:

blathers build

Configuration

Blathers reads from blathers.yaml in your project root:

ontology: ontology/my-ontology.ttl
shacl: []
sidecars: sidecars/
figures: figures/
output: dist/

metadata:
  title: "My Ontology"
  version: "1.0.0"
  namespace: "http://example.org/onto#"
  prefix: onto

validation:
  fail_on: error
  rules:
    shacl: true
    consistency: true
    completeness: true
    conventions: true
    overlap: true

Sidecar authoring

Create Markdown files in sidecars/ with YAML frontmatter to add narrative:

---
term: onto:MyClass
section: overview
order: 1
---

Description of MyClass and its role in the ontology.

CLI commands

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT