Custom Ontology

# Custom Ontology

Extend the capability graph with your organization's unique skills and domains.

While provides a comprehensive default skill ontology, every organization has specialized capabilities. This pattern shows you how to define custom skills, domains, and taxonomies that reflect your unique business needs.

When to Use This

Architecture

┌─────────────────────────────────────────────────────┐
│         Your Organization's Skill Model             │
│   - Custom domains                                   │
│   - Specialized skills                               │
│   - Proficiency definitions                          │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
          ┌──────────────────────┐
          │   Ontology Registry  │
          │   (create custom     │
          │    skills & domains) │
          └──────────┬───────────┘
                     │
                     ▼
      ┌──────────────────────────────┐
      │   Capability Graph Engine    │
      │   - Merges with base ontology│
      │   - Validates relationships  │
      │   - Indexes custom skills    │
      └──────────┬───────────────────┘
                 │
                 ▼
    ┌────────────────────────────────┐
    │   Unified Skill Taxonomy       │
    │   - Base + Custom Skills       │
    │   - Organization namespaced    │
    │   - Searchable & queryable     │
    └────────────────────────────────┘

Prerequisites

Implementation

Define a Custom Skill

Create a new skill specific to your organization:

Define a Custom Domain

Create a new domain (category) for grouping skills:

Define Skill Relationships

Create hierarchies and relationships between skills:

Use Cases

Best Practices

Naming Conventions

Skill Definitions

Maintenance

Security Considerations

Common Patterns

Pattern: Import from HR System

async function importSkillsFromHR(csvFile: string) {
  const skills = parseCSV(csvFile); // { name, description, level }
  
  for (const skill of skills) {
    // Create in HUMΛN ontology
    const humanSkill = await client.ontology.createSkill({
      organizationId: 'org_acme',
      skill: toSnakeCase(skill.name),
      displayName: skill.name,
      description: skill.description,
      domain: inferDomain(skill),
      levels: standardizeLevels(skill.level),
    });
    // Create equivalence mapping
    await client.ontology.createEquivalence({
      organizationId: 'org_acme',
      humanSkill: humanSkill.skill,
      externalSystem: 'hr_system',
      externalSkillId: skill.id,
      bidirectional: true,
    });
  }
}

Pattern: Skill Evolution

async function evolveSkill(oldSkill: string, newSkill: string) {
  // Create new skill
  const updated = await client.ontology.createSkill({
    organizationId: 'org_acme',
    skill: newSkill,
    displayName: ${oldSkill} (Updated),
    // ... updated definition
  });
  // Mark relationship
  await client.ontology.createRelationship({
    organizationId: 'org_acme',
    fromSkill: oldSkill,
    toSkill: newSkill,
    relationship: 'supersedes',
    strength: 1.0,
  });
  // Deprecate old skill (don't delete - preserves history)
  await client.ontology.updateSkill({
    organizationId: 'org_acme',
    skill: oldSkill,
    deprecated: true,
    deprecationMessage: Superseded by ${newSkill},
  });
}

Related Patterns

See Also

Same route in the other SDKs

The TypeScript tab above is the contract. These calls hit that same route.