Skip to main content
HUMΛN

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

  • ✅ You have organization-specific skills not in the default ontology
  • ✅ You need custom domains (e.g., "quantum_computing", "maritime_law")
  • ✅ You want to define skill hierarchies and relationships
  • ✅ You need to map legacy HR systems to

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

  • API key
  • Organization Passport ID
  • Admin role (ontology management permission)
  • Understanding of your organization's skill model

Implementation

Define a Custom Skill

Create a new skill specific to your organization:

TypeScript:
```typescript
import { HumanClient } from '@human/sdk';

const client = new HumanClient({
  apiKey: process.env.HUMAN_API_KEY,
});

// Define a custom skill
const skill = await client.ontology.createSkill({
  organizationId: 'org_acme',
  skill: 'acme_widget_assembly',
  displayName: 'Acme Widget Assembly',
  description: 'Ability to assemble and QA Acme Widget Model X',
  domain: 'manufacturing',
  parentSkill: 'mechanical_assembly', // Optional: inherit from base skill
  levels: [
    { level: 1, name: 'Novice', description: 'Can assemble with supervision' },
    { level: 2, name: 'Competent', description: 'Can assemble independently' },
    { level: 3, name: 'Proficient', description: 'Can train others' },
    { level: 4, name: 'Expert', description: 'Can design new assembly processes' },
  ],
  metadata: {
    certificationRequired: true,
    safetyTraining: 'widget_safety_101',
  },
});

console.log(`Created skill: ${skill.skillId}`);
```

Python:
```python
from human_sdk import HumanClient

client = HumanClient(api_key=os.environ["HUMAN_API_KEY"])

# Define a custom skill
skill = client.ontology.create_skill(
    organization_id="org_acme",
    skill="acme_widget_assembly",
    display_name="Acme Widget Assembly",
    description="Ability to assemble and QA Acme Widget Model X",
    domain="manufacturing",
    parent_skill="mechanical_assembly",  # Optional: inherit from base skill
    levels=[
        {"level": 1, "name": "Novice", "description": "Can assemble with supervision"},
        {"level": 2, "name": "Competent", "description": "Can assemble independently"},
        {"level": 3, "name": "Proficient", "description": "Can train others"},
        {"level": 4, "name": "Expert", "description": "Can design new assembly processes"},
    ],
    metadata={
        "certification_required": True,
        "safety_training": "widget_safety_101",
    }
)

print(f"Created skill: {skill.skill_id}")
```

Go:
```go
import "github.com/human/sdk-go"

client := human.NewClient(os.Getenv("HUMAN_API_KEY"))

// Define a custom skill
skill, err := client.Ontology.CreateSkill(&human.SkillDefinition{
    OrganizationID: "org_acme",
    Skill:          "acme_widget_assembly",
    DisplayName:    "Acme Widget Assembly",
    Description:    "Ability to assemble and QA Acme Widget Model X",
    Domain:         "manufacturing",
    ParentSkill:    "mechanical_assembly", // Optional: inherit from base skill
    Levels: []human.SkillLevel{
        {Level: 1, Name: "Novice", Description: "Can assemble with supervision"},
        {Level: 2, Name: "Competent", Description: "Can assemble independently"},
        {Level: 3, Name: "Proficient", Description: "Can train others"},
        {Level: 4, Name: "Expert", Description: "Can design new assembly processes"},
    },
    Metadata: map[string]interface{}{
        "certification_required": true,
        "safety_training":        "widget_safety_101",
    },
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Created skill: %s\n", skill.SkillID)
```

REST API:
```bash
curl -X POST https://api.human.ai/v1/ontology/skills \\
  -H "Authorization: Bearer $HUMAN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "organizationId": "org_acme",
    "skill": "acme_widget_assembly",
    "displayName": "Acme Widget Assembly",
    "description": "Ability to assemble and QA Acme Widget Model X",
    "domain": "manufacturing",
    "parentSkill": "mechanical_assembly",
    "levels": [
      { "level": 1, "name": "Novice", "description": "Can assemble with supervision" },
      { "level": 2, "name": "Competent", "description": "Can assemble independently" },
      { "level": 3, "name": "Proficient", "description": "Can train others" },
      { "level": 4, "name": "Expert", "description": "Can design new assembly processes" }
    ],
    "metadata": {
      "certificationRequired": true,
      "safetyTraining": "widget_safety_101"
    }
  }'
```

Define a Custom Domain

Create a new domain (category) for grouping skills:

TypeScript:
```typescript
// Create a custom domain
const domain = await client.ontology.createDomain({
  organizationId: 'org_acme',
  domain: 'aerospace_engineering',
  displayName: 'Aerospace Engineering',
  description: 'Skills related to aircraft and spacecraft design and manufacturing',
  parentDomain: 'engineering', // Optional: nest under existing domain
  metadata: {
    regulatoryBody: 'FAA',
    certificationAuthority: 'EASA',
  },
});

console.log(`Created domain: ${domain.domainId}`);
```

Python:
```python
# Create a custom domain
domain = client.ontology.create_domain(
    organization_id="org_acme",
    domain="aerospace_engineering",
    display_name="Aerospace Engineering",
    description="Skills related to aircraft and spacecraft design and manufacturing",
    parent_domain="engineering",  # Optional: nest under existing domain
    metadata={
        "regulatory_body": "FAA",
        "certification_authority": "EASA",
    }
)

print(f"Created domain: {domain.domain_id}")
```

