Running a Controlled Vocabulary: Governance, Tooling and Quality

A controlled vocabulary is not a file, it is a product with users, and the ones that fail almost never fail for technical reasons. They fail because nobody owned them, because a concept was deleted rather than deprecated, or because two teams edited the same term for eighteen months without noticing they meant different things by it. Lesson 7 gave you the language. This lesson is about the operational discipline that decides whether the vocabulary is still trustworthy in three years, and about the tooling that makes the discipline cheap enough to actually follow.

The vocabulary is a product, so give it a product’s furniture

Four roles have to exist somewhere, even on a small vocabulary, and naming them is most of the battle. There is an owner, accountable for what the vocabulary means, who is almost never the engineer. There are editors, usually domain experts, who propose and make changes. There is a reviewer or editorial board that adjudicates the arguments, because concept boundaries are contested and the argument has to end somewhere. And there are consumers, the systems and people who tag against it, who need to know when it changed and what changed.

The furniture that serves those roles is unglamorous: a change proposal route, a release cadence, a version identifier on every published release, a changelog a human can read, and a deprecation policy. Vocabularies that skip the release cadence get edited continuously in production, which means no consumer can ever say which version they tagged against, which means nothing can be reproduced. Pick a cadence, publish on it, and let the urgent additions wait for the next one.

ISO 25964-1, published in 2011, is the reference for the editorial side of this, and ISO 25964-2, published in 2013, covers interoperability with other vocabularies. ANSI/NISO Z39.19-2005, reaffirmed in 2010, remains a readable account of monolingual vocabulary construction and management. Neither will tell you anything about RDF, which is precisely why they are worth reading: they encode four decades of experience about the editorial failure modes, and those have not changed because the serialization did.

Editorial platforms: what to use, and when a text file is correct

The honest first answer is that a vocabulary of a hundred concepts maintained by one team belongs in a Turtle file in git, with a pull request per change and a validation job on the branch. You get review, history, blame, rollback and CI for free, and you have introduced no software to run. Reach for a platform when one of three things is true: the editors will not use git, the vocabulary is multilingual with distinct translators per language, or you need workflow states and per-label provenance.

VocBench 3 is the serious open option. It is a collaborative web platform for OWL ontologies, SKOS and SKOS-XL thesauri, Ontolex-lemon lexicons and generic RDF, released publicly in September 2017 under a BSD 3-clause licence. Its lineage matters: the original VocBench was built at the FAO to maintain AGROVOC, VocBench 2 was developed by the University of Rome Tor Vergata jointly with the FAO, and VocBench 3 is developed at Tor Vergata with funding from the European Commission ISA² programme and development managed by the Publications Office of the EU. That is why it handles multilingual editorial workflow properly: it was built by the two institutions with the hardest multilingual vocabulary problems in the world. The reference paper is Stellato and colleagues in the Semantic Web journal, 2020.

PoolParty is the established commercial platform, strong on the taxonomy-plus-content-tagging path and on integration with text mining. Note the corporate change if you are reading older material: Semantic Web Company, which built PoolParty, merged with Ontotext in an announcement dated 23 October 2024, and the combined company is Graphwise. The product continues; the vendor name in your procurement documents should not.

TopBraid EDG from TopQuadrant sits in the enterprise data governance lane, where the vocabulary is one asset among glossaries, reference data and lineage. Choose it when the buyer is data governance rather than content, and be aware you are buying a governance suite that does taxonomies, not a taxonomy tool.

Publishing: a vocabulary nobody can dereference is a private file

Publication is the step most internal vocabularies skip, and skipping it quietly cancels the main benefit, which is that other systems can point at your concepts instead of copying your strings. Three things make a vocabulary published rather than merely available.

Persistent, dereferenceable URIs. Concept URIs will end up in other people’s databases, so they are a permanent commitment. Do not put a hostname you might lose, a version number, or the preferred label in the URI. Opaque identifiers under a domain you control, or a PURL, and content negotiation so that a browser gets HTML and a machine gets RDF.

A browsable interface. Skosmos is the open source answer, developed by the National Library of Finland, where it runs the national Finto service. It reads SKOS from a SPARQL endpoint and gives you concept pages, multilingual search, hierarchy browsing, content negotiation and a REST API without writing an application. Development is active: version 3.3 was released on 9 June 2025.

