Shared understanding
Among people or software agents. If sites publish the same underlying ontology, agents can extract and aggregate across them.
A 2001 guide that already anticipated the agent
Written for domain experts rather than AI laboratories, in the era of Protégé-2000 and frame systems. Its first stated reason for building an ontology is "to share common understanding of the structure of information among people or software agents" — a phrase that read as boilerplate in 2001 and is now the whole point.
| Field | Value |
|---|---|
| Title | Ontology Development 101: A Guide to Creating Your First Ontology |
| Authors | Natalya F. Noy, Deborah L. McGuinness — Stanford |
| Length | 25 pages, 8 sections, 9 figures |
| Tooling era | Protégé-2000 (examples), Ontolingua (library), Chimaera (diagnostics); RDF and DAML named as emerging W3C/DARPA work |
| Running example | Wine & food pairing, descended from the CLASSIC tutorial knowledge base (Brachman et al. 1991) |
| Intellectual lineage | Gruber 1993 (definition), Gruninger & Fox 1995 (competency questions), Uschold & Gruninger 1996 and Gómez-Pérez 1998 (alternative methodologies), Rosch 1978 (levels of generality) |
| Source | protege.stanford.edu — ontology101.pdf |
Five reasons to build one (§1)
Reuse of domain knowledge
Time, units, devices: model once, reuse everywhere; or integrate several existing ontologies into a larger one.
Explicit assumptions
Hard-coded assumptions are hard to find, understand and change — especially for someone without programming expertise.
Domain ≠ operational
Describe the task's domain separately from the program that solves it: the same configuration algorithm drives PCs and elevators when each is fed its own ontology.
Analysis
Once terms are declared, they can be analyzed formally — which matters most when reusing or extending someone else's ontology.
Often an ontology of the domain is not a goal in itself. Developing an ontology is akin to defining a set of data and their structure for other programs to use.
101 §1 — the sentence that makes an ontology legitimate as agent context: it is data for a consumer, not a monument.
Noy & McGuinness 2001, §1
VLSC. The consumer here is an agent. The same eight
top-level concepts, the same relations and the same invariants are
read three ways: as agent context before an edit, as a pre-edit gate
that can refuse the edit, and as the vocabulary of human review. One
semantic, three consumers — see
Agentic · Domain Ontology.
Not object-oriented design (§ About this guide).
OO design decides by the operational properties of a class —
what methods it carries. Ontology design decides by the
structural properties — what it is, what it has, what it
relates to. The paper is explicit that the resulting class structure
differs from a similar domain modelled in an OO program.
Classes, slots, facets, instances — and a knowledge base
The paper's working definition, because the AI literature contains many and they contradict one another (§2).
| Term | Also called | What it is (101 §2) | Wine example |
|---|---|---|---|
| Class | concept | A concept in the domain of discourse; the focus of most ontologies. |
Wine, Red Wine,
Pauillac, Winery
|
| Slot | role, property | A property of a class or instance, describing a feature or attribute. |
body, maker, color,
produces
|
| Facet | role restriction | A restriction on a slot: value type, allowed values, cardinality, defaults. |
body: enumerated {light, medium, full};
produces: multiple, instance-type
Wine
|
| Instance | individual | A specific member of a class. Ontology plus instances constitutes a knowledge base. |
Chateau-Morgon-Beaujolais, a winery, a vintage
|
An ontology together with a set of individual instances of classes constitutes a knowledge base. In reality, there is a fine line where the ontology ends and the knowledge base begins.
101 §2
Noy & McGuinness 2001, §2
Developing an ontology, in practical terms (§2)
Define classes→Arrange them in a
taxonomic hierarchy→Define slots and their
allowed values→Fill slot values
for instances
taxonomic hierarchy→Define slots and their
allowed values→Fill slot values
for instances
VLSC. The same four activities, one for one: the
eight top-level classes (Agent, Physical Entity, Software System,
Activity, Information Object, Capability, Policy/Constraint,
Evidence); the relations that arrange them
(
requests, changes, yields,
sampled-as, framed-as, plus
inherits / consumes /
implements / inspired-by between product
families); the facets carried by the 52 machine-readable constraints
(severity, sdd_ref, scope glob,
patterns); and the instances — radio profiles, specific
stations, dated evidence records. Census 2026-09-12.
The rules the paper states before any step
"These rules may seem rather dogmatic. They can help, however, to make design decisions in many cases" (§3). Everything later in the guide is an application of these three.
No single correct model
"There is no one correct way to model a domain — there are
always viable alternatives. The best solution almost always
depends on the application that you have in mind and the
extensions that you anticipate." 101 §3
Necessarily iterative
"Ontology development is necessarily an iterative process."
Start rough, refine, fill in detail — and expect the first
version to be revised once it meets an application or an expert.
101 §3
Close to the domain
"Concepts in the ontology should be close to objects (physical or
logical) and relationships in your domain of interest" — most
likely the nouns and verbs of the sentences that describe it.
101 §3
The paper's own humility, kept verbatim. "There is
no single correct ontology-design methodology and we did not attempt
to define one" (§ About this guide) and, in the conclusion, "there is
no single correct ontology for any domain. Ontology design is a
creative process and no two ontologies designed by different people
would be the same… The proof is in the pudding — we can
assess the quality of our ontology only by using it in applications
for which we designed it" (§8). A method that ends by pointing at use
is a method that must be paired with evidence — which is exactly
where the next section starts.
VLSC. Rule 2 and rule 3 decided the shape of this
site's ontology: repeated concepts and constraints were consolidated
only after evidence appeared across product boundaries —
never designed up front from a whiteboard. The nouns and verbs came
from incident reports and SDD rulings, not from a taxonomy someone
found elegant.
Seven steps, in order
The spine of the guide (§3). Steps 4 and 5 are "closely intertwined… also the most important steps in the ontology-design process" — which is why §4 and §5 of the paper go back over them in detail, and why sections 05 and 06 below do the same.
| Step | What 101 asks | The rule that decides | VLSC artifact |
|---|---|---|---|
| 1 Domain & scope | What domain? For what use? Which questions must it answer? Who uses and maintains it? | Scope is task-shaped: the same domain yields different ontologies for different consumers. | 12 competency questions, five product-family profiles |
| 2 Reuse | What already exists that can be refined or extended? | Reuse may be a requirement, not a preference, once other systems have committed to a vocabulary. | W3C SSN/SOSA, PROV-O, OWL-Time, SKOS, SAREF/QUDT — as conceptual reference; Hamlib vocabulary as a de-facto reuse |
| 3 Enumerate terms | Which terms do we want to make statements about, or explain? | Get the list comprehensive first; do not yet worry about overlap, relations, or class-vs-slot. | Bilingual glossary: CommandIntent, Actuation, Observation, StateReport, DeviceAdapter, Protocol Binding, Control Lease… |
| 4 Classes & hierarchy | Which terms denote objects with independent existence, and how do they generalize? | The is-a test: every instance of B is also an instance of A. | Eight top-level classes; product families as siblings; no artificial intermediate classes |
| 5 Slots | What properties describe each class? Which class does each remaining term belong to? | Attach a slot at the most general class that can have the property. |
Relations requests / changes /
yields; capability and protocol-binding slots
|
| 6 Facets | Value type, allowed values, cardinality, domain, range, defaults? |
Most general domain and range that is not overly general —
never THING.
|
Constraint severity / sdd_ref /
scope / patterns; single-owner
cardinality
|
| 7 Instances | Which individuals, at what granularity, with which slot values? | Individual instances are the most specific concepts the application needs to represent. | Radio profiles (FT-710, IC-7300, IC-7300MK2), dated evidence records, 🐞 reports on the public board |
Step 1 — Domain and scope (§3, Step 1)
The four questions
What is the domain the ontology will cover? For what are we going to use it? For what types of questions should it provide answers? Who will use and maintain it? The answers may change during design, "but at any given time they help limit the scope of the model".
Scope is task-shaped
The paper's own demonstration: the same wine domain needs synonyms and part-of-speech data for natural-language processing, retail pricing for a customer choosing a bottle, wholesale pricing and availability for a buyer stocking a cellar. Three tasks, three ontologies.
Maintainer ≠ user language
"If the people who will maintain the ontology describe the domain
in a language that is different from the language of the ontology
users, we may need to provide the mapping between the languages."
101 §3
Competency questions (§3, Step 1). Sketch the
questions a knowledge base built on the ontology must be able to
answer; they become "the litmus test later" for whether the ontology
holds enough information, at the right level of detail. They are a
sketch and need not be exhaustive. The wine set runs from "Is
Bordeaux a red or white wine?" to "What were good vintages for Napa
Zinfandel?" — and reading them tells you, before any class is drawn,
that vintages and food classifications belong in scope while winery
inventory and restaurant staff do not.
VLSC: twelve competency questions are published in
the appendix of
Evidence Discipline — from "which
software system owns the authoritative state of a given radio?" to
"which safety claim has a real sensor or observation path?".
VLSC on the language rule. This site maintains every
ontology term in two languages on purpose — 控制意图 for
CommandIntent, 现场验证 for Field verified —
because the maintainer thinks in one language and part of the
audience reads the other. The mapping is published, not implied.
Step 2 — Reuse (§3, Step 2)
Almost always worth checking
"It is almost always worth considering what someone else has done and checking if we can refine and extend existing sources for our particular domain and task."
Sometimes a requirement
Reuse stops being optional "if our system needs to interact with other applications that have already committed to particular ontologies or controlled vocabularies".
Formalism usually doesn't matter
Most knowledge-representation systems import and export; where they cannot, translating an ontology between formalisms "is usually not a difficult one".
VLSC — reuse of concepts, not of runtime. W3C
SOSA/SSN supplies the observation–sensor–actuation distinction,
PROV-O the provenance fields, OWL-Time the interval vocabulary, SKOS
the bilingual concept pattern, SAREF/QUDT the device–function–quantity
split, WoT Thing Description the capability-affordance idea. None of
this means an RDF store, a triple database, or a reasoner in the
loop: the ontology stays a lightweight bilingual contract grounded in
product evidence. Separately, Hamlib's own vocabulary
is a reused controlled ontology in the strict sense of the rule —
this site's MRRC family had no choice but to commit to it, because
rigctld already had.
Step 3 — Enumerate terms (§3, Step 3)
Write down every term you want to make statements about or explain to
a user, with its properties and what you want to say about it. Get the
list comprehensive first: "without worrying about overlap between
concepts they represent, relations among the terms, or any properties
that the concepts may have, or whether the concepts are classes or
slots". The sorting happens in steps 4–6, and the paper is explicit
that steps 4 and 5 are intertwined — a few class definitions, then
their properties, then more classes.
Step 4 — Classes and the class hierarchy (§3, Step 4)
Top-down
Start with the most general concepts and specialize:
Wine → red / white / rosé → Syrah, Red Burgundy,
Cabernet Sauvignon.
Bottom-up
Start with the leaves and group upward: Pauillac and
Margaux → Medoc →
Bordeaux.
Combination
Define the salient concepts first, then generalize and specialize. "Often the easiest for many ontology developers, since the concepts 'in the middle' tend to be the more descriptive concepts in the domain" (Rosch 1978).
None is inherently better. The choice "depends
strongly on the personal view of the domain". From the Step-3 list,
pick the terms that describe objects with independent
existence — not terms that describe those objects — and those
become the anchors of the hierarchy. Then arrange them with one test:
if a class A is a superclass of class B, then every instance of B
is also an instance of A; equivalently, B is a "kind of" A.
Every Pinot Noir is necessarily a red wine, so
Pinot Noir is a subclass of Red Wine.
101 §3–§4.1
Step 5 — Slots (§3, Step 5)
Classes alone are not enough
"The classes alone will not provide enough information to answer the competency questions from Step 1." Most of the leftover Step-3 terms become properties of the classes.
Four kinds of property
Intrinsic (a wine's flavor),
extrinsic (its name, its area),
parts — physical or abstract (the courses of a
meal) — and relationships to other individuals
(maker, linking a wine to a winery).
Attach high, inherit down
"A slot should be attached at the most general class that can
have that property." body and color sit
on Wine; tannin level sits on
Red Wine, because white wines are not described by
it. All subclasses inherit.
Step 6 — Facets of the slots (§3, Step 6)
| Facet | What it constrains | Paper's example |
|---|---|---|
| Cardinality | How many values a slot may have: single vs multiple, or an explicit minimum and maximum. Maximum 0 is legal — it says a subclass may not fill the slot at all. |
body single; produces multiple;
grape min 1, max 1 for single-varietal wines
|
| Value type | What kind of value fills the slot: String, Number (Float/Integer), Boolean, Enumerated (Symbol in Protégé-2000), or Instance with a list of allowed classes. |
name String; flavor enumerated
{strong, moderate, delicate}; produces Instance
of Wine
|
| Domain | The classes a slot is attached to — the classes whose property it describes. | Winery is the domain of produces |
| Range | The allowed classes for an instance-typed slot's values. | Wine is the range of produces |
| Default value | A convenience filled in automatically for new instances — which, unlike a slot value, may be changed. See section 06 below. |
"full" as the default body when most wines in
scope are full-bodied
|
The domain-and-range doctrine, in four moves (§3, Step 6).
(1) Find the most general class that can be the domain or range.
(2) But not overly general: every class in the domain must really be
described by the slot, and every class in the range must be a
potential filler — "one would not want to make the range
THING". (3) If the list contains a class and its
subclass, delete the subclass — it adds no information. (4) If it
contains all subclasses of A but not A, use A alone; and if it
contains all but a few subclasses of A, consider whether A is the
better answer. Slot attachment obeys the same rules where attaching
equals declaring the domain: tannin level belongs on
Red Wine, not on each red variety, and not on
Wine.
VLSC. Move (2) is the reason
Protocol Binding ≠ Capability is an axiom here rather
than a preference: a capability declared over an overly general range
("any backend") is a claim no test can falsify. The concrete anchor is
the audio-pyaudio-rate constraint — audio rate comes
from backend capabilities, not from a model name hard-coded at the
call site [AD-011, amended V2.9/V2.14]. Cardinality shows up as an
invariant rather than a facet value: one authoritative state
owner, one serial-port owner (ft8
no-direct-serial [AD-008]; ft710 / modern
cat-direct-serial-io [AD-002]).
Step 7 — Instances (§3, Step 7)
Three moves: choose a class, create an individual of that class, fill
in its slot values. The paper's worked instance,
Chateau-Morgon-Beaujolais, carries eight values — body
light, color red, flavor delicate, tannin level low, grape
Gamay (an instance of Wine Grape), maker
Chateau-Morgon (an instance of Winery),
region Beaujolais (an instance of
Wine-Region), sugar dry. Note what the instance
demonstrates: three of its eight values are themselves instances of
other classes, which is how a knowledge base stays queryable instead
of becoming a pile of strings.
VLSC. Instances are where the evidence lives. A radio
profile (FT-710, IC-7300, IC-7300MK2) is an instance carrying
capability values; a dated evidence record is an instance carrying
source, version, environment, method, result and limitation; a 🐞
report on the public board is an instance carrying a classification.
The paper's granularity rule — "individual instances are the most
specific concepts represented in a knowledge base" — is why a
release is an instance here but a radio model is a
class: releases are counted, models are described.
Twenty ways a class hierarchy goes wrong
Section 4 of the paper is a defect catalogue, not a tutorial: "after defining a considerable number of new classes, it is helpful to stand back and check if the emerging hierarchy conforms to these guidelines." Read it as a review checklist — which is how an agent can use it too.
| # | Trap | The rule (101 §4) | Why it breaks |
|---|---|---|---|
| 1 | is-a read as "related to" | A is a superclass of B only if every instance of B is necessarily an instance of A — a "kind of" relation. §4.1 | Anything vaguely associated becomes a subclass, and inheritance starts carrying properties the child does not have. |
| 2 | Singular under plural |
Never define Wines and then Wine as
its subclass; pick one number and keep it everywhere. §4.1,
§6.2
|
"A single wine is not a kind of wines" — the hierarchy says something false about the domain. |
| 3 | Forgetting transitivity | If B ⊂ A and C ⊂ B then C ⊂ A. §4.1 | Constraints attached high up silently apply three levels down, where nobody expected them. |
| 4 | Direct vs indirect confusion |
A direct subclass has no class between it and its parent;
Chardonnay is a direct subclass of
White Wine, not of Wine. §4.1
|
Sibling analysis and "attach the slot at the most general class" both need the direct relation, not the transitive closure. |
| 5 | Frozen hierarchy in an evolving domain |
When white Zinfandel appeared, Zinfandel had to
split into red and white subclasses under different parents.
§4.1
|
The domain moved; the ontology now asserts a color that some of its own instances do not have. |
| 6 | Confusing a class with its name |
"Classes represent concepts in the domain and not the words
that denote these concepts." Renaming Shrimps to
Prawns changes nothing else. §4.1
|
A terminology change is mistaken for a modelling change, and everything downstream gets rebuilt. |
| 7 | Synonyms as separate classes | One concept, one class; carry synonyms, translations and presentation names as a list, or in documentation. §4.1 |
Shrimp, Prawn and
Crevette as three classes means three places to
maintain one fact.
|
| 8 | Cycles | A ⊂ B and B ⊂ A at once is a declaration that A and B are equivalent. §4.1 | The hierarchy stops being a hierarchy; traversal may not terminate. |
| 9 | Siblings at different levels of generality |
All siblings except those at the root must sit at the same
level of generality — White Wine and
Chardonnay are not siblings. Root-level classes
are major divisions and are exempt. §4.2
|
The tree reads like a book outline with a chapter and a sub-sub-section side by side. |
| 10 | Exactly one subclass | "If a class has only one direct subclass there may be a modeling problem or the ontology is not complete." Like a bulleted list with one bullet. §4.2 | Either the two classes are equivalent (delete one) or the missing siblings have not been found yet. |
| 11 | More than a dozen subclasses | Well-structured ontologies have between two and a dozen direct subclasses; beyond that, intermediate categories are probably needed. §4.2 |
Every wine type flat under Wine hides the Medoc /
Bordeaux and Côtes d'Or / Burgundy structure the domain
already has.
|
| 12 | Invented grouping classes | If no natural class exists to group a long sibling list, leave it flat — "the ontology is a reflection of the real world". §4.2 | An artificial intermediate class is a category nobody in the domain will recognise, and every future instance must be forced into it. |
| 13 | Fearing multiple inheritance |
It is legitimate: Port is both
Red Wine and Dessert Wine, and
inherits sugar = SWEET from one parent and
tannin level from the other. §4.3
|
Refusing it produces duplicate parallel hierarchies that must be kept in sync by hand. |
| 14 | New class with nothing new to say | Introduce a subclass when it has additional properties, different restrictions, or different relationships; in practice it should add slots, add slot values, or override inherited facets. §4.4 | A class that says nothing beyond its parent is a name, not a concept. |
| 15 | A subclass per restriction |
Do not create Delicate Wine,
Moderate Wine… for each value of a slot; the
distinction belongs in the slot value. §4.4–§4.5
|
Class explosion, and every facet of a value becomes a node in the tree. |
| 16 | Denying terminological hierarchies | Reference hierarchies (a classification of diseases) may add no properties at all and are still worth having: they support navigation and let the user pick a level of generality. §4.4 | Insisting every class earn new slots flattens vocabularies whose whole job is to organise terms. |
| 17 | Classes that instances migrate between |
"A class to which an individual instance belongs should not
change often." Chilled Wine is an attribute, not
a class. §4.5
|
Extrinsic properties used as class criteria make instances change class during their lifetime — and take their inherited facets with them. |
| 18 | Instances where a hierarchy exists | If concepts form a natural hierarchy, make them classes — all wine regions are classes, marked abstract where they have no direct instances. There is no such thing as a sub-instance. §4.6 |
Bourgogne as an instance cannot have
Côtes d'Or under it, so the natural structure is
lost.
|
| 19 | Over- and under-scoping | Do not specialise or generalise more than the application needs — "at most one extra level each way"; do not include every property or every conceivable relation. §4.7 | Label paper and shrimp recipes enter a wine-pairing ontology; maintenance cost rises and the competency questions do not. |
| 20 | Undeclared disjointness |
Declare classes disjoint when they cannot share instances —
Red Wine and White Wine are,
Dessert Wine and White Wine are not.
§4.8
|
Without the declaration the system cannot flag a class
subclassed from both Riesling and
Port as the modelling error it is.
|
The three hard decisions, in detail
A new class, or a property value? (§4.5)
Create a class for the distinction when
(a) the concepts with different values become
restrictions on slots of other classes, or
(b) the distinction matters in the domain and
you think of the two as different kinds of object. Otherwise keep
it in the slot value. Wine colour is the paper's exception that
proves the rule: colours are normally values, but a red wine and
a white wine pair with different foods, so
Red Merlot and White Merlot are two
classes.
A class, or an instance? (§4.6)
Decide the lowest granularity the application needs — "the most
specific concepts that will constitute answers to [the competency
questions] are very good candidates for individuals". Pairing wine
with food stops at Sterling Vineyards Merlot; adding
a restaurant inventory pushes individual bottles down to
instances; recording per-vintage properties makes the vintage the
instance and the wine the class.
Limiting the scope (§4.7)
True statements may still be out of scope. An experimenter is a biological organism, but for an ontology of biology experiments that subclass would attach weight, age and species slots to every experimenter — irrelevant data, and a trap for reusers. The paper's instruction is the important half: record such design decisions in the documentation, so someone reusing the ontology for another application knows the fact was excluded deliberately.
VLSC — trap 20 is a live invariant here. Declaring
disjointness is how a model becomes checkable, and this site declares
several: transmit and receive states are disjoint and a station must
be in exactly one; an authoritative state owner and a client
projection are disjoint, which is the formal content of "clients may
project or request state; they do not silently become the station
authority". The same move guards the evidence ladders: a
process badge (B1–B4, was the engineering constrained?) and a
product badge (design target → field verified, is the
behaviour true?) are declared disjoint on purpose, so that no number
of green constraints can be read as a bench result. See
Evidence Discipline.
VLSC — traps 10 to 12, decided by evidence. The five
product families are siblings under one engineering system, and no
sixth grouping class was invented to make the tree prettier; where a
natural middle concept did exist, it was taken —
RadioBackend and RadioCapabilities generalise
the FT-710 vertical slice into the Modern platform, which is trap 11
fixed by an intermediate category the domain actually uses. The
reverse case is documented too: SunsdrMobile is a client of
SunMRRC, not a product family, and saying so is what stops a
single-subclass branch appearing next to it.
Inverse slots and the default/value distinction
Section 5 of the paper is short and easily skipped. Both of its topics are about redundancy and enforcement — the two things that decide whether a model can be trusted by a machine.
Inverse slots (§5.1)
maker on Wine and
produces on Winery are the same fact
stated twice. Storing both directions is redundant: an application
can always infer one from the other. But from a
knowledge-acquisition standpoint both are convenient, because a
user may know the wine in one session and the winery in another —
so the system fills the inverse automatically and keeps the base
consistent.
The rule worth keeping: declare the pair, store it once, let the system maintain the mirror.
Default values vs slot values (§5.2)
A default is convenience: when most instances share a value, new instances are pre-filled and may then be changed. It "does not enforce any new restrictions on the model or change the model in any way".
A slot value is different: if
sugar = SWEET is a value on
Dessert Wine, then every subclass and instance
carries it and it cannot be changed. One is a starting point; the
other is a constraint.
VLSC — the distinction cost a real incident. Audio
sample rate on the FT-710 path was treated as a fixed value
(44.1 kHz, attached to the model) when it was in fact a capability
the backend reports. The correction is recorded as AD-011, amended in
V2.9 and V2.14, and pinned by the
audio-pyaudio-rate constraint: rate comes from backend
capabilities. Read in the paper's terms, a value was declared where a
default — or better, a lookup — belonged, and the model asserted
something the hardware was free to contradict.
VLSC — inverse pairs, and which side is authoritative.
Several relations here are genuinely inverse: a station's control
lease holder and the holder's leased stations; a
CommandIntent and the StateReport that
answers it; a 🐞 report and the answer page that closes it. The
mirror is maintained by the server, never by the client — and that
asymmetry is a safety invariant, not a convenience: a projection may
display the mirrored value, but only the authoritative side may write
it. CommandIntent ≠ Actuation and
Observation → StateReport are the ontology saying the
same thing twice: a command is not confirmed state, and only an
observation closes the loop. The ft710
ptt-release-no-verify constraint is the honest exception,
declared as such — TX0 is fire-and-forget, so there is no mirror to
maintain and no confirmation to infer [AD-007; Ch15; V1.2].
"Define a naming convention for classes and slots and adhere to it"
Section 6 of the paper. Naming is presented as a modelling safety device, not cosmetics: consistency is what prevents the singular / plural class error, and an explicit convention is what makes a term recognisable as a class or a slot at a glance.
| Decision (101 §6) | What the paper says | VLSC convention |
|---|---|---|
| System constraints first |
Choose the convention around the knowledge-representation
system: one namespace or separate ones for classes, slots and
instances; case sensitivity; which delimiters are legal.
Protégé-2000 is case-sensitive with a single namespace, so a
class Winery and a slot winery
coexist but two winerys do not.
|
The "system" is a repository plus an agent runtime: names must
survive as identifiers in code, as keys in
harness/index.json, and as search terms in a
constraint registry — so ASCII, no spaces, case-significant.
|
| Capitalisation | Capitalise class names, lower-case slot names, assuming the system is case-sensitive. |
Classes and ontology terms PascalCase:
CommandIntent, StateReport,
DeviceAdapter, ControlLease.
Relations lower-case: requests,
changes, yields,
inherits, consumes,
implements, inspired-by.
|
| Delimiters | Space, CamelCase, or an underscore / dash — and if you use delimiters, also decide whether each word is capitalised. Spaces are intuitive but may not survive the systems you interoperate with. |
Constraint IDs are kebab-case and read as a rule, not a thing:
cat-no-dn, no-direct-serial,
poll-stale-guard, vendor-readonly,
ptt-authority. Multi-word ontology relations use
a hyphen for the same reason.
|
| Singular or plural |
Neither is better; singular is more common in practice. Pick
one, keep it throughout — some systems make you declare the
choice in advance. Consistency is also what prevents
Wine under Wines.
|
Singular for every class and term: Product Family, Physical Entity, Information Object. Plural appears only in prose, never in a term. |
| Prefix / suffix |
has- or -of on slot names makes a
term self-identifying as a slot, at the cost of longer names.
|
Not used: verb-form relations (requests,
yields) are already unambiguous against
PascalCase classes, so the prefix would be noise.
|
| Do not annotate the kind | Never add "class", "property" or "slot" to a concept name — the context and the convention already say what it is. | Followed. The one deliberate exception is the evidence ladder, where the badge text names its own kind (Field verified, Bench pending) because the badge is read out of context, in tables and release notes. |
| Avoid abbreviations |
"Use Cabernet Sauvignon rather than
Cab."
|
Followed with one honest caveat: the radio domain's controlled vocabulary is abbreviations — PTT, CAT, SWR, IQ, EFHW, QSO, VFO, DNR. These are terms, not shorthand, and the bilingual glossary carries the expansion. The rule that actually applies is: no invented abbreviations. |
| Subclass naming |
Direct subclasses either all include the superclass name or
all omit it: Red Wine and White Wine,
or Red and White — never one of each.
|
Product names follow their family: MRRC Universal, MRRC FT-710, MRRC Modern, MRRC-FT8 — the family token is present in all of them, and SunMRRC keeps its own root because it is a different track, not a subclass. |
| Synonyms and translations | Many systems attach a list of synonyms, translations or presentation names to a class; where they cannot, list them in the class documentation. §4.1, §6 |
The bilingual glossary is exactly this list, published:
控制意图 / CommandIntent, 执行活动 /
Actuation, 观测活动 / Observation,
现场验证 / Field verified. Two names, one concept —
never two concepts.
|
The whole guide as 24 checks
Written so that it can be run by a person reviewing a model, or handed to an agent as the acceptance list for an ontology change. Every item traces to a section of the paper.
A · Before you model
-
Write the four scope questions down.
Domain, intended use, questions to answer, who maintains it — dated, because they will change.§3 Step 1 -
Sketch the competency questions.
They are the litmus test for everything built later, and they need not be exhaustive.§3 Step 1 -
Search for what already exists.
Record what you adopted, what you only consulted, and what you were forced to commit to.§3 Step 2 -
Enumerate terms before sorting them.
Comprehensive list first; class-vs-slot decided later.§3 Step 3
B · Building the hierarchy
-
Pick an approach deliberately.
Top-down, bottom-up, or combination — the last is usually easiest, because middle-level concepts are the most descriptive.§3 Step 4 -
Anchor on independent existence.
Terms that denote objects, not terms that describe them.§3 Step 4 -
Apply the is-a test to every pair.
Every instance of the child is necessarily an instance of the parent.§4.1 -
Keep siblings at one level of generality.
Root classes are exempt: they are major divisions.§4.2 -
Two to a dozen subclasses.
One is a smell; more than a dozen asks for an intermediate category — but never an invented one.§4.2 -
No cycles, no synonym classes.
A cycle declares equivalence; a synonym is another name for the same concept.§4.1
C · Slots and facets
-
Attach each slot as high as it truthfully goes.
The most general class that can have the property.§3 Step 5 -
Classify every property.
Intrinsic, extrinsic, part, or relation to another individual.§3 Step 5 -
Declare cardinality and value type.
Including minimum, maximum, and the legitimate maximum of 0.§3 Step 6 -
Set domain and range general — but not
THING.
Every class in the domain must be described by the slot; every class in the range must be a potential filler.§3 Step 6 -
Prune the domain and range lists.
Drop a subclass when its superclass is present; collapse a complete enumeration into the parent; reconsider the parent when all but a few subclasses are listed.§3 Step 6
D · Class, value, or instance
-
Introduce a class only when it has something new to
say.
New properties, different restrictions, or different relationships.§4.4 -
Keep distinctions in slot values by default.
Promote to a class when the values become restrictions elsewhere, or the domain treats them as different kinds of thing.§4.5 -
No classes that instances migrate between.
Chilled wine is an attribute, not a taxon.§4.5 -
Fix granularity from the competency
questions.
And promote natural hierarchies to classes — abstract ones where they have no direct instances.§4.6
E · Names
-
Write the convention down and follow it.
Capitalisation, delimiters, singular vs plural — chosen around the system you are actually in.§6 -
No invented abbreviations, no kind annotations.
And subclass names either all carry the parent's name or none do.§6.2–§6.4 -
One concept, many names.
Synonyms and translations attach to a class; they never become sibling classes.§4.1, §6
F · Governance
-
Document what you excluded and why.
An experimenter is a biological organism; this ontology says otherwise, on purpose — and the documentation must say so, or a reuser will be misled.§4.7 -
Declare disjointness, then use the model.
Where classes cannot share instances, say so — it is what lets a tool catch the error. Then assess quality the only way the paper allows: by using it.§4.8, §8
The seven steps, audited against a live ontology
What the paper asks for, what exists here, and — because an audit that only lists successes is advertising — what is missing. Census 2026-09-12; artifacts named so each row can be checked.
| Step | Present | Anchor | Gap / limitation |
|---|---|---|---|
| 1 Scope & competency questions | Yes | 12 published competency questions; five product-family profiles; scope stated per family in Product Families | The questions are prose, not executable: nothing fails a build when one of them stops being answerable. |
| 2 Reuse | Yes, conceptual | W3C SOSA/SSN, PROV-O, OWL-Time, SKOS, WoT TD; ETSI SAREF and QUDT; Hamlib's vocabulary as a forced commitment | No formal import: nothing is loaded from those namespaces at runtime, so the alignment is a claim maintained by hand. |
| 3 Term enumeration | Yes | Bilingual core glossary, 12 term pairs, published in the appendix | No synonym list beyond the EN/ZH pair; radio-domain aliases (CAT vs rig control, PTT vs transmit trigger) are not carried as declared synonyms. |
| 4 Classes & hierarchy | Yes, deliberately shallow |
Eight top-level classes; product families as siblings;
RadioBackend / RadioCapabilities as
the one earned intermediate level
|
Depth is at most two below the top level. That is a scope decision, not an accident — but it means the is-a test is rarely stressed. |
| 5 Slots | Yes |
requests, changes,
yields, sampled-as,
framed-as; family relations
inherits / consumes /
implements / inspired-by
|
Relations are documented in prose and SVG diagrams, not in a schema a tool can traverse. |
| 6 Facets | Partly — and better than prose where it counts |
52 machine-readable constraints across three repositories,
each with severity (block / warn /
info), sdd_ref, scope
glob and patterns; cardinality as an invariant
(one authoritative state owner, one serial owner)
|
These are enforcement facets on code, not declared facets on ontology slots. Domain and range of the relations are never stated formally. |
| 7 Instances | Yes | Radio profiles (FT-710, IC-7300, IC-7300MK2); dated evidence records; 🐞 reports classified on a public board | Instances live in three places (code profiles, release notes, the board) with no shared identity scheme. |
| §4.8 Disjointness | In prose | TX vs RX state; authoritative owner vs client projection; process evidence (B1–B4) vs product evidence (design target → field verified) | Not machine-declared, so no tool can flag a violation — the check is a human reading the invariants. |
| §6 Naming | Yes | PascalCase terms, lower-case relations, kebab-case constraint IDs, singular class names, published bilingual pairs | The convention is observable but unwritten: it lives in the artifacts, not in a style document an agent can load. |
| §8 Assessment by use | Yes — stronger than the paper |
Three consumers of one semantic: agent context,
PreToolUse(Edit|Write) gate, human review; a
reproducible block trace
(sdd_context.py check → exit 2)
|
Use is measured as blocked edits, not as answered competency questions. The litmus test of Step 1 is still manual. |
The honest summary. This ontology is strong exactly
where the paper is silent — runtime consumption, enforcement,
provenance — and weak exactly where the paper is strong: formal
domain and range, declared disjointness, a written naming convention,
executable competency questions. Neither half cancels the other. An
ontology that agents load but cannot be reasoned over, and an ontology
that reasons beautifully but nobody consumes, are two different
failures.
Where 101 stops — and what an agent adds
Reading a 2001 guide in 2026 requires naming its frame. None of this is criticism; the paper says of itself that it is "a starting point", and it is still the clearest one.
No metric beyond use
Quality is assessed by using the ontology in the application it was designed for — "the proof is in the pudding" (§8). The only tooling named is Chimaera, for logical correctness and common design errors. There is no cost model, no coverage measure, no notion of a regression.
No governance over time
Evolution appears once, as an anecdote about white Zinfandel (§4.1). There is no versioning, no ownership, no ruling process, no account of who may change a class and on what evidence.
No adversarial consumer
The consumers imagined are applications and knowledge-based systems that read the model. The paper never considers a consumer that can edit the codebase — which is the consumer that turns an ontology from documentation into a gate.
Frames, not the semantic web
Slots attach to classes; defaults exist; RDF and DAML are named as emerging work. An OWL 2 reading differs in kind: properties are global with declared domain and range, the open-world assumption applies, and there are no default values at all.
No responsibility
Nothing in the guide asks who is accountable when a model is wrong, who may authorize an action taken on the strength of it, or how a decision is traced back to the person who made it.
Nodes, not edges
101 is a discipline for making nodes meaningful. It does not address the quality of the links between them — which is the variable that decides whether a network of models, tools and people compounds or merely amplifies noise.
What an agentic setting adds
The ontology becomes runtime context
Loaded before the first edit rather than consulted after a
question arises — AGENTS.md, the living SDD, and a
routing index that holds no content so references never go stale.
Facets become enforceable
Severity, sdd_ref, scope and
patterns turn a modelling rule into a
PreToolUse hook that can refuse an edit before it
lands, with a non-zero exit code as the receipt.
Provenance becomes mandatory
Every claim carries source, version, environment, method, result, date and limitation — and evidence is snapshotted rather than accumulated, because a number without a cutoff time is a rumour with decimal places.
Incidents become axioms
The paper's iterative loop gets a concrete driver: a field incident becomes an SDD ruling, the ruling becomes a machine-readable constraint, the constraint blocks the re-introduction. An incident is only fixed when it becomes a guard.
A responsibility graph beside the capability graph
For every link that lets something act: who supplied the data, who chose the objective, who authorized the action, who observed the consequence, who can stop it. Recursive improvement is sustainable only when capability links and responsibility links grow together.
Edge quality as a sibling discipline
Six properties — clear semantics, traceable provenance, closed feedback, bounded authority, fault isolation, reviewable objectives — are what 101's node discipline needs on the links between nodes. See Connection Quality.
There is no single correct ontology for any domain. Ontology design is a creative process and no two ontologies designed by different people would be the same. "The proof is in the pudding" — we can assess the quality of our ontology only by using it in applications for which we designed it.
101 §8 — and in 2026 the application includes a consumer that reads the model, edits the code, and can be refused by it.
Noy & McGuinness 2001, §8
Sources, and where to go next
The paper and its lineage
-
Noy & McGuinness, Ontology Development 101
(2001)
— the source of every
101 §xcitation on this page. - Gruber (1993) — the definition of an ontology as an explicit specification.
- Gruninger & Fox (1995) — competency questions as the scope device and the litmus test.
- Uschold & Gruninger (1996); Gómez-Pérez (1998) — the alternative methodologies the paper points to.
- McGuinness et al. (2000), Chimaera — diagnostics for logical correctness and common design errors.
- Brachman et al. (1991), CLASSIC — where the wine-and-food example comes from; Rosch (1978) — levels of generality.
- Duineveld et al. (2000), WonderTools? — a comparative study of ontology engineering tools.
Standards consulted (conceptual reuse)
- W3C SOSA/SSN — observation, sensor, actuation.
- W3C PROV-O — provenance fields for evidence records.
- W3C Time Ontology — instants, intervals, timed workflows.
- W3C SKOS — the bilingual concept pattern.
- W3C OWL 2 Overview — the property-centric alternative frame; not a runtime requirement here.
- W3C Web of Things Thing Description, ETSI SAREF, QUDT — devices, functions, quantities and units.
On this site
- Agentic · Domain Ontology — the live model this page audits.
- Agentic · Connection Quality — the edge-side companion discipline.
- Agentic · Evidence Discipline — competency questions, the two ladders, the ledger.
- Engineering Mechanism — harness, loops, living SDD.
- The Three Axes — the seven steps walked on a real product line, with numbers.
- Connections Rule — why link quality, not link count, is the scarce resource.