ontology-manager

name	ontology-manager
description	Create, validate, inspect, and convert MIF ontology definition files. Use when the user asks to: create a new ontology, scaffold an ontology, validate an ontology YAML, inspect ontology contents (entities, traits, relationships, namespaces, discovery patterns), convert between YAML and JSON formats, convert to JSON-LD, or get guidance on MIF ontology structure. Triggers on: "ontology", "create ontology", "validate ontology", "inspect ontology", "convert ontology", "ontology schema", "entity types", "traits", "discovery patterns", "namespace hierarchy".
version	0.5.1

MIF Ontology Manager

Manage MIF ontology definition files using yq, jq, ajv, and bundled shell scripts. All operations are grounded in the vendored MIF ontology JSON Schema at schemas/mif/ontology.schema.json (seeded from MIF; first-class and editable in-repo).

In the research-harness this skill is the authoring/validate/inspect surface for the ontology registry (schemas/ontologies/), the pack catalog (.claude/enabled-packs.json), and per-topic ontology binding (harness.config.json topics[].ontologies[]). Its validate_ontology.sh and inspect_ontology.sh are reused by scripts/resolve-ontology.sh (the topical classification/resolution step) and gate_m12 in scripts/verify.sh.

Prerequisites

The harness already provides every dependency — no brew/pip needed, and no PyPI: yq (mikefarah v4), jq, and ajv (with ajv-formats). JSON Schema validation uses ajv (not jsonschema); YAML→JSON uses yq (not pyyaml). Discovery-pattern regex checks use the Python standard library re only.

Workflow Decision Tree

User wants to...
|
+-> Create a new ontology
|   scaffold_ontology.sh <id> <ver> [--extends mif-base]
|   Then edit the generated YAML to add domain content.
|
+-> Validate an ontology
|   validate_ontology.sh <file.yaml> [schema.json]
|
+-> Inspect ontology contents
|   inspect_ontology.sh <file.yaml> [--section X] [--json]
|   Sections: entities, namespaces, traits, relationships, discovery
|
+-> Convert formats
|   convert_format.sh yaml2json <in.yaml> [out.json]
|   convert_format.sh json2yaml <in.json> [out.yaml]
|   convert_format.sh yaml2jsonld <in.yaml> [out.jsonld]
|
+-> Understand the schema
|   Read references/schema-reference.md
|
+-> Add entity types / traits / relationships / patterns
|   Use yq commands documented below.
|
+-> Curate negative_examples at scale from a confusion export
|   Read references/negative-examples-curation.md (corpus-regen,
|   baseline calibrate, and partition-and-draft steps for spinning up
|   parallel drafting agents). Human spot-check and curation into the
|   YAML are never delegated to an agent — MIF ADR-020 requires
|   negative_examples be human-curated, never auto-mined.

Scripts

All scripts are in scripts/ relative to this skill directory. Set SKILL_DIR to this skill's path before running.

scaffold_ontology.sh

Generate a new ontology skeleton with valid structure.

# Standalone ontology
bash "$SKILL_DIR/scripts/scaffold_ontology.sh" \
  my-domain 0.1.0 > my-domain.ontology.yaml

# Extending mif-base
bash "$SKILL_DIR/scripts/scaffold_ontology.sh" \
  my-domain 0.1.0 --extends mif-base \
  > my-domain.ontology.yaml

# Extending multiple parents
bash "$SKILL_DIR/scripts/scaffold_ontology.sh" \
  my-domain 0.1.0 --extends mif-base,shared-traits \
  > my-domain.ontology.yaml

validate_ontology.sh

Validate ontology YAML for correctness.

# Basic validation (syntax, required fields, formats)
bash "$SKILL_DIR/scripts/validate_ontology.sh" my.ontology.yaml

# With explicit JSON Schema (defaults to the vendored schemas/mif/ontology.schema.json)
bash "$SKILL_DIR/scripts/validate_ontology.sh" my.ontology.yaml \
  schemas/mif/ontology.schema.json

Checks: YAML syntax, required fields (ontology.id, ontology.version), ID format, semver, base types, entity name format, trait references, discovery regex validity, optional JSON Schema compliance.

inspect_ontology.sh

Introspect ontology contents.

# Full summary
bash "$SKILL_DIR/scripts/inspect_ontology.sh" my.ontology.yaml

# Specific section
bash "$SKILL_DIR/scripts/inspect_ontology.sh" my.ontology.yaml \
  --section entities

