7. Building One for Real

About 27 minutes spoken, 3,986 words. Plain text for a reader app: 07-building-one-for-real.txt

This is the seventh of ten talks about ontologies. The first three were the word and its history. Four, five and six were the engineering tradition — Cyc, the standards stack, and last time the machinery, where a reasoner computes what your axioms force to be true and the open-world assumption breaks a database engineer’s intuition. Today is practice. If you were handed a real project on Monday, what would you do, in what order, and where would it go wrong?

I’ll organise this around the sequence of decisions, because in my experience the order matters more than any individual choice.

Decision one, and it comes before you open an editor: write the competency questions.

A competency question is a question the finished ontology must be able to answer, written in plain language, before any modelling starts. Which suppliers ship components that appear in products currently under recall? Which nurses on shift tonight are certified for this procedure?

The term isn’t mine. The Common Core Ontologies document their design patterns as motivated by use cases and competency questions, and ship each pattern with a diagram and a query that answers it.

My practice on top of that: write twenty, get the people who’ll use the system to write them rather than the modellers, and keep them, because they are your acceptance tests. When somebody proposes a new class, the question is which competency question needs it. If none does, it doesn’t go in. That’s the strongest control on scope I know of.

It’s also Quine’s criterion from lecture three run backwards. He gave us a way to read commitments off a theory; competency questions start from the questions and derive the commitments those questions require.

Decision two: how many layers, and which foundation.

The layering is three deep. At the top, an upper ontology giving domain-neutral categories. In the middle, a mid-level ontology with reusable notions. At the bottom, your domain. That’s the arrangement the Common Core Ontologies describe for themselves — sitting between the most generic categories above and the domain-specific ontologies below.

BFO, the Basic Formal Ontology, is that layer above. It’s a small upper-level ontology meant to support retrieval, analysis and integration across scientific and other domains, and its defining trait is what it refuses to contain. It deliberately excludes physical, chemical, biological, and other terms belonging to the specialised sciences. Its own guidance is to use it as a domain-independent top-level framework beneath a specialised ontology, and more than five hundred and fifty ontology-driven efforts do exactly that. Do not expect it to hand you scientific vocabulary; the project explicitly places that outside its scope.

Below it sits the mid-level. The Common Core Ontologies, CCO, are the clearest example: eleven modules extending BFO, covering agents, events, time, qualities, measurement units, currencies, facilities, artifacts, information entities, geospatial entities and extended relations, with broadly reusable classes like person, facility, date, employment and measurement. Things every domain needs and no domain owns.

Other foundations make different bets, and the differences are real.

DOLCE — the Descriptive Ontology for Linguistic and Cognitive Engineering — has been stable since its release in two thousand and two, is formally specified in first-order logic, and has a published consistency proof. The catch its own documentation states is that the versions in OWL, the Web Ontology Language, are re-engineerings rather than identical releases: they omit modality and temporal indexing, and add descriptions and situations that official DOLCE does not cover. Adopt DOLCE in OWL and you have adopted an adaptation.

Gist is Semantic Arts’ minimalist upper ontology for enterprise use. Roughly one hundred classes and a similar number of attributes and relationships, familiar top-level concepts like person, organization and agreement, extensive high-level disjointness to expose inconsistent typing, and no inverse properties.

gUFO is a lightweight implementation of UFO, the Unified Foundational Ontology, aimed at OWL two applications in the description-logic profile. It selects a subset of UFO and separates a taxonomy of individuals — objects, aspects, events, situations — from a taxonomy of types: kinds, phases, roles, categories, relationship types. “Lightweight” is a deliberate trade-off, and its authors say so. Some intended constraints go undeclared because declaring them would break decidability: proper parthood is described as asymmetric and irreflexive, and both characteristics are left out of the implementation.

Worth seeing what adopting one looks like at the class level, because people imagine something more mystical than it is. gUFO’s own instruction is to reuse its domain-independent distinctions by specialising or instantiating its classes. A class of yours can at the same time specialise its object class and instantiate its kind class; the occurrences you record instantiate its event class and use the temporal properties it supplies. That’s the move. A foundation, as I read it, is not a layer you admire from below. It’s a set of parents and types you attach your own terms to, one term at a time.

Choosing among these isn’t a matter of quality. As I read it, it’s a matter of which commitments you want to inherit — and you will inherit them, because everything you build sits underneath them.

And you inherit an apparatus with them. BFO expects you to work with its guidebook, publications, tutorials, release history and user forums; DOLCE, which began as a module of the WonderWeb foundational ontologies library, sends you to OntoClean and to applied research on roles, qualities, organizations, artifacts and group agency. You are choosing a body of practice, not a top-level diagram.

Decision three: reuse before invention.

