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".

MIF Ontology Manager

Manage MIF ontology definition files using yq, jq, and bundled shell scripts. All operations are grounded in the MIF ontology JSON Schema at schema/ontology/ontology.schema.json.

Prerequisites

# Required
brew install yq jq    # or equivalent package manager
# Optional (for JSON Schema validation)
pip install jsonschema
# Optional (for JSON-LD conversion)
pip install pyyaml

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.

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 JSON Schema validation
bash "$SKILL_DIR/scripts/validate_ontology.sh" my.ontology.yaml \
  schema/ontology/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 (uses scripts/yaml2jsonld.py if in MIF repo)
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