Worked example: the Ontology 101 wine & food ontology
Generated by npm run example (examples/build-wine.ts). Every command below was really run, and the output under it is what okb printed.
It follows the paper’s running example. Where the paper leaves a detail open, the choice made here is recorded as a design decision.
$ okb init wine --name "Wine and Food"
Step 1: Scope and competency questions#
The paper’s scope: wines, food, and which combinations are good. Inventory and staff are explicitly left out.
$ okb scope --domain "Wines, foods, and which wines go well with which foods" --purpose "Suggest good wine and food combinations for a restaurant menu and answer diners' questions" --users diners,waiters --maintainers sommelier --out-of-scope "winery inventory" --out-of-scope "restaurant staff"
Wine and Food
domain Wines, foods, and which wines go well with which foods
purpose Suggest good wine and food combinations for a restaurant menu and answer diners' questions
users diners, waiters
maintainers sommelier
out of scope winery inventory, restaurant staff
kind application
$ okb cq add "Which wine characteristics should I consider when choosing a wine?"
Added cq.1.
$ okb cq add "Is Bordeaux a red or white wine?"
Added cq.2.
$ okb cq add "Does Cabernet Sauvignon go well with seafood?"
Added cq.3.
$ okb cq add "What is the best choice of wine for grilled meat?"
Added cq.4.
$ okb cq add "Which characteristics of a wine affect its appropriateness for a dish?"
Added cq.5.
$ okb cq add "Which wines does a given winery produce?"
Added cq.6.
$ okb status
Wine and Food · 0 classes · 0 slots · 0 instances · 6 questions
✓ 1. Determine the domain and scope ◀ you are here
✓ Domain and purpose are written down
✓ Users (and ideally maintainers) are named
✓ At least three competency questions
✓ At least one thing is explicitly out of scope
○ 2. Consider reusing existing ontologies
○ 3. Enumerate important terms
○ 4. Define the classes and the class hierarchy
○ 5. Define the properties of classes (slots)
○ 6. Define the facets of the slots
○ 7. Create instances
○ 8. Review against your questions, and iterate
Validator (steps 1–1): ✗ 0 ! 0 i 0 okb validate for details
Step 1 looks done. When you're happy with it: okb step next
$ okb step next
Now on step 2. (To read a step's guide without moving: okb explain 2)
Step 2 of 8: Consider reusing existing ontologies
Goal: Check whether someone has already modeled part of your domain, and decide whether to
borrow, adapt, just reference it, or skip it.
Why it matters: Reuse saves time and makes your ontology compatible with others. If you have
to talk to systems that already use a vocabulary, reuse may not be optional.
Questions to answer
• Is there an industry standard, taxonomy or controlled vocabulary for this domain?
• Does any system you must integrate with already use a particular vocabulary?
• Is there an internal list, spreadsheet, glossary or schema that already names these things?
You're done when
○ Reuse has been considered and recorded
Tips
• Even a glossary page or an existing database schema counts as a source of terms.
• Don't let this step stall you. 30 minutes of looking is usually enough for a first version.
• Where to look: Linked Open Vocabularies (https://lov.linkeddata.es) searches hundreds of
reusable vocabularies by term. schema.org (https://schema.org) covers everyday things: people,
organizations, products, places, events and creative works.
• W3C vocabularies cover common needs: SKOS for taxonomies and thesauri, Dublin Core for
document metadata, PROV-O for provenance, ORG for organizations and OWL-Time for dates and
times.
• For design systems: WAI-ARIA roles (https://www.w3.org/TR/wai-aria/) are a standard taxonomy
of UI components (button, checkbox, switch, tab...). The W3C Design Tokens format
(https://www.designtokens.org) is the standard for tokens. DSDS, the Design System
Documentation Spec (https://designsystemdocspec.org), is a draft schema for documenting
components, tokens and themes.
• You rarely need to import a whole vocabulary. Borrowing its terms and definitions is usually
enough: okb reuse add --name ... --url ... --decision reference.
In the paper's wine example
The paper notes a French-wine knowledge base or a wine retailer's list of wine properties
could be imported, but chooses to build from scratch for teaching purposes.
Commands
okb reuse add okb reuse none
Step 2: Consider reuse#
The paper mentions existing wine vocabularies but deliberately builds from scratch to teach the method. We record that honestly. For your own ontology, the step guide (okb step 2, or docs/METHOD.md) lists where to look: Linked Open Vocabularies, schema.org, W3C vocabularies such as SKOS and Dublin Core, and for design systems WAI-ARIA roles, the Design Tokens format and DSDS.
$ okb reuse none --why "Following Ontology 101, which builds the wine ontology from scratch for teaching; a French-wine knowledge base or retailer vocabulary would be candidates in a real project."
$ okb step next
Step 3: Brainstorm terms#
$ okb term add wine grape winery location color body flavor sugar "tannin level" "red wine" "white wine" "rosé wine" "dessert wine" port bordeaux beaujolais food seafood "red meat" "goes well with" "vintage year" "label paper"
22 term(s) on the list.
$ okb term list
undecided wine · grape · winery · location · color · body · flavor · sugar · tannin level · red wine · white wine · rosé wine · dessert wine · port · bordeaux · beaujolais · food · seafood · red meat · goes well with · vintage year · label paper
$ okb step next
Now on step 4. (To read a step's guide without moving: okb explain 4)
Step 4 of 8: Define the classes and the class hierarchy
Goal: Pick the terms that name things with independent existence, make them classes, and
arrange them by 'is a kind of'.
Why it matters: The hierarchy is the backbone: slots are inherited down it and instances hang
off it. Most modeling mistakes are hierarchy mistakes.
Questions to answer
• Which terms name things that exist on their own (not descriptions of other things)?
• Where does your head naturally start: general, specific, or somewhere in the middle?
• For each pair: is every X necessarily (by definition) a Y?
• Do any siblings overlap? Can something be both? If not, they're disjoint.
You're done when
○ A naming convention is set
○ At least two classes, organized with at least one is-a link
○ No errors in hierarchy checks
? You've stood back and looked at the tree (okb tree) against the checklist in decision.is-a
Tips
• Steps 4 and 5 are intertwined. It's normal to add a few classes, then a few slots, then go
back.
• Say each is-a link out loud: 'Every Pinot Noir is a Red Wine.' If it sounds wrong, it is.
• Use singular names consistently (Wine, not Wines).
• Mark 'grouping only' classes as abstract.
In the paper's wine example
Wine → Red Wine / White Wine / Rosé Wine; Red Wine → Bordeaux, Burgundy, ...; Bordeaux → Médoc
→ Pauillac, Margaux. Port has two parents: Red Wine and Dessert Wine.
Decision guides for this step (okb explain <id>)
decision.approach Top-down, bottom-up, or combination?
decision.is-a Is this really a subclass?
decision.new-class Should I introduce a new subclass here?
decision.class-or-value New class, or just a slot value?
decision.instance-or-class Instance or class?
decision.disjoint Are these classes disjoint?
decision.naming Choosing a naming convention
Commands
okb convention okb class add okb class disjoint okb tree okb term set
Step 4: Classes and the hierarchy#
First a naming convention (the defaults), then classes. We work in the paper’s ‘combination’ style: Wine at the top, the familiar color groups in the middle, and specific wines below.
$ okb convention
Naming convention: classes PascalCase (singular) · slots camelCase · instances free text
$ okb class add Wine --desc "A specific wine produced by a specific winery (not an individual bottle)."
Added class Wine at the top level.
$ okb class add Wines --parent Wine --force
✗ 'Wines' can't be a subclass of 'Wine': they're the singular and plural of the same concept, so neither is a kind of the other (Ontology 101 §4.1: "a single Wine is not a kind of Wines"). Use one class.
Even with —force, okb refuses ‘Wines’ as a subclass of ‘Wine’. That’s Ontology 101’s classic singular/plural mistake (§4.1).
Step 4 (continued)#
$ okb class add RedWine --parent Wine --desc "Wine made from dark-skinned grapes with skin contact; described by tannin level."
Added class RedWine (a kind of Wine).
$ okb class add WhiteWine --parent Wine --desc "Wine fermented without grape skins."
Added class WhiteWine (a kind of Wine).
Can anything be both a WhiteWine and a RedWine? If not, say so: okb class disjoint "WhiteWine" "RedWine"
$ okb class add RoseWine --parent Wine --desc "Wine with brief skin contact giving a pink color." --synonym Rosé
Added class RoseWine (a kind of Wine).
$ okb class add DessertWine --parent Wine --desc "Sweet wine served with or as dessert."
Added class DessertWine (a kind of Wine).
$ okb class disjoint RedWine WhiteWine RoseWine
Declared disjoint: RedWine, WhiteWine, RoseWine. Nothing can be more than one of these now.
$ okb class add Bordeaux --parent RedWine --terminological --desc "Red wine from the Bordeaux region of France."
Added class Bordeaux (a kind of RedWine).
$ okb class add Medoc --parent Bordeaux --terminological --desc "Bordeaux from the Médoc sub-region."
Added class Medoc (a kind of Bordeaux).
$ okb class add Pauillac --parent Medoc --terminological --desc "Médoc wine from the Pauillac appellation."
Added class Pauillac (a kind of Medoc).
$ okb class add Margaux --parent Medoc --terminological --desc "Médoc wine from the Margaux appellation."
Added class Margaux (a kind of Medoc).
Can anything be both a Margaux and a Pauillac? If not, say so: okb class disjoint "Margaux" "Pauillac"
$ okb class add Beaujolais --parent RedWine --terminological --desc "Light red wine from the Beaujolais region, made from Gamay."
Added class Beaujolais (a kind of RedWine).
Can anything be both a Beaujolais and a Bordeaux? If not, say so: okb class disjoint "Beaujolais" "Bordeaux"
$ okb class add Merlot --parent RedWine --desc "Red wine made from the Merlot grape."
Added class Merlot (a kind of RedWine).
$ okb class add Port --parent RedWine --parent DessertWine --desc "Fortified sweet red wine from Portugal. (Only red Ports are modeled, as in the paper.)"
Added class Port (a kind of RedWine and DessertWine).
Multiple parents are fine when it's truly a kind of each. Consider recording why with `okb decision add`.
$ okb class add Chardonnay --parent WhiteWine --desc "White wine made from the Chardonnay grape."
Added class Chardonnay (a kind of WhiteWine).
$ okb class add Riesling --parent WhiteWine --desc "White wine made from the Riesling grape."
Added class Riesling (a kind of WhiteWine).
Can anything be both a Riesling and a Chardonnay? If not, say so: okb class disjoint "Riesling" "Chardonnay"
$ okb class disjoint Chardonnay Riesling
Declared disjoint: Chardonnay, Riesling. Nothing can be more than one of these now.
$ okb class add Sauternes --parent WhiteWine --parent DessertWine --desc "Sweet white wine from the Sauternes area of Bordeaux."
Added class Sauternes (a kind of WhiteWine and DessertWine).
Note: 'Sauternes' looks plural, but class names here are singular. If it's a proper name that just ends in 's' (like Sauternes), that's fine: record it with okb decision add ... --waives naming-singular-plural-consistent.
Multiple parents are fine when it's truly a kind of each. Consider recording why with `okb decision add`.
$ okb decision add --title "Sauternes keeps its final s" --decision "The class is named Sauternes, not Sauterne." --why "It's the proper name of the appellation, not a plural." --about Sauternes --waives naming-singular-plural-consistent
Recorded design decision d.2: Sauternes keeps its final s.
It explains 1 current finding(s) from naming-singular-plural-consistent (they'll show as 'explained' in okb validate).
$ okb class add Winery --desc "A business that makes wine."
Added class Winery at the top level.
$ okb class add WineGrape --desc "A grape variety used to make wine." --synonym Varietal
Added class WineGrape at the top level.
$ okb class add WineRegion --desc "A geographic area wines are named after or come from."
Added class WineRegion at the top level.
$ okb class add Food --abstract --desc "A kind of dish or ingredient a wine can be paired with."
Added class Food at the top level.
$ okb class add Seafood --parent Food --desc "Fish and shellfish dishes."
Added class Seafood (a kind of Food).
$ okb class add RedMeat --parent Food --desc "Beef, lamb and similar dishes, including grilled meat."
Added class RedMeat (a kind of Food).
Can anything be both a RedMeat and a Seafood? If not, say so: okb class disjoint "RedMeat" "Seafood"
$ okb class disjoint Seafood RedMeat
Declared disjoint: Seafood, RedMeat. Nothing can be more than one of these now.
$ okb term set "vintage year" --as out-of-scope --note "Vintage questions deferred to v2"
'vintage year' → out-of-scope.
$ okb term set "label paper" --as out-of-scope
'label paper' → out-of-scope.
$ okb term set port --as class --node Port
'port' → class.
Linked to Class 'Port'.
$ okb term set "rosé wine" --as class --node RoseWine
'rosé wine' → class.
Linked to Class 'RoseWine'.
$ okb decision add --title "Regional wines are terminological classes" --decision "Bordeaux, Medoc, Pauillac, Margaux and Beaujolais are classes even though they add no slots of their own." --why "Sommeliers and diners always distinguish these appellations (Ontology 101 §4.4: distinctions experts commonly make)." --about Bordeaux --about Medoc --about Beaujolais --waives hier-single-child
Recorded design decision d.3: Regional wines are terminological classes.
It explains 1 current finding(s) from hier-single-child (they'll show as 'explained' in okb validate).
$ okb tree
Food (abstract)
└ RedMeat
└ Seafood
Wine
└ DessertWine
└ Port (also under RedWine)
└ Sauternes (also under WhiteWine)
└ RedWine
└ Beaujolais
└ Bordeaux
└ Medoc
└ Margaux
└ Pauillac
└ Merlot
└ Port (see above)
└ RoseWine
└ WhiteWine
└ Chardonnay
└ Riesling
└ Sauternes (see above)
WineGrape
WineRegion
Winery
$ okb validate
✗ 0 error(s) ! 0 warning(s) i 2 hint(s) · checks for steps 1–4 (use --all for the rest)
HINTS: worth a look
i The subclasses of 'RedWine' ('Bordeaux', 'Beaujolais', 'Merlot', 'Port') have no disjointness declared. Can anything be more than one of them? [disjoint-consider-siblings]
Fix: `okb class disjoint A B C`, or ignore it if the siblings can overlap (Dessert Wine
and White Wine can).
i The subclasses of 'Medoc' ('Pauillac', 'Margaux') have no disjointness declared. Can anything be more than one of them? [disjoint-consider-siblings]
Fix: `okb class disjoint A B C`, or ignore it if the siblings can overlap (Dessert Wine
and White Wine can).
EXPLAINED by design decisions (2)
· Class 'Sauternes' looks plural, but the convention is singular. Try 'Sauterne'. [naming-singular-plural-consistent] → d.2
· 'Bordeaux' has only one direct subclass ('Medoc'). Is a sibling missing, or is the subclass really the same as its parent? [hier-single-child] → d.3
Learn about any rule: okb explain <rule-id> · add --why for reasons and sources
(9 warning(s)/hint(s) from later steps are hidden until you get there; okb validate --all shows them. Errors are never hidden.)
$ okb step next
Now on step 5. (To read a step's guide without moving: okb explain 5)
Step 5 of 8: Define the properties of classes (slots)
Goal: Turn the remaining terms into slots and attach each one to the most general class whose
members all have it.
Why it matters: Classes alone can't answer your questions. Slots hold the facts and
relationships the answers are made of.
Questions to answer
• Which remaining terms describe a class rather than being one?
• For each: is it intrinsic (flavor), extrinsic (name, region), a part, or a relationship to
another thing (maker)?
• What is the most general class whose members all have this property?
• Which competency question needs this slot?
You're done when
○ At least one slot
○ Every slot is attached to at least one class
Tips
• Two kinds of slot: properties hold a value (name, year, one of a list); relationships point
at another thing (maker → Winery).
• Name relationships as verbs or roles read from the domain class: a Wine has a maker; a
Winery produces wines.
• If you're attaching the same slot to every child, attach it to the parent instead.
In the paper's wine example
Wine gets color, body, flavor, sugar, name, maker, grape. Winery gets location and produces.
Red Wine gets tanninLevel, because white wines aren't described by tannin.
Decision guides for this step (okb explain <id>)
decision.slot-placement Which class does this slot go on?
decision.class-or-value New class, or just a slot value?
Commands
okb property add okb relationship add okb show okb term set
Step 5: Slots#
The paper calls every attribute a slot. There are two kinds: properties hold a value, and relationships link to another thing and are stored as graph edges (maker → :MAKER). Slots go on the most general class whose members all have them, so tanninLevel goes on RedWine, not Wine (§3, Step 6).
$ okb property add color --on Wine --type Enumerated --values red,white,rose --card single --desc "The wine's color."
Added property color on Wine (Enumerated).
$ okb property add body --on Wine --type Enumerated --values light,medium,full --card single --desc "How heavy the wine feels in the mouth."
Added property body on Wine (Enumerated).
$ okb property add flavor --on Wine --type Enumerated --values delicate,moderate,strong --card single --desc "Intensity of the wine's flavor."
Added property flavor on Wine (Enumerated).
$ okb property add sugar --on Wine --type Enumerated --values dry,offDry,sweet --card single --desc "Residual sweetness."
Added property sugar on Wine (Enumerated).
$ okb property add tanninLevel --on RedWine --type Enumerated --values low,moderate,high --card single --desc "Astringency from grape skins; only meaningful for red wines."
Added property tanninLevel on RedWine (Enumerated).
$ okb relationship add maker --from Wine --to Winery --card single --min 1 --desc "The winery that produced the wine."
Added relationship maker: (Wine)-[:MAKER]->(Winery).
$ okb relationship add produces --from Winery --to Wine --card multiple --desc "Wines the winery makes."
Added relationship produces: (Winery)-[:PRODUCES]->(Wine).
$ okb relationship add grape --from Wine --to WineGrape --card multiple --min 1 --desc "Grape varieties the wine is made from."
Added relationship grape: (Wine)-[:GRAPE]->(WineGrape).
$ okb relationship add region --from Wine --to WineRegion --card single --desc "Where the wine comes from."
Added relationship region: (Wine)-[:REGION]->(WineRegion).
$ okb property add location --on Winery --type String --card single --desc "Where the winery is."
Added property location on Winery (String).
$ okb relationship add goesWellWith --from Wine --to Food --card multiple --desc "Foods this wine pairs well with."
Added relationship goesWellWith: (Wine)-[:GOES_WELL_WITH]->(Food).
$ okb show RedWine
RedWine Class · c.red-wine
Wine made from dark-skinned grapes with skin contact; described by tannin level.
parents Wine
subclasses Bordeaux, Beaujolais, Merlot, Port
disjoint with WhiteWine, RoseWine
Slots (properties hold values; relationships → link to other things)
tanninLevel Enumerated, {low, moderate, high}, single
color Enumerated, {red, white, rose}, single (from Wine)
body Enumerated, {light, medium, full}, single (from Wine)
flavor Enumerated, {delicate, moderate, strong}, single (from Wine)
sugar Enumerated, {dry, offDry, sweet}, single (from Wine)
maker Instance, → Winery (:MAKER), single, min 1 (from Wine)
grape Instance, → WineGrape (:GRAPE), multiple, min 1 (from Wine)
region Instance, → WineRegion (:REGION), single (from Wine)
goesWellWith Instance, → Food (:GOES_WELL_WITH), multiple (from Wine)
$ okb step next
Now on step 6. (To read a step's guide without moving: okb explain 6)
Step 6 of 8: Define the facets of the slots
Goal: For every slot, decide its value type, allowed values or range, cardinality, and any
defaults, fixed values or inverse.
Why it matters: Facets turn a list of fields into rules a machine can check. This is where
most data-quality errors get caught later.
Questions to answer
• Is the value text, a number, yes/no, one of a fixed list, or another thing (Instance)?
• If it's a fixed list, what are all the allowed values?
• If it's another thing, what is the most general class of things it can be (the range)? Not
too general, not too narrow.
• One value or many? Is it required (minimum 1)?
• Is there a value most instances share (default), or one every instance of a class must have
(fixed value)?
• Is this relationship the reverse of another slot (maker ↔ produces)?
• Does each link need extra information of its own, like a condition or a strength? (Edge
properties; see decision.edge-or-class.)
You're done when
○ Every slot has a value type and cardinality
○ No errors in slot checks
Tips
• When in doubt about range, pick the most general class that still only contains valid
fillers.
• Defaults are suggestions; fixed values are facts. Don't confuse them.
In the paper's wine example
body: Enumerated {light, medium, full}, single. produces (on Winery): Instance, range Wine,
multiple, inverse of maker. grape: min 1. Dessert Wine fixes sugar = sweet.
Decision guides for this step (okb explain <id>)
decision.range What should this slot's range be?
decision.edge-or-class Edge property, or make the relationship its own class?
Commands
okb slot set okb relationship inverse okb relationship property okb class fix okb class default okb class restrict
Step 6: Facets, fixed values, inverses#
Fixed values are facts about a whole class. Every red wine’s color is red, and every dessert wine is sweet (§5.2). A pairing stated on a class applies to all its members.
$ okb relationship inverse maker produces
maker and produces are now inverses: one relationship read from both ends.
Stored as (Wine)-[:MAKER]->(Winery); produces follows MAKER backwards, so nothing is stored twice.
$ okb class fix RedWine color=red
RedWine.color fixed to "red"
Fixed values apply to every subclass and instance and can't be changed below. For an overridable starting value use `okb class default`.
$ okb class fix WhiteWine color=white
WhiteWine.color fixed to "white"
$ okb class fix RoseWine color=rose
RoseWine.color fixed to "rose"
$ okb class fix DessertWine sugar=sweet
DessertWine.sugar fixed to "sweet"
$ okb class fix RedWine goesWellWith=RedMeat
RedWine.goesWellWith fixed to RedMeat
$ okb class fix WhiteWine goesWellWith=Seafood
WhiteWine.goesWellWith fixed to Seafood
A pairing’s strength belongs to the pairing itself, not to the wine or the food, so it’s an edge property (see okb explain decision.edge-or-class).
$ okb relationship property goesWellWith strength --type Enumerated --values classic,good
goesWellWith edges can now carry strength (Enumerated): (…)-[:GOES_WELL_WITH {strength: …}]->(…)
$ okb link RedWine goesWellWith RedMeat strength=classic
Updated (RedWine)-[:GOES_WELL_WITH {strength: "classic"}]->(RedMeat)
$ okb class default Wine body=medium
New Wine instances will start with body = "medium" (can be changed per instance).
$ okb validate
✗ 0 error(s) ! 1 warning(s) i 2 hint(s) · checks for steps 1–6 (use --all for the rest)
WARNINGS: fix, or record a design decision explaining why not
! 'Merlot' doesn't add anything to 'RedWine': no own slots, values, restrictions or relationships. [hier-subclass-adds-something]
Fix: Add the slot, value, restriction or relationship that makes it different; or mark it
`terminological`; or merge it into its parent.
HINTS: worth a look
i The subclasses of 'RedWine' ('Bordeaux', 'Beaujolais', 'Merlot', 'Port') have no disjointness declared. Can anything be more than one of them? [disjoint-consider-siblings]
Fix: `okb class disjoint A B C`, or ignore it if the siblings can overlap (Dessert Wine
and White Wine can).
i The subclasses of 'Medoc' ('Pauillac', 'Margaux') have no disjointness declared. Can anything be more than one of them? [disjoint-consider-siblings]
Fix: `okb class disjoint A B C`, or ignore it if the siblings can overlap (Dessert Wine
and White Wine can).
EXPLAINED by design decisions (2)
· Class 'Sauternes' looks plural, but the convention is singular. Try 'Sauterne'. [naming-singular-plural-consistent] → d.2
· 'Bordeaux' has only one direct subclass ('Medoc'). Is a sibling missing, or is the subclass really the same as its parent? [hier-single-child] → d.3
Learn about any rule: okb explain <rule-id> · add --why for reasons and sources
(6 warning(s)/hint(s) from later steps are hidden until you get there; okb validate --all shows them. Errors are never hidden.)
$ okb step next
Now on step 7. (To read a step's guide without moving: okb explain 7)
Step 7 of 8: Create instances
Goal: Add real individuals: choose a class, create the instance, and fill in its slot values.
Why it matters: Instances are the real test. Filling them in shows up missing slots, wrong
facets and classes that don't fit.
Questions to answer
• What are the most specific things that appear in answers to your competency questions? Those
are your instances.
• Which class does each belong to? (The most specific one that fits.)
• Can you fill in every required slot? If not, is the data missing or is the facet wrong?
You're done when
○ At least a few instances (enough to answer one competency question end to end)
○ No errors in instance checks
Tips
• Start with instances that answer one competency question completely. It's the fastest way to
find gaps.
• An instance that won't fit anywhere usually means a class is missing or a facet is too
strict.
In the paper's wine example
Château Morgon Beaujolais: instance of Beaujolais; body light, color red, flavor delicate,
tannin low, grape Gamay, maker Château Morgon, region Beaujolais, sugar dry.
Decision guides for this step (okb explain <id>)
decision.instance-or-class Instance or class?
Commands
okb instance add okb instance set
Step 7: Instances#
The paper’s instance (Figure 5), plus what it needs: its winery, grape and region. Grape-variety classes get their grape as a fixed value.
$ okb instance add "Chateau Morgon" --of Winery location="Beaujolais, France"
Added Chateau Morgon (a Winery).
Chateau Morgon.location = "Beaujolais, France"
$ okb instance add "Sterling Vineyards" --of Winery location="Napa Valley, California"
Added Sterling Vineyards (a Winery).
Sterling Vineyards.location = "Napa Valley, California"
$ okb instance add Gamay --of WineGrape
Added Gamay (a WineGrape).
$ okb instance add "Merlot grape" --of WineGrape
Added Merlot grape (a WineGrape).
$ okb instance add "Chardonnay grape" --of WineGrape
Added Chardonnay grape (a WineGrape).
$ okb instance add "Riesling grape" --of WineGrape
Added Riesling grape (a WineGrape).
$ okb instance add "Beaujolais region" --of WineRegion
Added Beaujolais region (a WineRegion).
$ okb class fix Merlot grape="Merlot grape"
Merlot.grape fixed to Merlot grape
$ okb class fix Chardonnay grape="Chardonnay grape"
Chardonnay.grape fixed to Chardonnay grape
$ okb class fix Riesling grape="Riesling grape"
Riesling.grape fixed to Riesling grape
$ okb instance add "Chateau Morgon Beaujolais" --of Beaujolais body=light flavor=delicate tanninLevel=low grape=Gamay maker="Chateau Morgon" region="Beaujolais region" sugar=dry
Added Chateau Morgon Beaujolais (a Beaujolais).
Chateau Morgon Beaujolais.body = "light"
Chateau Morgon Beaujolais.flavor = "delicate"
Chateau Morgon Beaujolais.tanninLevel = "low"
Chateau Morgon Beaujolais.grape = Gamay
Chateau Morgon Beaujolais.maker = Chateau Morgon
Chateau Morgon Beaujolais.region = Beaujolais region
Chateau Morgon Beaujolais.sugar = "dry"
$ okb instance add "Sterling Vineyards Merlot" --of Merlot maker="Sterling Vineyards" flavor=moderate tanninLevel=moderate sugar=dry
Added Sterling Vineyards Merlot (a Merlot).
Sterling Vineyards Merlot.maker = Sterling Vineyards
Sterling Vineyards Merlot.flavor = "moderate"
Sterling Vineyards Merlot.tanninLevel = "moderate"
Sterling Vineyards Merlot.sugar = "dry"
Filled in default body = "medium".
$ okb show "Chateau Morgon Beaujolais"
Chateau Morgon Beaujolais Instance · i.chateau-morgon-beaujolais
instance of Beaujolais
Values
tanninLevel low
color red (fixed by RedWine)
body light
flavor delicate
sugar dry
maker Chateau Morgon
grape Gamay
region Beaujolais region
goesWellWith RedMeat (fixed by RedWine)
$ okb show "Chateau Morgon"
Chateau Morgon Instance · i.chateau-morgon
instance of Winery
Values
produces Chateau Morgon Beaujolais
location Beaujolais, France
Chateau Morgon produces Chateau Morgon Beaujolais without a second edge: produces is the inverse of maker, so it reads the single :MAKER edge backwards.
$ okb step next
Now on step 8. (To read a step's guide without moving: okb explain 8)
Step 8 of 8: Review against your questions, and iterate
Goal: Stand back: check each competency question can be answered, run the full validator,
review the judgment-only rules, record decisions, and go around again.
Why it matters: The only real test of an ontology is whether it does the job it was built for.
Expect to loop back to earlier steps.
Questions to answer
• For each competency question: which classes, slots and instances answer it? Is anything
missing?
• For each answered question: would the ontology also answer the rest of its family, the same
question about similar things and the questions next to it? Which of those are out of scope?
• Is there anything in the ontology no question needs?
• Would a domain expert agree with the hierarchy? Show it to one.
• Which choices would surprise someone reusing this ontology? Are they recorded as design
decisions?
You're done when
○ Every competency question is linked to what answers it
? Each question's family has been considered: wanted questions added, the rest recorded as out of scope
○ No errors from okb validate
○ Every remaining warning is fixed or explained in a design decision
? Someone who knows the domain has looked at it
Tips
• Iteration is part of the method, not a sign you went wrong.
• Use the ontology-review skill for the judgment rules a script can't check.
In the paper's wine example
The paper's own evolution example: Zinfandel starts under Red Wine, then 'white zinfandel'
appears and the class has to be split into White Zinfandel and Red Zinfandel.
Commands
okb cq link okb validate --all okb decision add okb diagram
Step 8: Review against the questions#
Link each competency question to what answers it, then run every check.
$ okb cq link 1 color body flavor sugar tanninLevel
Linked cq.1 → color (Slot).
Linked cq.1 → body (Slot).
Linked cq.1 → flavor (Slot).
Linked cq.1 → sugar (Slot).
Linked cq.1 → tanninLevel (Slot).
Tip: cq.1 is one example of a family of questions. Would you also ask more about Wine (maker, grape, region, goesWellWith)? Add the ones you want (okb cq add "..."), note the rest as out of scope (okb scope --out-of-scope "..."), or keep it narrow.
$ okb cq link 2 Bordeaux RedWine WhiteWine
Linked cq.2 → Bordeaux (Class).
Linked cq.2 → RedWine (Class).
Linked cq.2 → WhiteWine (Class).
Tip: cq.2 is one example of a family of questions. Would you also ask the same question about Beaujolais, Merlot, Port, Medoc, or more about Bordeaux (maker, grape, region, goesWellWith); the same question about RoseWine, DessertWine? Add the ones you want (okb cq add "..."), note the rest as out of scope (okb scope --out-of-scope "..."), or keep it narrow.
$ okb cq link 3 goesWellWith grape Seafood
Linked cq.3 → goesWellWith (Slot).
Linked cq.3 → grape (Slot).
Linked cq.3 → Seafood (Class).
Tip: cq.3 is one example of a family of questions. Would you also ask more about Wine (maker, region); the same question about RedMeat? Add the ones you want (okb cq add "..."), note the rest as out of scope (okb scope --out-of-scope "..."), or keep it narrow.
$ okb cq link 4 RedMeat goesWellWith
Linked cq.4 → RedMeat (Class).
Linked cq.4 → goesWellWith (Slot).
Tip: cq.4 is one example of a family of questions. Would you also ask more about Wine (maker, region)? Add the ones you want (okb cq add "..."), note the rest as out of scope (okb scope --out-of-scope "..."), or keep it narrow.
$ okb cq link 5 goesWellWith body flavor
Linked cq.5 → goesWellWith (Slot).
Linked cq.5 → body (Slot).
Linked cq.5 → flavor (Slot).
Tip: cq.5 is one example of a family of questions. Would you also ask more about Wine (maker, region)? Add the ones you want (okb cq add "..."), note the rest as out of scope (okb scope --out-of-scope "..."), or keep it narrow.
$ okb cq link 6 produces Winery
Linked cq.6 → produces (Slot).
Linked cq.6 → Winery (Class).
Tip: cq.6 is one example of a family of questions. Would you also ask more about Winery (location)? Add the ones you want (okb cq add "..."), note the rest as out of scope (okb scope --out-of-scope "..."), or keep it narrow.
$ okb cq list
cq.1 Which wine characteristics should I consider when choosing a wine? [draft]
needs: color, body, flavor, sugar, tanninLevel
cq.2 Is Bordeaux a red or white wine? [draft]
needs: Bordeaux, RedWine, WhiteWine
cq.3 Does Cabernet Sauvignon go well with seafood? [draft]
needs: goesWellWith, grape, Seafood
cq.4 What is the best choice of wine for grilled meat? [draft]
needs: RedMeat, goesWellWith
cq.5 Which characteristics of a wine affect its appropriateness for a dish? [draft]
needs: goesWellWith, body, flavor
cq.6 Which wines does a given winery produce? [draft]
needs: produces, Winery
$ okb validate --all
✗ 0 error(s) ! 0 warning(s) i 4 hint(s) · all checks
HINTS: worth a look
i The subclasses of 'RedWine' ('Bordeaux', 'Beaujolais', 'Merlot', 'Port') have no disjointness declared. Can anything be more than one of them? [disjoint-consider-siblings]
Fix: `okb class disjoint A B C`, or ignore it if the siblings can overlap (Dessert Wine
and White Wine can).
i The subclasses of 'Medoc' ('Pauillac', 'Margaux') have no disjointness declared. Can anything be more than one of them? [disjoint-consider-siblings]
Fix: `okb class disjoint A B C`, or ignore it if the siblings can overlap (Dessert Wine
and White Wine can).
i No competency question needs these classes (or their parent/child): 'WineRegion'. [scope-no-unneeded]
Fix: Link it to (or add) the question that needs it, or remove it.
i No competency question needs these slots: 'region', 'location'. [scope-no-unneeded]
Fix: Link it to (or add) the question that needs it, or remove it.
EXPLAINED by design decisions (2)
· Class 'Sauternes' looks plural, but the convention is singular. Try 'Sauterne'. [naming-singular-plural-consistent] → d.2
· 'Bordeaux' has only one direct subclass ('Medoc'). Is a sibling missing, or is the subclass really the same as its parent? [hier-single-child] → d.3
Learn about any rule: okb explain <rule-id> · add --why for reasons and sources
Four hints are left in on purpose so you can see what they look like. WineRegion, region and location aren’t needed by any question yet (§4.7): either add a question like “Where does this wine come from?” or drop them. Two sibling groups have no disjointness declared. That’s worth a real conversation: a Bordeaux blend usually contains Merlot grapes, so are the classes Merlot and Bordeaux disjoint? It depends on whether Merlot means ‘varietal Merlot wine’. Record the answer as a design decision.
$ okb status
Wine and Food · 21 classes · 11 slots · 9 instances · 6 questions
✓ 1. Determine the domain and scope
✓ 2. Consider reusing existing ontologies
✓ 3. Enumerate important terms
✓ 4. Define the classes and the class hierarchy
✓ 5. Define the properties of classes (slots)
✓ 6. Define the facets of the slots
✓ 7. Create instances
✓ 8. Review against your questions, and iterate ◀ you are here
✓ Every competency question is linked to what answers it
? Each question's family has been considered: wanted questions added, the rest recorded as out of scope
✓ No errors from okb validate
✓ Every remaining warning is fixed or explained in a design decision
? Someone who knows the domain has looked at it
Validator (steps 1–8): ✗ 0 ! 0 i 4 okb validate for details
See the guide for this step: okb step
$ okb diagram --out diagram.md
Wrote diagram.md. Open it in GitHub, VS Code (Markdown preview), or mermaid.live.
Export for a graph database#
In the okb files, classes are nodes so the schema can be checked. A graph database usually wants the data the other way round: each instance becomes a node labeled with its class and all its ancestors, with properties (including fixed values inherited from classes) and typed relationships.
$ okb export --format cypher --out wine.cypher
Wrote wine.cypher: 9 nodes, 5 relationships (cypher).
2 class-level relationship value(s) point at classes (e.g. RedWine GOES_WELL_WITH RedMeat), not instances, so they're only exported with --with-schema.
Inverse relationships are stored once: produces = MAKER followed backwards.
$ okb export --with-schema --out wine-export.json
Wrote wine-export.json: 30 nodes, 37 relationships (json).
Inverse relationships are stored once: produces = MAKER followed backwards.