# JSON output (pipe to jq for queries)
bash "$SKILL_DIR/scripts/inspect_ontology.sh" my.ontology.yaml \
  --section traits --json

Sections: entities, namespaces, traits, relationships, discovery, all (default).

convert_format.sh

Convert between YAML, JSON, and JSON-LD.

# YAML -> JSON
bash "$SKILL_DIR/scripts/convert_format.sh" yaml2json my.ontology.yaml

# JSON -> YAML
bash "$SKILL_DIR/scripts/convert_format.sh" json2yaml my.ontology.json

# YAML -> JSON-LD (yq/jq projection with a minimal @context; no PyPI)
bash "$SKILL_DIR/scripts/convert_format.sh" yaml2jsonld my.ontology.yaml

Common yq/jq Operations

Query Operations

# List all entity type names
yq -r '.entity_types[].name' ontology.yaml

# Count entities by base type
yq '.entity_types | group_by(.base) |
  map({key: .[0].base, value: length}) |
  from_entries' ontology.yaml

# List all trait names
yq -r '.traits | keys | .[]' ontology.yaml

# List all relationship names
yq -r '.relationships | keys | .[]' ontology.yaml

# Show namespace tree (children only)
yq '.namespaces | .. | .children? // empty | keys' ontology.yaml

# Find entities using a specific trait
yq '.entity_types[] |
  select(.traits and (.traits[] == "timestamped")) |
  .name' ontology.yaml

# Count discovery patterns
yq '[.discovery.content_patterns // [],
  .discovery.file_patterns // []] |
  flatten | length' ontology.yaml

Mutation Operations

# Add a new entity type
yq -i '.entity_types += [{
  "name": "my-entity",
  "description": "Description here",
  "base": "semantic",
  "traits": ["timestamped"],
  "schema": {
    "required": ["name"],
    "properties": {
      "name": {"type": "string", "description": "Name"}
    }
  }
}]' ontology.yaml

# Add a new trait
yq -i '.traits.my-trait = {
  "description": "My custom trait",
  "fields": {
    "my_field": {
      "type": "string",
      "description": "Field description"
    }
  }
}' ontology.yaml

# Add a new relationship
yq -i '.relationships.my-rel = {
  "description": "Links A to B",
  "from": ["entity-a"],
  "to": ["entity-b"],
  "symmetric": false
}' ontology.yaml

# Add a content discovery pattern
yq -i '.discovery.content_patterns += [{
  "pattern": "\\bmy-keyword\\b",
  "namespace": "_semantic/knowledge",
  "context": "my domain context"
}]' ontology.yaml

# Add a child namespace
yq -i '.namespaces._semantic.children.my-sub = {
  "description": "My sub-namespace",
  "type_hint": "semantic"
}' ontology.yaml

# Bump version
yq -i '.ontology.version = "0.2.0"' ontology.yaml

Ontology Design Guidelines

Naming Conventions

• IDs: lowercase, hyphens only (my-domain, not myDomain)
• Entity names: lowercase, hyphens (support-ticket)
• Trait names: lowercase, underscores for field names (created_at)
• Namespaces: underscore prefix for top-level (_semantic)

Cognitive Triad Mapping

Memory Type	Use For	Namespace
semantic	Facts, concepts, entities, decisions	_semantic/
episodic	Events, incidents, sessions, timelines	_episodic/
procedural	Processes, runbooks, patterns, how-tos	_procedural/

When to Extend vs. Standalone

• Extend mif-base: Almost always. Provides cognitive triad namespaces, base traits, and base relationships.
• Extend shared-traits: When you need reusable traits like lifecycle, auditable, categorized, tagged, scored.
• Standalone: Only for experimental or self-contained ontologies.

Entity Type Design

1. Choose the correct base type (semantic/episodic/procedural)
2. Compose with existing traits before defining new fields
3. Use schema.required for mandatory fields
4. Use enum for controlled vocabularies
5. Keep descriptions concise (use >- folded scalars in YAML)

Discovery Pattern Tips

• Content patterns: use \b word boundaries for precision
• File patterns: match against file path segments
• Always test regex: python3 -c "import re; re.compile(r'...')"
• Set suggest_entity to auto-classify matched content

Schema Reference

For complete field definitions, types, and constraints, see references/schema-reference.md.

The authoritative JSON Schema is at: schema/ontology/ontology.schema.json