Reuse an existing term, extend an existing ontology, and only then mint something new. The Common Core Ontologies state the institutional version of this: their authors explicitly encourage users to publish their own domain extensions rather than expanding the core indefinitely with domain content. BFO states the same boundary from the other side by refusing scientific terms outright.

To reuse, you have to find things, and there are catalogues. The OBO Foundry — the Open Biological and Biomedical Ontology Foundry — is the one to know: a community effort to develop interoperable ontologies for the biological sciences, whose site pairs an ontology catalog with published principles and best-practice material. You can search or filter the table, consult the principles, or submit an ontology for consideration.

Reuse doesn’t only happen at the level of whole ontologies, and this is the place to say what a design pattern is, because I used the phrase at the top of the lecture and let it go past.

A design pattern is a documented, reusable treatment of a modelling situation that recurs — published as an artifact you can lift, not as advice you have to interpret. That’s why the Common Core patterns come with a graph, a visualisation and a query attached rather than a paragraph of guidance, and the query is the part that matters: it makes the pattern checkable instead of merely persuasive, because it is the pattern demonstrating that it answers the question it was written for. Their documentation recommends reusing those patterns when you map data into a knowledge graph, on the argument that it speeds up the mapping and the querying and improves consistency and interoperability between the people doing it. Which is the case for patterns entire: the win is not cleverness, it’s two teams solving the recurring problem the same way.

There is a community portal for patterns as such. It organises them by type and by domain, links patterns to the modelling issues that motivate them, collects exemplary ontologies, and runs training, open review and a quality committee.

And now the caution the catalogues state about themselves and people ignore anyway. Inclusion is not endorsement. The OBO Foundry’s home page presents principles, resources and catalog access, but it does not itself establish that every listed ontology satisfies every principle — selecting one still means examining that entry and its metadata yourself. The ontology design patterns portal is the same story: it still marks certified content as due to come, so presence in that catalogue is not certification either. Finding an ontology in a catalogue tells you it exists, and, as I read it, nothing more.

Decision four: identifiers and labels, and this is where projects acquire scars.

The rule that matters is that identifiers should be opaque and stable, and labels should carry the human-readable meaning. ELOT — the literate ontology-engineering environment — states it in those words: labels, not the compact identifiers, carry human-readable meaning. The Common Core Ontologies learned it the hard way. Their version two changed the IRI namespace — that’s the Internationalized Resource Identifier, the global name of a term — and adopted opaque local identifiers, and the release summary records no other ontology changes in that step. A whole release spent on identifiers.

The reason, as I read it, is one-way doors. Mint an identifier that spells out a term’s meaning, refine that meaning later, and you have a permanent lie in a name other people have already cited.

ELOT also documents the mechanical traps. Numeric-only counter identifiers are technically invalid as XML names, so an alphabetic counter template is recommended instead, and its slug scheme is lossy. Its position is that identifier policy belongs to each ontology rather than to the tool, with a documented menu — universally unique identifiers, label-derived slugs, formatted counters, registered custom schemes. Pick from it before the first commit, and enforce that in the build.

Decision five: which editor, and this is less consequential than teams believe.

Protégé is a free, open-source OWL ontology editor covering the whole lifecycle. Desktop Protégé does local modelling, reasoning and querying on a Java plug-in architecture; WebProtégé does the same work in a browser when several people need to collaborate. It’s also the assumed tool elsewhere: the Common Core Ontologies tell you to import their all-core file into Protégé to assemble the eleven modules.

And there’s a text-first tradition worth knowing about, because it fits how software teams already work. ELOT makes one plain-text notebook the ontology source and its documentation at once. The outline carries formal meaning: headlines declare classes, properties and individuals, nesting expresses the subclass hierarchy, and description-list rows attach annotations and axioms written in Manchester syntax. Queries and diagrams live in the same file as the prose. Its documentation says it has been used in scores of projects, including an ISO standard.

It’s also unusually honest about its own state, and that’s a property I’d weigh when choosing any tool here. Its documentation says outright that the long-form manual is under construction, that several manual files are stubs or drafts and may be inaccurate, and then names the documents that are reliable. It publishes a feature matrix across editors too: Emacs is the reference implementation and gets things first, while the Visual Studio Code extension marks queries, diagrams and the assisted-authoring features as planned rather than available. My view is that a tool telling you which parts of its own documentation to distrust should raise your confidence, not lower it.

Decision six: automate the lifecycle, because this is what separates a project that survives from one that doesn’t.

ROBOT is the workhorse — a tool for working with Open Biomedical Ontologies, available as a command-line program or as a library. Its documented commands cover annotation, conversion, diffing, extraction, filtering, materialisation, merging, querying, reasoning, repair, reporting, templating, profile validation, and verification. ELOT leans on it too: optional there, but required for conversion, queries, reasoning or reports.

