The SemOps Manual

What this is

SemOps is the operational discipline required to build, deploy, govern and evolve semantic knowledge systems continuously: what DevOps did for software, applied to ontologies, mappings, rules and knowledge graphs.

There is a lot of SemOps strategy about: maturity models, operating models, nine-stage pipeline blueprints, polyglot technology menus. Strategy is cheap. Why do semantic programmes stall, then? Almost never because nobody drew the diagram. It is because the diagram had no commands under it, no named owner, and no answer for the person who has to justify the spend in October.

This manual is the missing middle. It takes the SemOps strategy material as given and connects it, stage by stage, to a toolchain that is built, tested and runnable today:

Chapter 7 introduces them, says which versions this edition was measured against, and explains the one idea that matters more than any of them.

Every command shown in Part III was executed for real, against the ontology suite's own bundled examples/acme_robotics/ fixture, and re-run for this edition between 13 October and 3 November 2026. Where the output differs from what a strategy document would lead you to expect, the manual reports what actually happened and explains why. Chapter 9 has the sharpest example, where the obvious flag is the wrong one.

You don't have to take any of it on trust. evidence/ holds the commands, input data and recorded output behind every checkable claim, and an annotated copy of the manual with a link from each claim to its evidence and back.

Where the toolchain has no answer for a SemOps concept, this manual says so plainly and marks it grey. Chapter 14 is the honest ledger, and this edition's copy includes a list of things earlier editions had wrong.

The shape of the argument

Part I is unusual in a technical manual, and it is first on purpose. The failure modes that kill semantic programmes are overwhelmingly organisational, cognitive and commercial rather than technical. Building an ontology is a social process with a technical output: done well, it brings a team onto the same wavelength; done badly, it shows you the fracture lines that were already there. A team that can run every command in Part III and has not read Part I will build something correct that nobody adopts.

Read it on paper

Download the A4 PDF: the whole manual as a single A4 document, with a title page, contents with page numbers, all twenty diagrams rendered, and an index of commands, flags and check identifiers.

The PDF is published as a release asset rather than committed, so the repository does not carry a fresh multi-megabyte binary for every revision. Build it yourself with cd tools && npm install && node build-pdf.mjs; see tools/. The same build also produces the web edition.

Run it yourself

Three self-contained Jupyter notebooks cover the parts where watching the tool behave teaches more than reading about it. Each writes its own fixtures to a temporary directory, so nothing needs to exist on disk first.

pip install ontology-quality-suite shacl jupyterlab && jupyter lab

Notebook 2 also wants the shacl command on your PATH, from the engine's releases; pip install shacl gives you the Python library only. See notebooks/ for the details and how they are generated.

Contents

Part I — Why this is hard

Part II — The SemOps frame

Part III — The practice

Part IV — The ledger

How to read it

If you are deciding whether to fund this: Chapters 1, 3 and 4, then the coverage matrix in 14. About forty minutes.

If you have been handed a stalled semantic programme: Chapter 2 first. The diagnosis is usually there rather than in the technology.

If you are the engineer: skim 6 and 7, then work through Part III with a terminal open. Every command runs against fixtures bundled in the ontology suite, so nothing needs inventing to follow along.

If you are writing the business case: Chapters 1 and 14, and steal the maturity-level framing wholesale.

Conventions

Findings, commands and outputs in Part III are real. Where a number appears ("23 findings", "confidence 100%") it is the number the tool printed on the run described, not an illustrative figure.

Two outputs move unless you pin one variable, and both are labelled where they appear. A scoped data run reports 54 or 55 findings depending on whether the optional DL reasoner runs, and docgen reorders its page. Both turn out to follow Python's per-process hash seed, so PYTHONHASHSEED makes docgen reproducible and the reasoner very nearly so: nine runs in ten (Chapter 14 §14.4). In an unscoped run you can tell whether the reasoner ran from the report itself, since REA-021 present means it did and REA-022 means it did not. In a scoped run you cannot, because the scoping filter removes REA-022 along with everything else that isn't yours (Chapter 10 §10.4). Everything else is exactly reproducible across repeated runs, and survived a change of the engine underneath.

That last point is why Chapter 9 §9.8 argues for asserting on check identifiers rather than counts: counts move when the rules move, and identifiers say what moved.

Grey boxes and dashed borders in diagrams mean not covered by this toolchain. They are a deliberate, load-bearing part of the notation; see Appendix A.

Diagrams are Mermaid and render natively on GitHub. They are built to stay readable when printed A4 portrait; the rules that achieve that are documented in Appendix A for anyone extending the manual.

Licence

MIT — © 2026 Peter Winstanley. See LICENSE.

This covers the text, the diagrams and the build tooling: use it, adapt it, and put it in front of your own organisation. Attribution is required; a warranty is not offered.

Two things the licence does not reach. The Semantechs mark in assets/ is a trademark, and a copyright licence does not grant rights in it: reuse the manual freely, but replace the branding if you republish. The third-party vocabularies referenced throughout (the W3C Organization Ontology, FOAF, gist) carry their own terms, as do the tools the manual documents.