Knowledge Organization Classifier
Overview
Nearly every enterprise needs an organizational vocabulary to standardize
terminology (customer vs client vs patron), preserve institutional knowledge,
and meet governance/compliance requirements. These vocabularies live on a
spectrum from simple to complex (Ch3):
- Pick list — controlled value list, no hierarchy (country list, currency
codes).
- Taxonomy — parent-child hierarchy with predefined terms and synonyms
(Transportation -> Bike, Bus, Car, Truck).
- Thesaurus — taxonomy plus generic associative ("related") relationships.
- Ontology — a graph/network of classes with object properties, expanded
relationship types, scope notes, and inference. The chapter's argument for
ontologies is flexibility: pick lists/taxonomies/thesauruses require
reorganizing whole hierarchies to add instances; ontologies expand without
structural disruption.
The classifier reads the structural features a spec exhibits and places it on
the spectrum, walking bottom-up so a partial structure (classes but no
properties) does not claim to be a full ontology. The ontology validator
enforces the five core components Ch3 names — classes, subclasses,
individuals, axioms, relationships — and the structural checks from the
AI-assisted-ontology section (subclasses reference existing parents,
relationships reference existing classes). The upgrade helper names the concrete
feature to add to reach the next tier.
When to Use
- Auditing an existing taxonomy/vocabulary before integrating it into an agent KG
- Deciding whether the use case needs a full ontology or a simpler structure
- Validating an AI-assisted ontology draft before publishing it as a service
- Justifying an "upgrade to ontology" recommendation with the missing feature
Phrases: "knowledge organization spectrum", "pick list vs taxonomy",
"taxonomy vs ontology", "ontology core components", "is this a real ontology",
"controlled vocabulary audit", "validate ontology".
When NOT to Use
- Building ontology content. This audits structure; authoring the actual
classes/relationships is domain modeling with experts.
- SKOS cross-vocabulary mapping.
exactMatch / broader / related
between vocabularies is a separate step (Ch3 "Creating a Unified Semantic
Foundation"); this classifies a single vocabulary's structure.
- Entity resolution. Linking records that refer to the same entity is the
three-graph-router linkage gate, not this skill.
Process
| Step |
Input |
Action |
Output |
Verification |
| 1 |
feature spec dict (has_hierarchy, has_synonyms, has_associative, has_classes, has_properties, has_inference, values) |
lib.classify(spec) |
{classification, spectrum_index, reasons} |
bottom-up walk; partial ontology classifies lower |
| 2 |
same |
lib.recommend_upgrade(spec) |
{current, next, action} |
names the concrete feature to add for the next tier |
| 3 |
ontology dict (classes, subclasses, individuals, axioms, relationships) |
lib.validate_ontology_components(ont) |
{valid, present, missing, errors} |
all five components required; valid only if none missing and no dangling refs |
| 4 |
ontology with a subclass whose parent is unknown |
lib.validate_ontology_components(ont) |
error listing the unknown parent |
enforces subclass->parent integrity |
| 5 |
spectrum level + change event |
lib.migration_cost(level, event) |
{cost, upgrade_to, note} |
ontology absorbs every change as LOCAL_ADD; pick_list relationship-type is NOT_EXPRESSIBLE with upgrade_to=ontology; unknown inputs raise |
Rationalizations
| Agent rationalization |
Documented rebuttal |
| "It has classes, so it's an ontology — call it done." |
Classes alone are not an ontology. Ch3 requires five components (classes, subclasses, individuals, axioms, relationships) plus object properties and inference. The classifier walks bottom-up precisely so classes-without-properties does not over-claim ontology status. |
| "A taxonomy is good enough, ontologies are overkill." |
Sometimes true — pick the simplest tier the use case needs. But the chapter's flexibility argument matters: taxonomies require reorganizing whole hierarchies to add instances, ontologies expand without disruption. If the vocabulary will scale and evolve, the upgrade pays off. The classifier just makes the choice explicit. |
| "Dangling subclass parents and relationship endpoints are fine, the meaning is obvious." |
The AI-assisted-ontology validation in Ch3 explicitly checks that "relationships reference existing nodes". A subclass whose parent doesn't exist, or a relationship pointing at a non-existent class, is a structural defect the validator must catch before the ontology is trusted by an agent. |
| "Axioms are academic — skip them." |
Axioms codify domain truths and constraints (Cancer subclassOf Disease; a patient has at most one primary physician). Without them the ontology is a labeled graph, not a reasoning substrate. The validator lists axioms as a required core component. |
| "I'll classify a partial ontology as an ontology to look further along." |
Over-claiming hides the missing features. The classifier reports the true tier and the upgrade action so the gap is visible, not papered over. |
Red Flags
- Spec classified as ontology but
has_inference and has_associative both
false. Misclassification risk — re-check the feature flags; an ontology
needs expanded relationships or inference.
validate_ontology_components returns missing: [individuals] for every
draft. The ontology defines structure but has no instance data — fine for a
schema, but it is not yet operational for agent reasoning.- Many
unknown parent / unknown class errors. The vocabulary was merged
from sources without alignment; harmonize class hierarchies before trusting it.
- Everything classifies as pick_list. The specs lack hierarchy flags —
likely the feature extraction is incomplete, not that every vocabulary is flat.
Non-Negotiable Verification
- Run the benchmark battery.
python cli.py benchmark must report 10/10:
- each spectrum tier classifies correctly; partial ontology does not over-claim
- spectrum indices are monotonic pick_list < taxonomy < ontology
- complete 5-component ontology validates; missing-axioms and unknown-parent fail
- upgrade chains pick_list -> taxonomy
- Run the scenario.
python cli.py scenario healthcare-ontology classifies
currency codes / a transportation taxonomy and validates a healthcare ontology
plus a broken one.
- Verify CLI help.
python cli.py --help exits 0 and prints this SKILL.md
description (so any harness can discover the skill from --help).
Security Posture
- Prompt injection. Vocabulary specs and ontology drafts are untrusted
input - often AI-generated. The classifier reads fixed boolean/list keys
against a fixed spectrum; adversarial flags can over-claim a tier but never
execute. Scope notes and class names are treated as opaque strings, not
instructions.
- Data exfiltration. No network calls, no file writes. Vocabulary content
may encode internal business structure; it stays in-process and appears only
in the stdout report the caller owns.
- Privilege escalation. No shell invocation, no eval, no dynamic import. A
passing validation is advisory - it does not publish the ontology; an
AI-drafted ontology still needs expert review before agents reason over it.
Source Attribution
Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch3 — Knowledge
Representation, section "Knowledge Organization and Ontology Fundamentals": "The
knowledge organization spectrum" (pick list / taxonomy / thesaurus / ontology)
and "Ontology core components" (classes, subclasses, individuals, axioms,
relationships). The structural validation checks (relationships reference
existing nodes; entities have identifying properties) are from "Iterative
ontology creation with AI assistance".
1---2name: knowledge-organization-classifier3description: Classify an organizational vocabulary onto the Ch3 knowledge-organization spectrum — pick list -> taxonomy -> thesaurus -> ontology — by the structural features the spec actually exhibits, walking bottom-up so a partial ontology does NOT over-claim. Also validates that something claiming to be an ontology carries the five core components the chapter names (classes, subclasses, individuals, axioms, relationships) with no dangling parent/class references, and recommends the next-tier upgrade with the concrete feature to add. Use when auditing an existing taxonomy/vocabulary before integrating it into an agent knowledge graph, when deciding whether you need a full ontology or a simpler structure, or when validating an AI-assisted ontology draft. NOT for building the ontology content itself (that is domain modeling), NOT for the SKOS cross-vocabulary mapping step (exactMatch/broader/related — a different primitive), NOT for entity resolution (use three-graph-router's linkage gate).4---56# Knowledge Organization Classifier78## Overview910Nearly every enterprise needs an organizational vocabulary to standardize11terminology (customer vs client vs patron), preserve institutional knowledge,12and meet governance/compliance requirements. These vocabularies live on a13spectrum from simple to complex (Ch3):1415- **Pick list** — controlled value list, no hierarchy (country list, currency16 codes).17- **Taxonomy** — parent-child hierarchy with predefined terms and synonyms18 (Transportation -> Bike, Bus, Car, Truck).19- **Thesaurus** — taxonomy plus generic associative ("related") relationships.20- **Ontology** — a graph/network of classes with object properties, expanded21 relationship types, scope notes, and inference. The chapter's argument for22 ontologies is **flexibility**: pick lists/taxonomies/thesauruses require23 reorganizing whole hierarchies to add instances; ontologies expand without24 structural disruption.2526The classifier reads the structural features a spec exhibits and places it on27the spectrum, walking bottom-up so a partial structure (classes but no28properties) does not claim to be a full ontology. The ontology validator29enforces the five core components Ch3 names — **classes, subclasses,30individuals, axioms, relationships** — and the structural checks from the31AI-assisted-ontology section (subclasses reference existing parents,32relationships reference existing classes). The upgrade helper names the concrete33feature to add to reach the next tier.3435## When to Use3637- Auditing an existing taxonomy/vocabulary before integrating it into an agent KG38- Deciding whether the use case needs a full ontology or a simpler structure39- Validating an AI-assisted ontology draft before publishing it as a service40- Justifying an "upgrade to ontology" recommendation with the missing feature4142Phrases: "knowledge organization spectrum", "pick list vs taxonomy",43"taxonomy vs ontology", "ontology core components", "is this a real ontology",44"controlled vocabulary audit", "validate ontology".4546## When NOT to Use4748- **Building ontology content.** This audits structure; authoring the actual49 classes/relationships is domain modeling with experts.50- **SKOS cross-vocabulary mapping.** `exactMatch` / `broader` / `related`51 between vocabularies is a separate step (Ch3 "Creating a Unified Semantic52 Foundation"); this classifies a single vocabulary's structure.53- **Entity resolution.** Linking records that refer to the same entity is the54 `three-graph-router` linkage gate, not this skill.5556## Process5758| Step | Input | Action | Output | Verification |59|------|-------|--------|--------|--------------|60| 1 | feature spec dict (`has_hierarchy`, `has_synonyms`, `has_associative`, `has_classes`, `has_properties`, `has_inference`, `values`) | `lib.classify(spec)` | `{classification, spectrum_index, reasons}` | bottom-up walk; partial ontology classifies lower |61| 2 | same | `lib.recommend_upgrade(spec)` | `{current, next, action}` | names the concrete feature to add for the next tier |62| 3 | ontology dict (classes, subclasses, individuals, axioms, relationships) | `lib.validate_ontology_components(ont)` | `{valid, present, missing, errors}` | all five components required; valid only if none missing and no dangling refs |63| 4 | ontology with a subclass whose parent is unknown | `lib.validate_ontology_components(ont)` | error listing the unknown parent | enforces subclass->parent integrity |64| 5 | spectrum level + change event | `lib.migration_cost(level, event)` | `{cost, upgrade_to, note}` | ontology absorbs every change as LOCAL_ADD; pick_list relationship-type is NOT_EXPRESSIBLE with upgrade_to=ontology; unknown inputs raise |6566## Rationalizations6768| Agent rationalization | Documented rebuttal |69|------------------------|--------------------|70| "It has classes, so it's an ontology — call it done." | Classes alone are not an ontology. Ch3 requires five components (classes, subclasses, individuals, axioms, relationships) plus object properties and inference. The classifier walks bottom-up precisely so classes-without-properties does not over-claim ontology status. |71| "A taxonomy is good enough, ontologies are overkill." | Sometimes true — pick the simplest tier the use case needs. But the chapter's flexibility argument matters: taxonomies require reorganizing whole hierarchies to add instances, ontologies expand without disruption. If the vocabulary will scale and evolve, the upgrade pays off. The classifier just makes the choice explicit. |72| "Dangling subclass parents and relationship endpoints are fine, the meaning is obvious." | The AI-assisted-ontology validation in Ch3 explicitly checks that "relationships reference existing nodes". A subclass whose parent doesn't exist, or a relationship pointing at a non-existent class, is a structural defect the validator must catch before the ontology is trusted by an agent. |73| "Axioms are academic — skip them." | Axioms codify domain truths and constraints (Cancer subclassOf Disease; a patient has at most one primary physician). Without them the ontology is a labeled graph, not a reasoning substrate. The validator lists axioms as a required core component. |74| "I'll classify a partial ontology as an ontology to look further along." | Over-claiming hides the missing features. The classifier reports the true tier and the upgrade action so the gap is visible, not papered over. |7576## Red Flags7778- **Spec classified as ontology but `has_inference` and `has_associative` both79 false.** Misclassification risk — re-check the feature flags; an ontology80 needs expanded relationships or inference.81- **`validate_ontology_components` returns `missing: [individuals]` for every82 draft.** The ontology defines structure but has no instance data — fine for a83 schema, but it is not yet operational for agent reasoning.84- **Many `unknown parent` / `unknown class` errors.** The vocabulary was merged85 from sources without alignment; harmonize class hierarchies before trusting it.86- **Everything classifies as pick_list.** The specs lack hierarchy flags —87 likely the feature extraction is incomplete, not that every vocabulary is flat.8889## Non-Negotiable Verification90911. **Run the benchmark battery.** `python cli.py benchmark` must report 10/10:92 - each spectrum tier classifies correctly; partial ontology does not over-claim93 - spectrum indices are monotonic pick_list < taxonomy < ontology94 - complete 5-component ontology validates; missing-axioms and unknown-parent fail95 - upgrade chains pick_list -> taxonomy962. **Run the scenario.** `python cli.py scenario healthcare-ontology` classifies97 currency codes / a transportation taxonomy and validates a healthcare ontology98 plus a broken one.993. **Verify CLI help.** `python cli.py --help` exits 0 and prints this SKILL.md100 description (so any harness can discover the skill from --help).101102## Security Posture103104- **Prompt injection.** Vocabulary specs and ontology drafts are untrusted105 input - often AI-generated. The classifier reads fixed boolean/list keys106 against a fixed spectrum; adversarial flags can over-claim a tier but never107 execute. Scope notes and class names are treated as opaque strings, not108 instructions.109- **Data exfiltration.** No network calls, no file writes. Vocabulary content110 may encode internal business structure; it stays in-process and appears only111 in the stdout report the caller owns.112- **Privilege escalation.** No shell invocation, no eval, no dynamic import. A113 passing validation is advisory - it does not publish the ontology; an114 AI-drafted ontology still needs expert review before agents reason over it.115116## Source Attribution117118Distilled from *Agentic GraphRAG* (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch3 — Knowledge119Representation, section "Knowledge Organization and Ontology Fundamentals": "The120knowledge organization spectrum" (pick list / taxonomy / thesaurus / ontology)121and "Ontology core components" (classes, subclasses, individuals, axioms,122relationships). The structural validation checks (relationships reference123existing nodes; entities have identifying properties) are from "Iterative124ontology creation with AI assistance".
AnthonyAlcaraz