That whole surface is reachable from a script, and my argument is that this is the point. Put it in continuous integration: every change classifies the ontology, checks the profile, runs the report, and fails if consistency broke. Encode the competency questions as queries in the same suite, so a change that breaks an answer fails the build rather than surfacing in a meeting six weeks later. Treat your ontology like source code and it behaves like source code.

WIDOCO — the Wizard for Documenting Ontologies — is the publication half, generating human-readable documentation from the ontology’s own annotations and folding in visualisation, an evaluation report, licence metadata, provenance, and changelogs computed between versions. Its advice is to keep that metadata inside the ontology as annotations rather than in a separate configuration file, because embedded metadata is easier to maintain across releases.

Decision seven: expect alignment, and budget for it.

We established in lecture three why this is permanent. Different purposes produce different commitments, so two correct models of the same domain will differ, and somebody has to write the mapping.

There is mature tooling. AgreementMakerLight, AML, is an automated, efficient matcher emphasising element-level matching supported by background knowledge. It runs between a source ontology and a target, in three modes — automatic matching, manual matching configured through a settings file, and alignment repair, where an existing alignment is the required input rather than an optional hint. Its authors report strong results across several shared evaluation tracks. One trap: it saves nothing unless you give it an output path.

LogMap is the other one to know, built for scale — semantically rich ontologies with tens or even hundreds of thousands of classes. It maps classes, properties and instances rather than classes alone, and it integrates reasoning and mapping repair to minimise logical inconsistencies in the alignments it produces. A large task can be divided into subtasks, and that division is a documented module rather than something you improvise. Its documentation is also honest about the cost of scale: newer Java versions need specific virtual-machine arguments, and the suggested configuration allows a heap of up to twenty-five gigabytes. That number is the caution.

Alignment is also where the large language models arrived first, and I’ll flag it here because it’s where this course ends up. LogMap’s documentation states that it supports validation by a large language model during matching, and points at related work described as using large language models as oracles for ontology alignment — oracle meaning, as I read it, that the matcher proposes a correspondence and the model is asked whether it holds. The same documentation records neighbouring work augmenting alignment with semantic or knowledge-graph embeddings and with distant supervision. Notice the role the model is given. It is not authoring the ontology and it is not deciding the alignment; it is consulted about one candidate correspondence at a time, inside a system that still does its own reasoning and its own repair. Hold that shape in mind. We come back to it at the end of the course.

Decision eight: version and deprecation policy, which has to exist before the first release.

Versioning an ontology is harder than versioning code, for one reason. Release version two of a library and consumers upgrade when they choose; old versions keep working. Release version two of an ontology and other people’s data already contains your identifiers — in published datasets, in papers, in databases you have never heard of. You cannot recall them.

The field’s answer is institutional. The OBO Foundry’s published principles include an identifier space, versioning, change notification, maintenance, stability of term meaning, and responsiveness — six of the sixteen are about not breaking the people downstream. Gist shows the other side: its major release fourteen broke compatibility with earlier versions, migration scripts were supplied, and the following release was backward-compatible again. Breaking changes happen; migration material is what makes them survivable.

There’s a consumer’s half of this, and the Common Core Ontologies are living it in public right now. Their repository is being modernised through structural changes planned across two coming releases, and the guidance says plainly what that means downstream: the Governance Board recommends waiting until after the later of the two before updating, and anyone who needs the current changes should take them from the development branch. That is a version policy doing its job — one answer for the patient, a documented route for the impatient. Ask it of every ontology you intend to depend on, and if nobody can answer, you have learned something about the project you were about to marry.

The metadata is mechanical, so automate it. WIDOCO’s guidance is to give the vocabulary a stable namespace and prefix, a licence, a version identifier and version information, and a link to the previous version — that last link is what lets it generate a changelog at all. Term annotations carry deprecation and status, running from unstable through testing and stable to archaic. Stamp those in the release process, because a file that doesn’t say which version it is ends up in four places at three versions.

Decision nine: documentation, and the gap between the file and what a human needs.

An ontology is not self-documenting, whatever anyone tells you. A class annotated “a customer” is documented in the same sense that a variable called data is documented. Textual definitions are one of the OBO Foundry’s principles, and WIDOCO’s checklist says the same at the term level: describe classes and properties with labels and definitions, and use the optional annotations for examples, original source, rationale, deprecation and status.

The one people skip — my addition, not theirs — is the negative definition. What the class deliberately is not. If your Order class does not cover cancelled orders, say so in the annotation, where the person integrating at midnight will read it. Otherwise they find out by writing a query that returns a slightly wrong number nobody notices for a year. WIDOCO renders all of this; it cannot write the definitions. Somebody has to, and writing a genuine definition is the best test of whether the class should exist, because a class you can’t define crisply will accumulate junk.

