The meta-KB
A knowledge base about building knowledge bases. It’s the single source of truth for:
- the method (8 steps, with guiding questions and “done when” checklists)
- the vocabulary a beginner needs (glossary concepts, in plain language)
- principles and decision guides for judgment calls
- the rules
okb validateenforces and the ontology-review skill asks about - the file format okb ontologies use (node/edge type registry)
It is itself an LPG (data/nodes.json, data/edges.json), so you can load it into the same graph database as your domain KBs.
Grounding#
Every non-toolkit claim is tied to a SourceLocation: a verbatim quote with section and PDF page number, checked word-for-word against the PDF by npm run verify:quotes.
- Ontology 101: Noy, N.F. & McGuinness, D.L. (2001). Ontology Development 101: A Guide to Creating Your First Ontology. Stanford. The method, rules and wine examples.
- Gruber 1993: Gruber, T.R. A Translation Approach to Portable Ontology Specifications. Knowledge Acquisition 5(2). The definition of an ontology, the “knowledge level” principle, and documentation strings. Page numbers are PDF pages (the PDF has a cover page, so they’re one more than the printed numbers).
Each rule states its basis:
direct: the cited passage states the rule.interpretive: it follows from a cited definition;rationaleexplains the step.operational: a toolkit convention with no source. Says so plainly and cites nothing.
…and its modality, taken from the passage’s own wording (“must”/“should always”/“wrong” → MUST; “should” or an imperative guideline → SHOULD; “consider”/“may”/“can” → MAY). Where the toolkit treats a rule more strictly or leniently than its modality suggests, severity is overridden with a written severityReason (for example hier-no-cycles is SHOULD NOT in the paper but an error here, because okb has no way to declare intended equivalence).
Schema#
| Node | Key properties | Edges |
|---|---|---|
MetaKB |
version, formatVersion |
|
Source |
title, authors, year, url |
|
SourceLocation |
section, page, quote, deepLink |
PART_OF → Source |
Principle |
name, statement, plainLanguage |
CITES → SourceLocation |
Concept |
name, aliases, definition, plainLanguage, example, inThisToolkit, origin |
DEFINED_IN → SourceLocation |
Rule |
key, modality, basis, check, severity, severityReason, fromStep, statement, plainLanguage, review, fix |
JUSTIFIED_BY → Rationale, GOVERNS → Concept |
Rationale |
explanation |
CITES → SourceLocation |
Step |
order, name, goal, whyItMatters, guidingQuestions, outputs, doneWhen, tips, wine, commands |
PRECEDES → Step, APPLIES → Rule, INTRODUCES → Concept, USES → Decision, CITES → SourceLocation |
Decision |
name, whenYouFaceIt, tests[{ask, ifYes, ifNo}], note, wine |
CITES → SourceLocation |
NodeType, EdgeType |
the okb file-format registry; origin is ontology101 or operational |
MODELS → Concept |
Editing#
- Edit
src/*.yaml. Quotes must be copied exactly; use...for a deliberate gap. npm run verify:quotes: compilesdata/, re-checks every quote againstsources/*.pdf, and fails on any inconsistency (see the header ofbuild.tsfor the full list).- If you added a mechanical/heuristic rule, add a check with the same id to
src/checks.tsand a fixture totests/checks.test.ts. The build and the test suite both fail until you do. npm run docs && npm test.- Bump
VERSIONinbuild.tswhen rules change meaning or a shipped skill’s instructions change (a patch version for skill-only changes), and update the**Version X.Y.Z.**line at the top of eachskills/*/SKILL.mdto match. Ontologies record the meta-KB version they were created with (okb.json).
Changes from the first draft (v1)#
The v1 meta-KB (build_meta_kb.py) was rebuilt from scratch in v2. Main differences:
- Every rule now cites a quote that actually supports it. In v1 several rules cited the nearest section’s headline quote rather than the sentence that states the rule (for example the no-cycles, synonym and one-child/twelve-children rules all cited unrelated sentences). The v1 inverse-slot rule also overstated the paper, which calls storing both directions redundant (just convenient for data entry) rather than something you should do.
- Modalities were re-derived from the wording. For example, “Do not add strings such as ‘class’…” sits in a list of things “to consider”, so it’s SHOULD NOT (warning), not MUST NOT.
- Quotes are checked mechanically against the PDFs, with page numbers.
- Domain-neutral. Examples come from the paper’s wine ontology rather than Canvas Kit, and the
DomainKBregistry was dropped: which KBs follow the rules is recorded in each KB (okb.json→metaKbVersion), not in the meta-KB. - Added: the method as Step nodes, decision guides, principles (including Gruber’s knowledge-level principle), plain-language explanations, a
basisfor every rule, and the okb file-format registry. The v1EdgeTyperegistry’s design-system edges (COMPOSES,PREFERRED_OVER,CONFLICTS_WITH,IS_VARIANT_OF) are modeled in v2 as Instance-type slots with class-level fixed values. That keeps them inside the Ontology 101 primitives, so they get range and fixed-value checks for free.
v2.1#
- Relationships are stored LPG-style. A relationship slot’s values are edges named after it (
maker→:MAKER) instead of genericHAS_VALUEedges. The file format is nowokb-lpg/2;okb-lpg/1files are migrated automatically when loaded. - Inverse slots are stored once. One edge per fact, read from both ends. The paper calls storing both directions redundant, and in a graph it’s pure duplication.
slot-inverse-consistentnow checks only that domains and ranges mirror each other; values can’t disagree. - Everyday vocabulary. The glossary maps slot → property / relationship, and to OWL datatype/object properties and LPG node properties/relationship types. The CLI adds
okb propertyandokb relationshipalongsideokb slot. okb exportwrites instance data for graph databases (JSON or openCypher).
v2.2#
- Edge properties. Relationships can declare properties for their edges (
condition,strength…), with facets checked by the newslot-edge-propertiesrule, plus a reservedrulereference to the Rule that justifies the link. New glossary entryconcept.edge-propertyand decision guidedecision.edge-or-class(edge property vs. making the relationship its own class). Both are marked as toolkit concepts: Ontology 101’s frame model has no relationship properties.
v2.3#
- Question families. A competency question stands for a type of question (the paper: “just a sketch” and “do not need to be exhaustive”). The new judgment rule
scope-cq-familiesasks, once a question is answered, whether the ontology should also answer its family: the same question about similar things, and related questions about the same thing. Anything not wanted is recorded as out of scope.okb cq linkandokb cq set --status answerablesuggest the family from what’s already built, andokb reviewlists every family. Step 1 now says not to list every question up front, and Step 8 asks about families. scope-no-unneedednow suggests adding the question an element serves before removing the element.
v2.3.1#
- Skills state their version. Each shipped skill starts with
**Version X.Y.Z.**, matching the meta-KB, and checks it againstokb versionwhen it starts; if they differ, it says which is out of date. Changing a skill’s instructions now bumps the version (a patch for skill-only changes), and the docs drift check fails if a skill’s version lags.
v2.4.0#
- Authored rules.
authoredis a documented Rule field (okb rule add --authored, withextracted: false). It is shown inokb rule listandokb showand exported onOkbRule. Authored rules keepprov-cites-quoteandprov-verified. - Qualifier values on Rules. A Rule can carry
values{slotId: value}for slots declared withokb slot add ... --on-rules(appliesToRules), checked like instance values (okb rule add --value condition=open). Rules have no inheritance: nothing is inherited throughREFINES, and no class namedRuleis involved. REFINES(Rule → Rule, optionaladds) andFULFILLS(Instance → Rule) edges, set withokb rule refinesandokb fulfills, and exported. The format registry gainsoptionalPropsfor edge types.okb cite <node> <quote id>attaches an existing quote to a node.- New glossary entries:
concept.prescriptive-vs-descriptive,concept.rule-qualifier,concept.rule-refines,concept.rule-fulfills,concept.authored-rule.