Go:
```go
// Create a custom domain
domain, err := client.Ontology.CreateDomain(&human.DomainDefinition{
    OrganizationID: "org_acme",
    Domain:         "aerospace_engineering",
    DisplayName:    "Aerospace Engineering",
    Description:    "Skills related to aircraft and spacecraft design and manufacturing",
    ParentDomain:   "engineering", // Optional: nest under existing domain
    Metadata: map[string]interface{}{
        "regulatory_body":          "FAA",
        "certification_authority": "EASA",
    },
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Created domain: %s\n", domain.DomainID)
```

REST API:
```bash
curl -X POST https://api.human.ai/v1/ontology/domains \\
  -H "Authorization: Bearer $HUMAN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "organizationId": "org_acme",
    "domain": "aerospace_engineering",
    "displayName": "Aerospace Engineering",
    "description": "Skills related to aircraft and spacecraft design and manufacturing",
    "parentDomain": "engineering",
    "metadata": {
      "regulatoryBody": "FAA",
      "certificationAuthority": "EASA"
    }
  }'
```

Define Skill Relationships

Create hierarchies and relationships between skills:

TypeScript:
```typescript
// Define skill relationships
await client.ontology.createRelationship({
  organizationId: 'org_acme',
  fromSkill: 'cad_design',
  toSkill: 'aerospace_cad',
  relationship: 'prerequisite', // 'prerequisite', 'related', 'supersedes'
  strength: 0.9, // 0-1, how strong the relationship is
  metadata: {
    requiredLevel: 3, // Must be level 3 in CAD before learning aerospace CAD
  },
});

// Create equivalence mapping (for legacy system integration)
await client.ontology.createEquivalence({
  organizationId: 'org_acme',
  humanSkill: 'project_management',
  externalSystem: 'workday',
  externalSkillId: 'PM_CERT_001',
  bidirectional: true, // Sync both ways
});
```

Python:
```python
# Define skill relationships
client.ontology.create_relationship(
    organization_id="org_acme",
    from_skill="cad_design",
    to_skill="aerospace_cad",
    relationship="prerequisite",  # 'prerequisite', 'related', 'supersedes'
    strength=0.9,  # 0-1, how strong the relationship is
    metadata={
        "required_level": 3,  # Must be level 3 in CAD before learning aerospace CAD
    }
)

# Create equivalence mapping (for legacy system integration)
client.ontology.create_equivalence(
    organization_id="org_acme",
    human_skill="project_management",
    external_system="workday",
    external_skill_id="PM_CERT_001",
    bidirectional=True  # Sync both ways
)
```

Go:
```go
// Define skill relationships
err := client.Ontology.CreateRelationship(&human.SkillRelationship{
    OrganizationID: "org_acme",
    FromSkill:      "cad_design",
    ToSkill:        "aerospace_cad",
    Relationship:   "prerequisite", // 'prerequisite', 'related', 'supersedes'
    Strength:       0.9,             // 0-1, how strong the relationship is
    Metadata: map[string]interface{}{
        "required_level": 3, // Must be level 3 in CAD before learning aerospace CAD
    },
})

if err != nil {
    log.Fatal(err)
}

// Create equivalence mapping (for legacy system integration)
err = client.Ontology.CreateEquivalence(&human.SkillEquivalence{
    OrganizationID:   "org_acme",
    HumanSkill:       "project_management",
    ExternalSystem:   "workday",
    ExternalSkillID:  "PM_CERT_001",
    Bidirectional:    true, // Sync both ways
})
```

REST API:
```bash
# Create skill relationship
curl -X POST https://api.human.ai/v1/ontology/relationships \\
  -H "Authorization: Bearer $HUMAN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "organizationId": "org_acme",
    "fromSkill": "cad_design",
    "toSkill": "aerospace_cad",
    "relationship": "prerequisite",
    "strength": 0.9,
    "metadata": { "requiredLevel": 3 }
  }'

# Create equivalence mapping
curl -X POST https://api.human.ai/v1/ontology/equivalences \\
  -H "Authorization: Bearer $HUMAN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "organizationId": "org_acme",
    "humanSkill": "project_management",
    "externalSystem": "workday",
    "externalSkillId": "PM_CERT_001",
    "bidirectional": true
  }'
```

Use Cases

building:Industry-Specific Skills|Define skills unique to your industry (e.g., "crane_operation_offshore" for maritime)
shuffle:Legacy System Integration|Map your existing HR/talent systems to <HumanBrand /> ontology
briefcase:Compliance Requirements|Define skills with regulatory or certification requirements
network:Skill Hierarchies|Model prerequisite relationships and learning pathways

Best Practices

Naming Conventions

  • Use snake_case for skill IDs (e.g., widget_assembly_advanced)
  • Include organization context for truly unique skills
  • Avoid abbreviations unless industry-standard
  • Be specific rather than generic (e.g., "react_frontend" not "programming")

Skill Definitions

  • Define clear levels with actionable descriptions
  • Document prerequisites for complex skills
  • Include metadata for certifications, safety requirements, etc.
  • Review regularly - skills evolve, ontologies should too

Maintenance

  • Version your ontology - track changes over time
  • Deprecate carefully - provide migration paths for old skills
  • Test queries after ontology changes
  • Document custom skills for future team members

Security Considerations

do:Restrict ontology management to admin roles only
do:Log all ontology changes for audit trails
do:Validate skill names against injection attacks
do:Review custom skills before activating them
dont:Allow skill deletion if capabilities reference it
dont:Create overly broad skills that leak information
dont:Bypass skill validation rules
dont:Share organization-specific ontologies outside the org

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}`,
  });
}

See Also

← All patterns