Skip to content

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.

View this page's source on GitHub