Machine access and a licence. A SPARQL endpoint or a downloadable dump, plus an explicit licence, because a vocabulary without a licence cannot legally be reused and reuse was the point. The exemplar to copy is the EU Vocabularies service at the Publications Office, which publishes EuroVoc, currently at version 4.24, covering the 24 official EU languages plus Albanian, Macedonian and Serbian, with downloads, an endpoint and versioned releases.

Worked example · the Aberdeen-2 asset register

Where we left it: an equipment-type scheme absorbing three source dialects, living in one engineer’s working file.

The scheme is the most fragile artefact we have built, because it is the only one whose correctness no reasoner can check and whose users are not in the room. So it gets the full product treatment, sized for a two-engineer project. The owner is the maintenance superintendent, not us, because the terms are maintenance’s terms and the moment engineering owns the vocabulary the catalogue dialect quietly disappears from it. Editors are the superintendent and the reliability engineer. Changes arrive as issues, releases are monthly and versioned, and the changelog names every concept added, deprecated or re-scoped.

The vocabulary lives in git as Turtle, because two editors do not justify a platform, and the branch runs three checks before merge: Skosify for structural validity, a qSKOS report for the quality issues that are warnings rather than errors, and a SHACL shapes file encoding the rules that are ours rather than the standard’s, which is the same CI habit lesson 11 built for the data. The house rules are short and specific: every concept carries a scope note, every concept has an English preferred label, no concept is an orphan, and no notation is reused. Two of those are not SKOS requirements at all, which is exactly why they need shapes.

Publication is internal but real. The scheme is served through Skosmos on the intranet so that a planner can look up “what does the register mean by rotating equipment” without asking an engineer, and the URIs resolve. That single move is what stops the fourth dialect from being invented next year by someone who could not find the third.

State of the register: the vocabulary is a governed product with an owner, a cadence and CI. Next lesson asks the question we have been deferring: which parts of this problem should never have been SKOS in the first place.

Quality: the checks that catch what the specification cannot

SKOS carries integrity conditions, but conformance to them is a low bar and a vocabulary can satisfy every one while being unusable. Two research tools defined what the higher bar looks like, and both are still the reference.

qSKOS, from Christian Mader, Bernhard Haslhofer and Antoine Isaac, formalised a catalogue of quality issues into computable checking functions and ran them over published vocabularies, reported in “Finding Quality Issues in SKOS Vocabularies” at TPDL 2012. The follow-up by Osma Suominen and Mader in the Journal on Data Semantics in 2014 extended the analysis and connected it to remediation. Skosify, from Suominen and Eero Hyvonen at EKAW 2012, approached it from the other end: it converts RDFS and OWL vocabularies into SKOS and validates and corrects existing SKOS, working from 11 criteria. Their finding is the one to quote at a sceptical stakeholder. They analysed 14 published vocabularies against those criteria and found that most of them contained structural errors.

The issue classes worth wiring into CI, in rough order of how much damage they do:

Vocabulary quality issues, what they cost, and how to catch them
Issue	What it looks like	Operational cost	Gate
Cyclic hierarchy	A broader chain that returns to its start	Closure queries never terminate or return everything	Fail the build
Related plus hierarchical (S27)	Two concepts both broader-linked and related	Query expansion double-counts; a specification violation	Fail the build
Ambiguous preferred label	Two concepts, same prefLabel, same language	Indexers pick at random; tagging becomes noise	Fail the build
Orphan concept	No broader, no narrower, no related	Unreachable by browsing; only findable if already known	Warn, review at release
Disconnected cluster	A group of concepts with no path to any top concept	A whole branch invisible to navigation	Warn, review at release
Missing language coverage	Concept lacks a prefLabel in a declared language	Silent gaps in multilingual retrieval	House SHACL shape
Missing scope note	Concept boundary undocumented	Meaning drifts under a stable URI, undetected	House SHACL shape
Undefined SKOS resource	Uses skos:prefferedLabel or similar invention	Tools silently ignore the triple	Fail the build

The last row deserves a comment, because it is the quiet killer of RDF generally. A misspelled property is not an error in RDF, it is a new property nobody has heard of. Nothing warns you. The vocabulary loads, the concept page renders without a label, and the bug survives until a human notices a blank. This is why the CI job must check that every property used in the SKOS namespace actually exists in the SKOS namespace, and it is the cheapest check on the list.

Change: deprecate, never delete

