🧩 Domain Modeling Patterns

Best practices for semantic modeling.

Entity Patterns

Hierarchical Naming

Use dot notation for entity hierarchies:

Entity "Warehouse.Main" in logistics
Entity "Warehouse.Regional.East" in logistics
Entity "Warehouse.Regional.West" in logistics

Domain Separation

Group related entities by domain:

# Finance domain
Entity "AP" in finance
Entity "AR" in finance
Entity "Treasury" in finance

# Logistics domain
Entity "Warehouse.A" in logistics
Entity "ShippingDock" in logistics

Resource Patterns

Unit Consistency

Define dimensions and units upfront:

Dimension "Currency"
Dimension "Mass"
Dimension "Volume"

Unit "USD" of "Currency" factor 1 base "USD"
Unit "EUR" of "Currency" factor 1.07 base "USD"
Unit "kg" of "Mass" factor 1
Unit "L" of "Volume" factor 1

Domain-Specific Resources

Resource "Money" unit "USD" in finance
Resource "Steel" unit "kg" in manufacturing
Resource "Fuel" unit "L" in logistics

Flow Patterns

Bidirectional Flows

Model both directions for full visibility:

# Payment cycle
Flow "Invoice" from "Vendor.X" to "AP" quantity 1500 "USD"
Flow "Payment" from "AP" to "Vendor.X" quantity 1500 "USD"

Named Flows

Use descriptive names:

# ✅ Good - descriptive
Flow "SteelDelivery_Q1" from "Plant.A" to "Warehouse.Main" quantity 500 "kg"

# ❌ Avoid - generic
Flow "Flow1" from "A" to "B" quantity 500 "kg"

Policy Patterns

Threshold Constraints

Policy max_vendor_payment per Constraint Obligation priority 5
  @rationale "Limit vendor exposure per finance policy"
  @tags ["finance", "risk"]
as:
  sum(f in flows where f.resource = "Money" and f.to.name = "Vendor.X": 
      f.quantity as "USD") <= 5000 "USD"

Uniqueness Constraints

Policy unique_entity_names per Constraint Obligation priority 3 as:
  forall e1 in entities:
    forall e2 in entities:
      (e1 != e2 and e1.namespace = e2.namespace) implies (e1.name != e2.name)

Existence Constraints

Policy primary_warehouse_exists per Constraint Obligation priority 5 as:
  exists e in entities where e.name contains "Primary":
    e.domain = "logistics"

Aggregation Patterns

Sum with Filter

total_received = sum(f in flows 
  where f.to.name = "Warehouse.Main" and f.resource = "Steel": 
  f.quantity as "kg")

Count with Predicate

vendor_count = count(e in entities 
  where e.domain = "suppliers" and e.name startswith "Vendor")

Conditional Aggregation

Policy min_active_vendors per Constraint Obligation priority 4 as:
  count(e in entities 
    where e.domain = "suppliers" and e.status = "active") >= 3

Metadata Patterns

Rationale Documentation

Always document policy rationale:

Policy payment_limit per Constraint Obligation priority 5
  @rationale "Required by SOX compliance section 4.2"
  @tags ["sox", "compliance", "finance"]
  @owner "finance-team"
as:
  <expression>

Version Management

Use semantic versioning:

@namespace "com.example.finance"
@version "2.1.0"  # Major.Minor.Patch
@owner "team-payments"

Anti-Patterns

❌ Avoid

# Too generic
Entity "Thing1" in stuff
Flow "Move" from "A" to "B" quantity 100 "units"

# Missing units
Resource "Inventory" in warehouse  # No unit!

# Undocumented policies
Policy rule1 as: x > 0  # What does this mean?

✅ Prefer

# Descriptive
Entity "Warehouse.Distribution.Central" in logistics
Flow "SteelShipment" from "Plant.Chicago" to "Warehouse.Distribution.Central" quantity 500 "kg"

# With units
Resource "SteelInventory" unit "kg" in manufacturing

# Documented
Policy min_safety_stock per Constraint Obligation priority 5
  @rationale "Maintain 7-day buffer per operations manual"
as:
  current_inventory >= 7 * daily_usage