Skip to main content

Ontology Writing Guide

5 min read
AI documentation guide

Recommended ontology levels and writing guidelines organized by complexity.

Ontology Levels by Complexity​

Table 1. Ontology level, included elements, and example file by complexity level

ComplexityOntology LevelIncluded ElementsExample File
L1Lightweight Schema- Entity definitions
- Attributes
- Basic invariants		ontology/user-schema.yaml
L2Standard Ontology- Entities + relationships
- Service contracts
- Bounded Context		ontology/order-service.yaml
L3Full Ontology- Event schemas
- Event ordering
- Idempotency keys		ontology/order-events.yaml
L4Full Ontology + Saga- Saga steps
- Compensation logic
- Failure scenarios		ontology/booking-saga.yaml
L5Knowledge 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​

The invariants entries below are illustrative domain notation written for human readers, not an executable constraint syntax. The actual validation rules are implemented in each service's schema and validation code.

# 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, MoneyWithdrawn]
    target: read_db.account_balance

SemanticForge Pattern (L5 Only)​

Level 5 projects apply the SemanticForge pattern from Ontology Engineering. The mappings below are proposed analogies for applying it to event sourcing at L5, not the SemanticForge definition itself.

Proposed analogies (L5 only):

  • 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​