A vocabulary you can govern.

Why a controlled vocabulary at all

A controlled vocabulary is the fixed set of values a field is allowed to take — the perils you underwrite, the statuses a claim moves through, the currencies you settle in, the lines of business you write. It is agreed once, governed centrally, and reused everywhere. It is not the shape of the model; it is the content that fills it.

The tool for this is SKOS — the W3C Simple Knowledge Organization System, built for exactly one job: representing the code lists, taxonomies, thesauri and glossaries that classify things, as a graph of concepts rather than a hierarchy of logical classes.

This brief is the companion to the namespace policy: that one fixes where a scheme’s IRIs live (the /vocabulary/ root); this one shows how to build what lives there — and, most of all, how a second team extends a vocabulary it does not own.

The instinct is to model each code as an owl:Class — Flood, Fire, Windstorm all under a Peril class. It reads well and it is wrong for four reasons:

• Class explosion. A few hundred perils, statuses and industry codes become a few hundred near-empty classes cluttering the T-Box, each existing only to be a label.
• Reasoner burden. A DL reasoner must classify every one of them. Values carry no logical structure worth reasoning over, so the cost buys nothing.
• Governance friction. The business cannot add “Storm Surge” without an ontology change, a review and a release. Reference data should move on its own clock, not the model’s.
• Profile risk. Bending classes to carry synonyms, multilingual labels and ordering drags the model toward OWL Full — against an OWL 2 DL profile.

SKOS answers all four. A code is a skos:Concept — an individual, not a class — gathered into a skos:ConceptScheme. Concepts carry labels, notations, hierarchy and definitions without ever entering the class hierarchy the reasoner classifies. The vocabulary lives in its own graph and its own file; the ontology references it. The T-Box stays small and DL-clean; the value set grows freely.

One code list, three ways to model it

Code list, taxonomy, thesaurus and glossary are not four technologies. They are four points on a single SKOS continuum. Every one is a skos:ConceptScheme of skos:Concepts — they differ only in which SKOS properties you switch on. That is the quiet superpower here: a flat code list can grow into a full thesaurus without re-platforming, keeping the same IRIs the whole way.

Shape 1 — code list

Flat and finite. Every concept is a skos:topConceptOf the scheme; there is no broader. The skos:notation carries the machine code the business already uses.

# /vocabulary/ins/claim-status/ — a flat code list
@prefix cstat: <https://data.chubb.com/vocabulary/ins/claim-status/> .
@prefix skos:  <http://www.w3.org/2004/02/skos/core#> .
@prefix dct:   <http://purl.org/dc/terms/> .

cstat:  a skos:ConceptScheme ;
        dct:title "Chubb Claim Status"@en ;
        owl:versionInfo "0.1" .

cstat:Open   a skos:Concept ; skos:topConceptOf cstat: ;
        skos:prefLabel "Open"@en ;   skos:notation "OPN" .
cstat:Closed a skos:Concept ; skos:topConceptOf cstat: ;
        skos:prefLabel "Closed"@en ; skos:notation "CLS" .
cstat:Reopened a skos:Concept ; skos:topConceptOf cstat: ;
        skos:prefLabel "Reopened"@en ; skos:notation "ROP" .

Shape 2 — taxonomy

Add skos:broader / skos:narrower (they are inverses) to classify. For “all descendants” queries use the transitive super‑properties skos:broaderTransitive / narrowerTransitive — broader itself is deliberately not transitive, so you assert one level and query many.

# /vocabulary/ins/line-of-business/ — a classification tree
@prefix lob: <https://data.chubb.com/vocabulary/ins/line-of-business/> .

lob: a skos:ConceptScheme ; dct:title "Chubb Lines of Business"@en .

lob:Property a skos:Concept ; skos:topConceptOf lob: ;
        skos:prefLabel "Property"@en .

lob:CommercialProperty a skos:Concept ; skos:inScheme lob: ;
        skos:prefLabel "Commercial Property"@en ;
        skos:broader   lob:Property .          # one level asserted…

lob:CommercialFlood a skos:Concept ; skos:inScheme lob: ;
        skos:prefLabel "Commercial Flood"@en ;
        skos:broader   lob:CommercialProperty . # …descendants inferred via broaderTransitive

Shape 3 — thesaurus

A taxonomy that also captures how people say things and how concepts relate: skos:altLabel for synonyms and abbreviations, skos:hiddenLabel for misspellings and retired forms (indexed for search but never shown), and skos:related for a non‑hierarchical association. This is the ISO‑25964 thesaurus, expressed in SKOS.

# /vocabulary/ins/peril/ — hierarchy + synonyms + association
@prefix peril: <https://data.chubb.com/vocabulary/ins/peril/> .

peril:Flood a skos:Concept ; skos:inScheme peril: ;
        skos:prefLabel   "Flood"@en ;
        skos:altLabel    "Inundation"@en ;    # a synonym — searchable, shown
        skos:hiddenLabel "Flud"@en ;          # a misspelling — searchable, never shown
        skos:notation    "FLD" ;
        skos:broader     peril:WaterDamage ;    # hierarchical (BT/NT)
        skos:related     peril:StormSurge ;     # associative (RT)
        skos:definition  "A temporary covering by water of land not normally covered by water."@en .

