Ontology Kit
Overview#
A toolkit that walks a beginner through building their first ontology, following the method in Ontology Development 101 (Noy & McGuinness, 2001). It has three parts:
| Part | What it is |
|---|---|
meta-KB (meta-kb/) |
A knowledge base about building knowledge bases: the 8-step method, 40 glossary concepts, 7 principles, 10 decision guides and 57 rules. Every rule cites a verbatim, page-checked quote from the paper (or Gruber 1993), or says plainly that it’s a toolkit convention. |
okb (src/) |
A command-line tool that creates the ontology one step at a time, refuses common mistakes as you make them, checks everything against the meta-KB rules, and explains every finding in plain language. |
Skills (skills/) |
Instructions for Claude: ontology-coach (hand-holding from a blank page), ontology-review (a second opinion on the judgment rules a script can’t check) and build-domain-kb-from-docs (extracting an ontology from existing documentation with a quote-first verification gate). |
Installation#
Needs Node.js 24+ (okb runs its TypeScript source directly; there’s no build step).
cd ontology-kit
npm install # one runtime dependency (yaml, for markdown frontmatter); the rest are dev tools
npm link # puts `okb` on your PATH (or use: node src/cli.ts ...)
npm test # the test suite, including building the wine example end to end
pdftotext (brew install poppler) is optional: okb uses it to check quotes against PDFs, and falls back to the optional pdfjs-dist package without it.
Updating#
Check which version you have:
okb version # okb 1.0.0 · meta-KB 2.4.0
The meta-KB version tracks changes to the method and rules; meta-kb/README.md lists what changed in each one. Each ontology’s okb.json records the version it started with (metaKbVersion).
To update:
cd ontology-kit
git pull
npm install # dependencies can change between versions
okb version
You don’t need to run npm link again. It points at this folder, so okb runs the new code right away. Link again only if you switch Node versions or move the folder.
Skills you linked into ~/.claude/skills/ update with the repo. If you copied or uploaded them instead, replace the old copies with the new ones from skills/. Either way, start a new Claude session so it loads the new version.
Existing ontologies keep working: okb converts older file formats when it loads them, and new rules only add findings.
Getting started#
-
Read the 2-minute version: an ontology is a precise, shared vocabulary for one subject. It says what kinds of things exist (classes), how they’re organized (“a Red Wine is a kind of Wine”), what you can say about them (slots like
bodyormaker), and the rules for filling those in (facets). Add real examples (instances) and you have a knowledge base. -
Skim the worked example: examples/wine/TRANSCRIPT.md builds the paper’s wine ontology command by command, with real output.
-
Start your own.
Either ask Claude to
coach me through building an ontology(uses the ontology-coach skill). To add the skill, link it from this folder:mkdir -p ~/.claude/skills ln -s "$PWD/skills/ontology-coach" ~/.claude/skills/ontology-coachClaude Code and Cursor both load skills from
~/.claude/skills/, and the link keeps the skill current when you update this repo. Start it by asking, or with/ontology-coach. The other skills inskills/install the same way.Or run it yourself:
okb init my-ontology --name "My Ontology" cd my-ontology okb status # where you are and what's next, at any time okb step # the guide for the current step okb explain range # plain-language explanation of any term, rule or step okb validate # check your work (only rules relevant to your current step)
The method#
| Step | You’ll produce | Key commands |
|---|---|---|
| 1. Scope | domain, purpose, users, out-of-scope, 3+ competency questions | okb scope, okb cq add |
| 2. Reuse | what existing vocabularies you considered | okb reuse add, okb reuse none |
| 3. Terms | an unsorted brainstorm list | okb term add |
| 4. Classes | naming convention, class hierarchy, disjointness | okb convention, okb class add, okb class disjoint, okb tree |
| 5. Slots | properties (values) and relationships (links), attached at the right level | okb property add, okb relationship add, okb show |
| 6. Facets | value types, allowed values, ranges, cardinality, fixed values, inverses, edge properties | okb slot set, okb class fix, okb relationship inverse, okb relationship property, okb link |
| 7. Instances | real examples, which test the steps before | okb instance add |
| 8. Review | questions linked to what answers them, decisions recorded | okb cq link, okb validate --all, okb decision add |
When it’s built, okb export --format cypher --out my.cypher writes the data for a graph database: instances as nodes labeled with their class chain, properties on the nodes, relationships as typed edges, and the verified domain rules with the quotes they cite.
Building from existing documentation? okb source add docs/button.md reads markdown (frontmatter, headings, lists, callouts, prop tables) and okb quote add finds your quote in it by heading and line. The full quote-first pipeline is in docs/EXTRACTION-PIPELINE.md.
Full guide: docs/METHOD.md · Terms: docs/GLOSSARY.md · Every rule and its source: docs/RULES.md · Modeling choices: docs/DECISIONS.md · File format: docs/FORMAT.md
Findings#
- Errors (MUST rules): fix them.
- Warnings (SHOULD rules): fix them, or record a design decision that explains why not. For example,
okb decision add --title "..." --decision "..." --why "..." --about Sauternes --waives naming-singular-plural-consistent. Explained warnings stop counting against you but stay visible. - Hints (MAY rules): prompts to think about; nothing to fix.
- Warnings and hints appear once you reach the step they belong to. Errors always appear.
okb validate --allshows everything. - The ontology-review skill covers what a script can’t judge, such as whether siblings are equally general or whether something should be a class or a value. It works through the
judgmentrules with you.
Repository layout#
bin/okb.js launcher (npm link target)
src/ okb source (TypeScript, Node 24 type stripping)
cli.ts ops.ts ops/ commands and the operations behind them (ops/ split by reason to change)
checks.ts status.ts validator (one check per rule) and step progress
model.ts types.ts graph model and the typed okb file format
relationships.ts how relationship values are stored as edges (inverses, renames, removal)
naming.ts errors.ts naming conventions; OkbError
metakb.ts render.ts meta-KB access, terminal output
export.ts review.ts graph-database export, judgment-rule review
markdown.ts provenance.ts markdown reader; sources, quotes, extracted rules, verification
quotes.ts gendocs.ts verbatim-quote matching, doc generator
meta-kb/src/*.yaml the meta-KB source (edit these)
meta-kb/data/*.json the compiled meta-KB (npm run build:meta)
meta-kb/build.ts compiler + integrity checks + quote verification
docs/ METHOD/GLOSSARY/RULES/DECISIONS are generated (npm run docs)
examples/ build-wine.ts → examples/wine/ (npm run example)
site/ the docs site (Astro; its own npm package, reads the markdown in place)
skills/ SKILL.md files for Claude
sources/ the source PDFs (gitignored; see sources/README.md)
tests/ node:test suites
Docs site#
The docs in this repo are also published as a website at ontology-kit.dev, with search, a side-panel menu, light and dark themes and reading settings. It’s an Astro site in site/ that reads these markdown files in place, so there’s nothing to copy or keep in sync. To build it, or to work on it with live reload:
npm run site # regenerate docs/, then build the site into site/dist (with the search index)
npm run site:dev # the same, served at http://localhost:4321 while you edit
Run npm ci --prefix site once first. Pages and the menu are listed in site/src/nav.ts; a test fails if a file in docs/ isn’t in it. Search only works on the built site (npm --prefix site run preview). Netlify builds and hosts it from netlify.toml.
Changing rules#
Edit meta-kb/src/*.yaml, then:
npm run verify:quotes # rebuild + check every quote word-for-word against the PDFs
npm run docs # regenerate docs/
npm test
The build fails if a rule cites a quote that doesn’t exist, if a mechanical rule has no check in src/checks.ts (or a check has no rule), or if a step’s checklist refers to a status check that isn’t implemented. See meta-kb/README.md.