Vocabulary and Types

Why Shared Vocabularies Matter

In Business-as-Code, we don't invent our own types—we use standardized vocabularies that AI models already understand. This is crucial because:

AI Training: AI models are trained on these vocabularies
Interoperability: Different systems can understand each other
Semantics: Types carry meaning, not just structure
Evolution: Vocabularies evolve with community input

The Three Core Vocabularies

graph TB subgraph Ecosystem["Vocabulary Ecosystem"] S[Schema.org 817 types, 1,518 properties General business entities] O[O*NET 1,459 occupations Workforce & skills] G[GS1 Supply chain standards Products & events] end subgraph Integration["Integrated Knowledge"] K[Knowledge Graph Unified semantic model] end S --> K O --> K G --> K

1. Schema.org - General Business Entities

Purpose: Structured data vocabulary for the web Scope: 817 types, 1,518 properties Maintained by: W3C Community Group URL: https://schema.org

Core Types

// Organizations and People
$.Organization // Companies, businesses, institutions
$.Person // Individual people
$.Brand // Brands and trademarks

// Products and Offers
$.Product // Physical or digital products
$.Service // Services offered
$.Offer // Price and availability information

// E-commerce
$.Order // Purchase orders
$.Invoice // Billing documents
$.Payment // Payment transactions

// Content
$.Article // Written content
$.VideoObject // Video content
$.SoftwareApplication // Software products

// Places
$.Place // Physical locations
$.PostalAddress // Mailing addresses
$.GeoCoordinates // Geographic coordinates

// Events
$.Event // Events and happenings
$.BusinessEvent // Business-specific events

Key Properties

Every Schema.org type inherits from Thing and shares core properties:

interface Thing {
  $id: string // Unique identifier
  $type: string // Type name
  name: string // Human-readable name
  description?: string // Description
  url?: string // URL reference
  identifier?: string // Additional identifier
  sameAs?: string // Equivalent entity elsewhere
}

Example: Organization Type

interface Organization extends Thing {
  $type: 'Organization'
  legalName?: string // Legal name
  taxID?: string // Tax identification
  email?: string // Contact email
  telephone?: string // Phone number
  address?: PostalAddress // Physical address
  founder?: Person // Founder(s)
  employee?: Person[] // Employees
  owns?: Brand[] // Owned brands
  memberOf?: Organization // Parent organization
}

// Usage
const company = await $.Organization.create({
  $type: 'Organization',
  name: 'Acme Corp',
  legalName: 'Acme Corporation LLC',
  taxID: '12-3456789',
  address: {
    $type: 'PostalAddress',
    streetAddress: '123 Main St',
    addressLocality: 'Austin',
    addressRegion: 'TX',
    postalCode: '78701',
    addressCountry: 'US',
  },
})

2. O*NET - Workforce and Occupations

Purpose: Occupational information network Scope: 1,459 occupations, 17,588 tasks, 135 technologies Maintained by: U.S. Department of Labor URL: https://www.onetonline.org

graph TB O[O*NET Occupation] subgraph Structure["O*NET Data Structure"] SOC[SOC Code 15-1252.00] T[Tasks 17,588 task statements] S[Skills 71 core skills] A[Abilities 57 abilities] K[Knowledge 39 areas] TECH[Technologies 135 tech skills] end O --> SOC O --> T O --> S O --> A O --> K O --> TECH

O*NET Packages

The platform includes comprehensive O*NET data:

// Occupation structure
soc.org.ai/        // 1,459 occupation codes
  ├── 15-1252.00   // Software Developers
  ├── 41-3099.00   // Sales Representatives
  └── ...

jobs.org.ai/       // 1,020 job titles
  ├── Full-Stack Developer
  ├── Solutions Architect
  └── ...

tasks.org.ai/      // 17,588 task statements
  ├── Design software systems
  ├── Write clean code
  └── ...

skills.org.ai/     // 71 core skills
  ├── Programming
  ├── Critical Thinking
  └── ...

abilities.org.ai/  // 57 abilities
  ├── Deductive Reasoning
  ├── Problem Sensitivity
  └── ...

knowledge.org.ai/  // 39 knowledge areas
  ├── Computers and Electronics
  ├── Engineering and Technology
  └── ...

tech.org.ai/       // 135 technology skills
  ├── Python
  ├── JavaScript
  ├── React
  └── ...

Example: Software Developer Occupation

interface Occupation {
  $type: 'Occupation'
  $id: 'soc:15-1252.00'
  name: 'Software Developers'
  description: 'Research, design, and develop computer...'