Shape 4 — glossary

Here the concept exists for its definition. The term is the headword; the meaning is carried in the SKOS documentation properties — skos:definition, skos:scopeNote (how and where to use it), skos:example, and the editorial notes. A glossary is a thesaurus whose centre of gravity is the note, not the hierarchy.

# /vocabulary/ins/glossary/ — definitional concepts
@prefix term: <https://data.chubb.com/vocabulary/ins/glossary/> .

term: a skos:ConceptScheme ; dct:title "Chubb Insurance Glossary"@en .

term:Subrogation a skos:Concept ; skos:inScheme term: ;
        skos:prefLabel  "Subrogation"@en ;
        skos:definition "The insurer's right, after paying a claim, to pursue a third party that caused the loss."@en ;
        skos:scopeNote  "Used in claims recovery; distinct from salvage."@en ;
        skos:example    "After settling a fire claim, the insurer subrogates against the negligent contractor."@en ;
        skos:related    term:Salvage .

Everything above is built from a small, fixed set of terms. This is the whole toolkit — group it in your head as scheme, labels, relations, notes, grouping and mapping.

The integrity rules that keep a scheme consistent

• One prefLabel per language. A concept may have many altLabels but only a single preferred label in each language.
• The three label types are disjoint. A given string is a prefLabel, an altLabel or a hiddenLabel — never two at once on the same concept.
• Associative and hierarchical don’t overlap. skos:related is disjoint from broaderTransitive — two concepts are either ancestor/descendant or associates, not both.
• The code goes in skos:notation, the token in the IRI. …/peril/Flood is a readable, permanent handle; "FLD" is the governed business code that may have its own datatype.
• exactMatch is transitive and symmetric; closeMatch is neither. Don’t chain a run of closeMatch links and treat the ends as equivalent.

The T-Box never contains the codes; it points at them. A property ranges over skos:Concept, an instance links to a shared concept, and the code list evolves on its own without a single edit to the model. OWL’s rdfs:range can only say “a concept”; to say “a concept from this scheme” use a SHACL shape — validation, not schema — which is exactly what a shapes/ layer is for.

# T-Box (claim.ttl) — reference the scheme by range; don't embed the codes
claim:hasPeril  a owl:ObjectProperty ;
        rdfs:range skos:Concept .

# SHACL (shapes/) — the value must be a peril concept, drawn from peril:
claim:ClaimShape a sh:NodeShape ; sh:targetClass claim:Claim ;
    sh:property [ sh:path claim:hasPeril ;
                  sh:class skos:Concept ;
                  sh:node [ sh:property [ sh:path skos:inScheme ;
                                          sh:hasValue peril: ] ] ] .

# A-Box (resource/) — the fact points at the shared concept
ex:Claim-100  a claim:Claim ;
        claim:hasPeril peril:Flood .   # the same IRI the whole enterprise uses

Concept or class? The boundary

Not every domain notion is a value. Use this test when you’re unsure which side of the seam a thing belongs on:

Most domains need both: a small class backbone in OWL and a large governed value list in SKOS, joined at the seam. Keep concepts as individuals — do not pun a concept as a class — and the model stays in OWL 2 DL.

This is where controlled vocabularies most often go wrong. A regional team, a new line of business or a partner needs to add or refine values — and reaches into the enterprise scheme to do it. Don’t. The same golden rule that governs ontology extensions governs vocabularies: mint in your own scheme, and link across.

The four mapping properties — and what each claims

Reserve exactMatch for genuine equivalence — because it is transitive, a careless one propagates. When two concepts are “basically the same” but you’re not certain, closeMatch is the honest choice.

The pattern in Turtle

A UK flood team needs finer perils than the enterprise scheme carries. It builds its own hierarchy and hangs the roots under the enterprise concept — without ever writing into peril:.

# /vocabulary/uk/peril/ — a regional refinement, in its own namespace
@prefix ukp:   <https://data.chubb.com/vocabulary/uk/peril/> .
@prefix peril: <https://data.chubb.com/vocabulary/ins/peril/> .   # the enterprise scheme — read-only to us

ukp: a skos:ConceptScheme ; dct:title "UK Flood Perils"@en ; owl:versionInfo "0.1" .

ukp:CoastalFlood a skos:Concept ; skos:inScheme ukp: ;
        skos:prefLabel  "Coastal Flood"@en ;
        skos:broadMatch peril:Flood .          # root of my tree hangs under theirs

ukp:StormSurge a skos:Concept ; skos:inScheme ukp: ;
        skos:prefLabel  "Storm Surge"@en ; skos:notation "STS" ;
        skos:broader    ukp:CoastalFlood ;     # hierarchy *within* my scheme
        skos:broadMatch peril:Flood .          # …and anchored to the enterprise concept

Two ways to extend — one right, one wrong

Normative. MUST rules are invariants a reviewer or a SHACL shape can check; SHOULD rules are strong defaults you break only with a recorded reason.

Concrete first schemes to mint under /vocabulary/, with the shape each naturally takes. The green rows sit in the foundation layer because they’re standards‑based and shared across every domain.

Every one of these is the same machine underneath: a scheme, some concepts, the right SKOS properties switched on for the job — governed as data, referenced by the model, and open for any domain team to extend from its own namespace.