Ontology Writing Guide

Recommended ontology levels and writing guidelines organized by complexity.

Ontology Levels by Complexity

Complexity	Ontology Level	Included Elements	Example File
L1	Lightweight Schema	- Entity definitions - Attributes - Basic invariants	ontology/user-schema.yaml
L2	Standard Ontology	- Entities + relationships - Service contracts - Bounded Context	ontology/order-service.yaml
L3	Full Ontology	- Event schemas - Event ordering - Idempotency keys	ontology/order-events.yaml
L4	Full Ontology + Saga	- Saga steps - Compensation logic - Failure scenarios	ontology/booking-saga.yaml
L5	Knowledge Graph	- Event store - Projections - Event version management	ontology/banking-kg.yaml

Level 1-2: Lightweight to Standard Ontology

Focus

Entity and relationship definitions

Writing Principles

• Clear entity boundaries
• Explicit required attributes
• Define basic invariants

Example

# Entity definitions
entities:
  Order:
    attributes:
      - orderId: string
      - customerId: string
      - items: list<OrderItem>
    invariants:
      - orderId must be unique
      - items must not be empty

# Relationship definitions
relationships:
  - Customer hasMany Order
  - Order hasMany OrderItem

Level 3-4: Full Ontology + Saga

Focus

Event schemas + compensation logic

Writing Principles

• Explicit event contracts
• Define compensation logic
• Timeout/retry policies

Example

# Event contracts
events:
  OrderCreated:
    schema: {...}
    producers: [OrderService]
    consumers: [InventoryService, NotificationService]
    idempotencyKey: orderId

# Saga definitions
saga:
  steps:
    - action: reserveInventory
      compensation: releaseInventory
      timeout: 5s

Level 5: Knowledge Graph

Focus

Event sourcing + projections

Writing Principles

• Event version management
• Explicit projection logic
• Event replay strategy

Example

# Event store
eventStore:
  aggregateRoot: BankAccount
  snapshotStrategy: every 100 events

# Projections
projections:
  AccountBalanceView:
    source: [AccountOpened, MoneyDeposited]
    target: read_db.account_balance

SemanticForge Pattern (L5 Only)

Level 5 projects apply the SemanticForge pattern from Ontology Engineering.

Key Features:

• Event = atomic unit of domain knowledge
• Express event relationships as Knowledge Graph
• Projection = Knowledge Graph query

Reference: See Ontology Engineering for detailed guide

Next Steps

• Harness Checklist: Required harnesses by pattern
• Verification Methodology: Ontology verification methods