  tasks: Task[] // What they do
  skills: Skill[] // What skills they need
  abilities: Ability[] // Required abilities
  knowledge: Knowledge[] // Knowledge domains
  technologies: Tech[] // Tools they use
}

// Usage: Define an AI agent based on occupation
const developerAgent = await $.Agent.create({
  occupation: $.SOC['15-1252.00'], // Software Developer
  capabilities: ['Design software systems', 'Write and test code', 'Debug applications'],
  technologies: [$.Tech.Python, $.Tech.JavaScript, $.Tech.React],
})

3. GS1 - Supply Chain and Products

Purpose: Global standards for supply chain Scope: Product identification, events, locations Maintained by: GS1 URL: https://www.gs1.org

GS1 Standards

// Product Identification
$.GTIN // Global Trade Item Number
$.GLN // Global Location Number
$.SSCC // Serial Shipping Container Code

// Supply Chain Events (EPCIS)
$.ObjectEvent // Objects observed
$.AggregationEvent // Objects aggregated
$.TransactionEvent // Transaction occurred
$.TransformationEvent // Objects transformed

// Business Steps
$.receiving
$.shipping
$.packing
$.departing
$.arriving
$.inspecting
$.storing

Example: Supply Chain Tracking

// Track product through supply chain
on.ObjectEvent.observed(async (event) => {
  db.SupplyChainEvent.create({
    $type: 'ObjectEvent',
    action: 'OBSERVE',
    epcList: [event.gtin],
    bizStep: $.receiving,
    location: event.gln,
    eventTime: new Date(),
  })
})

// Shipment tracking
on.Shipment.departed(async (shipment) => {
  send.ObjectEvent.create({
    action: 'OBSERVE',
    epcList: shipment.items.map((i) => i.gtin),
    bizStep: $.departing,
    location: shipment.origin.gln,
  })
})

Type System Features

1. Type Hierarchy

Types form inheritance hierarchies:

graph TB Thing[Thing Base type for all entities] Org[Organization Companies, institutions] Corp[Corporation] Edu[EducationalOrganization] Local[LocalBusiness] Food[FoodEstablishment] Rest[Restaurant] Thing --> Org Org --> Corp Org --> Edu Org --> Local Local --> Food Food --> Rest

// Schema.org hierarchy
Thing
  └── Organization
       ├── Corporation
       ├── EducationalOrganization
       └── LocalBusiness
            └── FoodEstablishment
                 └── Restaurant

// Usage
const restaurant = await $.Restaurant.create({
  // Has all properties from:
  // Thing, Organization, LocalBusiness, FoodEstablishment, Restaurant
  name: 'Best Tacos',
  servesCuisine: 'Mexican',
  priceRange: '$$'
})

2. Type Composition

Combine multiple types:

graph TB subgraph Composition["Type Composition"] P1[Person Identity properties] E1[Employee Employment properties] C1[Person + Employee Combined entity] P2[Product Product properties] S2[SoftwareApplication Software properties] C2[Product + SoftwareApplication Combined entity] end P1 --> C1 E1 --> C1 P2 --> C2 S2 --> C2

// A Person who is also an Employee
interface Employee extends Person {
  $type: ['Person', 'Employee']
  employeeID: string
  department: string
  startDate: Date
  salary: number
}

// A Product that is also Software
interface SoftwareProduct extends Product, SoftwareApplication {
  $type: ['Product', 'SoftwareApplication']
  operatingSystem: string
  version: string
  license: string
}

3. Type Extensions

Extend vocabulary types with custom properties:

// Extend Schema.org Organization
interface StartupOrganization extends Organization {
  $type: 'Organization'
  // Custom properties for startups
  fundingStage: 'pre-seed' | 'seed' | 'series-a' | 'series-b'
  monthlyBurnRate: number
  runway: number // months
  investors: Organization[]
}

4. Type Guards

TypeScript type guards for semantic types:

function isPerson(entity: Thing): entity is Person {
  return entity.$type === 'Person'
}

function isOrganization(entity: Thing): entity is Organization {
  return entity.$type === 'Organization'
}

// Usage
const entity = await db.get(id)

if (isPerson(entity)) {
  console.log(entity.givenName) // Type-safe
} else if (isOrganization(entity)) {
  console.log(entity.legalName) // Type-safe
}

Vocabulary Packages

The platform provides typed packages for each vocabulary:

Installation

npm install @dotdo/schema.org.ai
npm install @dotdo/onet.org.ai
npm install @dotdo/gs1.org.ai

Usage

// Import specific types
import { Person, Organization, Product } from '@dotdo/schema.org.ai'
import { Occupation, Task, Technology } from '@dotdo/onet.org.ai'
import { GTIN, ObjectEvent } from '@dotdo/gs1.org.ai'

