Ontology Skos Audit

Ontology SKOS Audit

Structural integrity audit for SKOS concept schemes. Uses rdflib to parse any RDF serialization (Turtle, OWL, RDF/XML, N-Triples, JSON-LD, etc.) and navigate the SKOS graph to detect 8 categories of structural issues.

What It Detects

Setup

Create a virtual environment and install dependencies:

cd <your-ontology-repo>
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install rdflib

After finishing: deactivate the venv and remove it:

deactivate && rm -rf .venv

Skip this if the user asks to keep the environment.

Workflow

1. Run the audit

python scripts/skos_audit.py . -o SKOS_REPORT.md

2. JSON output for CI pipelines

python scripts/skos_audit.py . -o skos_issues.json --format json

Example JSON entry:

{
  "severity": "error",
  "check": "inScheme-undefined",
  "message": "Concept :StreetLamp references undefined ConceptScheme ex:MissingScheme",
  "subject_short": ":StreetLamp",
  "scheme_short": "ex:MissingScheme"
}

How It Works

┌─────────────────────┐
│  RDF files in repo  │
│  (.ttl, .owl, .rdf, │
│   .nt, .jsonld, …)  │
└────────┬────────────┘
         │ rdflib parses all into one graph
         ▼
┌─────────────────────┐
│  skos_audit.py      │
│  SPARQL-like graph  │
│  traversal:          │
│    skos:Concept     │
│    skos:ConceptScheme│
│    skos:inScheme    │
│    skos:broader     │
│    skos:narrower    │
│    skos:prefLabel   │
│    skos:notation    │
└────────┬────────────┘
         ▼
  SKOS_REPORT.md
  (or .json)

Standardized Report

All skills support --format report which outputs a common JSON schema:

{
  "skill": "skill-name",
  "summary": {"errors": N, "warnings": N, "info": N},
  "issues": [{"file": ".ttl", "element": ":Class", "message": "...",
              "severity": "error|warning|info", "check": "RULE",
              "suggestion": "fix"}]
}

This format is consumed by ontology-full-audit to produce unified reports.

Output Files

Never write files into the repository without permission. Before generating any report or output file, ask the user where to save it (e.g. -o ../report.md or an absolute path outside the repo). The default output path in script examples is only a suggestion — always confirm with the user first.

Important Rules

1. missing-prefLabel is always an error. SKOS requires skos:prefLabel on every skos:Concept. A concept with only skos:altLabel is not valid.

2. duplicate-prefLabel within a scheme is almost always wrong. Two concepts in the same scheme should not share the same label since prefLabel is meant to be unique per language.

3. notation-mismatch is informational, not always wrong. The script normalizes accents and spaces before comparing. A mismatch may be intentional (e.g. legacy notation) — review manually.

4. empty-scheme may be intentional if the scheme is defined in a different file not scanned. Adjust the repo path accordingly.

5. For SKOS, skos:notation uses unaccented forms. e.g. pista-de-padel, while skos:prefLabel uses proper orthography: Pista de Pádel.

Troubleshooting