Now, four failure modes.

The first is scope creep, and it starts reasonably. Someone notices the model doesn’t cover a nearby case, so they extend it. Then another. Two years later nobody understands the whole thing, classification is slow enough that people stop running it, and no consuming system uses more than a fraction of the terms. The competency questions are what prevent this, which is why they’re decision one. And notice that BFO’s refusal to include scientific terms, and the Common Core’s instruction to publish extensions rather than grow the core, are institutional versions of the same defence. The foundations that lasted say no for a living.

The second is version drift, and this one is documented rather than folklore. The Common Core Ontologies warn their own contributors that different versions of the OWL programming interface and of Protégé can generate spurious formatting differences — your diff shows a thousand changed lines and one real edit. Their remedy is worth stealing: before substantive edits, make a token change, inspect the diff to see what your toolchain does to the file, and confirm the result still loads. Pin your versions, and treat an upgrade as a change requiring review.

And the version problem doesn’t stay inside the file; it runs through the whole tool chain. Read the installation notes rather than the front pages and you find ROBOT wanting Java eleven or later, the exporter that pulls existing models into ELOT wanting Java twenty-one or newer, and AgreementMakerLight naming the three Oracle Java releases it was tested against, stating that compatibility with OpenJDK — the open Java Development Kit — is not guaranteed, and advising you to download the built release rather than compile it, because the build reports errors. LogMap’s older interface branch is explicitly unmaintained. Individually none of that is interesting. Together it means a working pipeline pins several runtimes at once, and the rule I take from it is dull and it holds: your tool versions are part of your ontology’s build, so declare them and let the build fail when they drift.

Licensing belongs in the same honest paragraph, because it’s the other thing teams discover late and from the wrong person. Gist’s licence requires attribution — an obligation that arrives with the download and binds whatever you build on top of it. That’s why licence sits in the metadata list I read out a minute ago, and why the licence of every ontology you import belongs inside the ontology, before somebody asks the question in a procurement meeting.

The third is confusing syntactic success with semantic correctness. Your file parses. It passes the linter. That tells you nothing about whether it is consistent, or whether it means what you intended. This matters most when a language model is proposing edits, and ELOT shows both halves of the pattern. The guard rails: file writes are project-scoped, disabled by default, confirmation-gated, revalidated, and rolled back if revalidation fails. And the honesty: its documentation states plainly that the automatic validation checks lint and parsing, not semantic consistency, so the separate consistency check still has to run.

The same tool documents a smaller, mechanical version of the lesson: a freshly minted identifier cannot be used as the subject of an axiom in the same batch, so creating a term and then saying things about it takes two separate calls. That isn’t in the pitch, it’s in the pitfalls — which is where the working knowledge of every tool in this lecture turns out to live.

The fourth is the ontology that becomes an end in itself. The team spends more time on the upper ontology than on the domain. Debates about foundational categories run for weeks with no consuming system waiting on the answer. The class count grows faster than the query count. And when you ask which competency question a new branch serves, you get an answer about completeness. Completeness is not a goal. It’s the failure mode that Cyc’s forty years, from lecture four, should have inoculated this field against, and hasn’t, because building a beautiful model of the world is more fun than answering three tedious questions about shipments.

Two last things from experience rather than from the sources, and I’ll flag them as mine. Month one of a real project is not modelling; it’s competency questions, and discovering that two departments have used the same word differently for a decade. Month three should be the first small model that answers three of those questions end to end against real data, because that proves the pipeline.

And staffing: three roles, rarely the same person. Someone who knows the domain well enough to say when a distinction is real. Someone who knows the formalism well enough to say when a modelling choice will cause trouble in two years. And someone with the institutional standing to rule when two departments disagree about what a word means, and make it stick. The third gets left out of project plans, and it decides whether the thing ships.

Which is the point of the whole lecture, so let me finish there.

Who decides what a term means? What’s the deprecation policy when a term turns out to be wrong, given that other people’s data already cites it? Who is responsible in five years?

Those questions have institutional answers, not technical ones, and the projects in today’s sources answer them out loud. The OBO Foundry publishes principles covering authority, collaboration, change notification, maintenance and responsiveness, plus a submission route and working groups. The Common Core Ontologies have a Governance Board that tells users which release to wait for. Gist ships migration scripts, and namespace rules forbidding you from defining your own terms in its space. None of that is overhead attached to the real work.

So, the claim to keep. Write the competency questions first and use them as acceptance tests. Reuse before inventing, and don’t mistake catalogue inclusion for endorsement. Put the ontology in continuous integration with ROBOT. Budget for alignment, because it’s permanent. And understand what you’re setting up: an ontology project is a governance project with a file attached. The modelling is the easy half.

Next time, the case against everything I’ve just told you.