// Use in code with full type safety
const person: Person = {
  $type: 'Person',
  $id: 'https://example.com/people/john',
  name: 'John Doe',
  givenName: 'John',
  familyName: 'Doe',
  email: '[email protected]',
}

const occupation: Occupation = {
  $type: 'Occupation',
  $id: 'soc:15-1252.00',
  name: 'Software Developers',
  tasks: ['Modify existing software to correct errors', 'Analyze user needs and develop software solutions'],
}

Custom Vocabularies

While you should use standard vocabularies when possible, you can create custom types:

Custom Type Definition

// Define custom type in your codebase
interface DigitalProduct extends Product {
  $type: 'DigitalProduct'
  $context: 'https://yourdomain.com/vocab'

  // Custom properties
  downloadURL: string
  fileSize: number
  fileFormat: string
  licenseType: 'single' | 'unlimited'
  expirationDate?: Date
}

// Register with $
$.defineType('DigitalProduct', {
  extends: $.Product,
  properties: {
    downloadURL: { type: 'string', required: true },
    fileSize: { type: 'number' },
    fileFormat: { type: 'string' },
    licenseType: { type: 'string', enum: ['single', 'unlimited'] },
    expirationDate: { type: 'date' },
  },
})

When to Create Custom Types

✅ Create custom types when:

No standard vocabulary covers your domain
You need industry-specific types
You're extending with proprietary features

❌ Don't create custom types when:

Schema.org already has the type
You can extend an existing type
It's for convenience (use composition instead)

Type Discovery

Explore Available Types

// List all Organization types
const orgTypes = $.Organization.$subtypes
// Returns: ['Corporation', 'EducationalOrganization', ...]

// Get type information
const typeInfo = $.Person.$info
console.log(typeInfo.properties) // All Person properties
console.log(typeInfo.required) // Required properties
console.log(typeInfo.relations) // Possible relationships

Type Search

// Search for types by name
const types = await $.search('software')
// Returns: [SoftwareApplication, SoftwareSourceCode, ...]

// Search by property
const typesWithEmail = await $.searchByProperty('email')
// Returns: [Person, Organization, ContactPoint, ...]

AI and Types

Why AI Understands These Types

AI models (GPT, Claude, etc.) are trained on:

Schema.org markup: Billions of web pages use Schema.org
O*NET data: Standard occupational information
GS1 standards: Global supply chain documentation

When you use these types, AI can:

// AI knows what a Person is
const person = await ai.generate($.Person, {
  context: 'Create a software developer profile',
})
// Returns valid Person with appropriate properties

// AI knows Organization relationships
const org = await ai.analyze($.Organization, company)
console.log(org.insights)
// Returns analysis based on understanding of organizations

// AI can reason about types
const recommendation = await ai.recommend({
  type: $.Product,
  for: customer,
  context: 'complementary products',
})

Best Practices

1. Start with Schema.org

Always check Schema.org first:

// ✅ Use Schema.org
$.Person
$.Organization
$.Product

// ❌ Don't reinvent
$.User // Use Person instead
$.Company // Use Organization instead
$.Item // Use Product instead

2. Use O*NET for Work

For anything related to jobs, skills, or tasks:

// ✅ Use O*NET
$.Occupation['15-1252.00'] // Software Developer
$.Task['Design software systems']
$.Technology.Python

// ❌ Don't create custom
$.Job.Developer // Use O*NET occupation
$.Skill.Coding // Use O*NET skill

3. Compose Types

Combine types for complex entities:

// ✅ Composition
interface EmployeePerson extends Person {
  $type: ['Person', 'Employee']
  employer: Organization
  jobTitle: string
  startDate: Date
}

// ❌ Custom from scratch
interface Worker {
  // Don't do this
  name: string
  company: string
}

4. Document Extensions

When extending types, document clearly:

/**
 * Extended Organization type for startup tracking
 * Adds funding and investor information to Schema.org Organization
 */
interface Startup extends Organization {
  $type: 'Organization'
  $context: 'https://yourdomain.com/vocab'

  // Additional startup-specific fields
  fundingStage: string
  investors: Organization[]
}

Summary

The type system in Business-as-Code is built on three pillars:

Schema.org: 817 types for general business entities
O*NET: 1,459 occupations with tasks, skills, and technologies
GS1: Supply chain standards and product identification

These vocabularies provide:

AI Understanding: Models already know these types
Interoperability: Standard language across systems
Evolution: Community-maintained, continuously updated
Type Safety: Full TypeScript support

Next: Autonomous Operations →

Vocabulary and Types

On this page