The rule is absolute and the reason is that you do not know who is pointing at the concept. When a concept goes away, mark it deprecated with owl:deprecated true, record what happened in a skos:historyNote or skos:changeNote with a date, and where there is a successor, link it, conventionally with dcterms:isReplacedBy. Keep the URI resolving forever. A deprecated concept that still dereferences and explains itself lets a downstream consumer discover the change and migrate; a 404 lets them discover nothing.

Three change types cause almost all the pain, and they are worth naming so the editorial board can recognise them. A merge is survivable: two concepts become one, both URIs stay, one is deprecated and points at the survivor, and downstream tags remain interpretable. A split is dangerous: one concept becomes two, and every existing tag is now ambiguous, because nothing recorded which of the two senses was meant. The only honest handling is to deprecate the original, mint two new URIs, and accept that the historical tags need review rather than automatic migration. A silent re-scoping, where the label and URI stay and only the intended boundary moves, is the worst of the three because no tool can detect it. Scope notes plus a change note are the only defence, which is the practical argument for the discipline lesson 7 recommended.

What breaks · reusing a URI after a concept split

Eighteen months in, the register’s scheme has one concept for pumps and three hundred work orders tagged with it. Reliability engineering points out, correctly, that centrifugal and positive displacement pumps fail in completely different ways and lumping them together makes the failure statistics meaningless. The scheme is split. An editor, being tidy, keeps the existing URI for the larger of the two groups and mints one new URI for the other.

# Before: one concept, 300 work orders tagged with it
ex:Pump  skos:prefLabel "Pump"@en .

# After the "tidy" split: same URI, narrower meaning
ex:Pump  skos:prefLabel "Centrifugal pump"@en .
ex:PDPump a skos:Concept ; skos:prefLabel "Positive displacement pump"@en .

No system errors. Nothing fails validation: the vocabulary is structurally perfect, and Skosify and qSKOS both pass it, because this is a semantic change and neither tool can see semantics. But all three hundred historical work orders have just been re-tagged, retroactively and invisibly, as centrifugal pumps, including the forty that were positive displacement. The failure statistics that motivated the split are now wrong in a new and more confident way, and the audit trail says nothing happened. Six months later someone computes mean time between failures for centrifugal pumps and gets a number contaminated by a different technology, with no artefact anywhere in the system pointing at the cause.

The rule that prevents it is mechanical: a URI’s meaning may be narrowed by nothing and clarified only by a scope note that does not change what it covers. On a genuine split, deprecate the original, mint two new URIs, link both back with dcterms:isReplacedBy or a documented change note, and put the historical tags into a review queue rather than migrating them by rule. That is more work and it is visibly more work, which is the entire point: the cost lands on the editor who has the context, not on an analyst two years later who does not. The general principle is the one behind every deprecation policy in software. Identifiers are promises to strangers, and the stranger cannot renegotiate.

Check yourself

Your CI runs Skosify and qSKOS on every change to a published scheme, and both pass cleanly. An editor then changes a concept’s preferred label from “Pump” to “Centrifugal pump” and adds a scope note saying the concept never covered positive displacement pumps. What is the correct reading?

The tools cannot detect this class of change at all, so it must be caught by editorial review and a change note
The change is safe, because the tools passed and the scope note documents the boundary
The change is unsafe, and adding a SHACL shape for label stability would catch it
The change is safe only if the concept has no narrower concepts

Show the answer, and why each wrong option is wrong

A is correct. Whether this edit is a harmless clarification or a destructive re-scoping depends entirely on a fact no tool holds: what the three hundred existing tags were actually intended to mean. If the concept genuinely never covered positive displacement pumps, this is a good change and the scope note is overdue. If it did, this is the silent re-scoping from the block above, wearing a scope note as a disguise. Structural validators check structure; only a human with the tagging history can adjudicate meaning, which is why the editorial board is infrastructure and not ceremony.

B mistakes passing validation for being correct, which is the single most common error in vocabulary operations. Skosify and qSKOS check for cycles, orphans, ambiguous labels and undefined resources; none of those is what changed here. C is the strongest wrong answer, because it is half right about the risk and wrong about the remedy. A shape forbidding preferred label changes would fire on this edit, but it would fire on every legitimate translation fix and typo correction too, and a gate that cries wolf is switched off within a month. Worse, it addresses the symptom: an editor determined to re-scope can leave the label alone entirely, and the shape sees nothing. D invents a constraint that has no bearing on the problem. Narrower concepts affect how the change propagates through the hierarchy; they say nothing about whether the meaning of existing tags has moved.

Apply it to your work

Lesson Content

Previous Quiz

Back to Course

Next Quiz