15. Adoption roadmap

Part IV — The ledger

The maturity model tells you where you are. This chapter tells you what to do on Monday.

The sequencing principle throughout: automate before you accelerate. Every transition below establishes a control before it increases throughput, for the reason Chapter 5 sets out — an organisation that raises its change rate before it has a gate has industrialised the production of unreviewed model.

Phase 0 — Baseline before you build

One to two weeks. Skipping this is the most common and most expensive mistake.

Once the ontology exists you can no longer measure what it saved, because the counterfactual is gone. Capture the numbers first.

Exit criterion: you can state, in one sentence and with a number, what is broken today.

Phase 1 — Reach Level 2: ontologies like code

Days. This is a decision more than a project.

Two habits to establish now, while it is cheap:

Design the IRI scheme deliberately. Schema terms and instance data should sit under a common prefix you can filter on — https://acme.example.org/ns/ and https://acme.example.org/data/ share https://acme.example.org/, which is what makes --own-namespace usable across both (Ch. 10). Retrofitting an IRI scheme is a migration.

Decide named graphs before the first production load. Per-source named graphs are nearly free at load time and effectively impossible to retrofit (Ch. 13).

Exit criterion: every modeller sees findings in their editor, and the ontology's history is in Git.

Phase 2 — Reach Level 3: the gate

Two to four weeks. This is the transition worth real effort.

It converts "we have standards" into "the standards are enforced without anyone remembering to enforce them" — and it is the prerequisite for everything in Phases 3 and 4.

Week 1 — the gate that cannot be ignored

ontology-quality-suite ontology \
  --ontology ontology/acme-org.ttl --import-dir lib/vocab \
  --fail-on Violation

Start here, not with the full registry. It is the narrowest, highest-signal check, and a gate people trust from day one is worth more than a comprehensive one they learn to bypass.

Week 2 — scope the registry, then add it

ontology-quality-suite checks \
  --ontology ontology/acme-org.ttl --import-dir lib/vocab \
  --own-namespace "https://acme.example.org/" \
  --engine sparql --fail-on Violation

Do not skip --own-namespace. Unscoped, the fixture in this manual produces close to 300 findings where 5 are yours, and the total drifts between runs; the gate is dead within two sprints (Ch. 9). And do not reach for --exclude-imports instead — verified, it introduces four false findings, which damages trust faster than noise does. The scoped run returns the same 5 findings every time, which is what a gate has to do.

Verify the filter is live by pointing it at a known-failing input once. A gate that cannot fail is indistinguishable from a gate that passes.

Week 3 — the pipeline stages

--output-data is not optional in practice. Without it, per-row controlled values are invisible (Ch. 12).

Week 4 — documentation and artefacts

PYTHONHASHSEED=0 ontology-quality-suite docgen \
  --ontology ontology/acme-org.ttl --out-dir docs/reference

Publish it. The PYTHONHASHSEED is a workaround, not decoration: without it docgen reorders its own output on every run, so the page is undiffable and two readers get the terms in a different sequence (Ch. 13).

Then retain full_results.csv from every run, timestamped — it costs nothing and becomes your only quality time series (Ch. 14).

Exit criterion: a pull request that breaks the ontology fails, and the failure names something the team owns.

Phase 3 — Hold it: release discipline

Ongoing. Most teams should stop and consolidate here.

Add one governance control, which is a branch protection rule rather than a command: a MAJOR bump requires a named reviewer. The tool establishes the fact; the platform enforces the policy (Ch. 12).

And one review-checklist item that will otherwise cost you an afternoon per occurrence: migration annotations are read directionally, from the retiring IRI to the replacement. Written the other way round, rename detection silently degrades to name-similarity guessing.

If you work across organisational boundaries

Three additions, all cheap (Ch. 3):

• Publish your check registry as a directory partners can point --registry/--shapes/--sparql at, so they validate before submitting rather than after rejection.
• Accept CSV. The triplify path means a partner never authors RDF.
• Attach diff.json to every change notice, so partner tooling can act without parsing your prose.

Phase 4 — Level 4, and knowing when not to

Quarters, and mostly not semantic work.

Level 4 is Kubernetes deployment, environment promotion, continuous ingestion with retry logic, an observability stack, and managed semantic APIs. Almost none of it is in this toolchain, and almost none of it needs specialist semantic tooling (Ch. 14).

What is here for Level 4:

Consider not doing Phase 4. A team solidly at Level 3, with a gate that holds and releases that are evidence-based, has captured most of the available value. Level 4 is justified by scale — many consumers, large graphs, strict availability. Pursued for its own sake it is an expensive way to acquire operational burden.

And Level 5 is overwhelmingly organisational. A team frustrated that tooling will not carry them there has correctly identified that the remaining problem is Chapter 2's, not the toolchain's.

The first ninety days, on one page

The last row matters more than it looks. A programme that reaches day 90 without having reported back against Phase 0's number will be asked to justify itself in a language it did not prepare for.

The shortest version

If you read nothing else in this manual:

1. Measure the cost before you fix it. You cannot reconstruct the counterfactual.
2. Name an owner. Unowned ontologies decay silently, and decay is the dominant failure mode.
3. Gate on --fail-on Violation, scoped with --own-namespace. Unscoped gates die; --exclude-imports produces false findings.
4. Assert migration annotations from the retiring IRI. Symmetric in logic, directional in tooling.
5. Automate before you accelerate. Especially before adding agents.