DomainLang modeling

Write DDD architecture models in .dlang files. DomainLang is a domain-specific language for expressing Domain-Driven Design concepts as code — domains, bounded contexts, context maps, teams, ownership, ubiquitous language, and integration patterns.

Reference: https://domainlang.net

Workflow

Follow these steps when creating a DomainLang model:

1. Identify domains — the high-level business capabilities
2. Declare teams and classifications — who owns what, how strategically important
3. Define bounded contexts — concrete boundaries with terminology
4. Map relationships — how contexts integrate, with DDD patterns
5. Organize — use namespaces and imports for large models

Core syntax

Domains

Domain Sales {
    description: "Revenue generation"
    vision: "Make buying easy"
}

// Subdomains use 'in'
Domain OnlineSales in Sales {
    description: "Digital sales channel"
}

Use nouns reflecting business capabilities, not technical terms.

Teams and classifications

Classification CoreDomain
Classification SupportingDomain
Classification GenericSubdomain

Team SalesTeam
Team PlatformTeam

Declare these before referencing them in bounded contexts.

Bounded contexts

// Full form with header keywords
BoundedContext Orders for Sales as CoreDomain by SalesTeam {
    description: "Order lifecycle and orchestration"

    terminology {
        term Order: "A customer's request to purchase one or more items"
        term OrderLine: "A single line item representing a product and quantity"
        term OrderStatus: "Current state of an order (Pending, Confirmed, Shipped)"
            aka Status
            examples "Pending", "Confirmed", "Shipped"
    }

    decisions {
        decision EventSourcing: "Capture every state change"
        policy Refunds: "Allow refunds within 30 days"
        rule MinOrder: "Minimum order value is $10"
    }

    metadata {
        Language: "TypeScript"
        Status: "Production"
    }

    relationships {
        this [OHS] -> [CF] Billing
    }
}

// Minimal (body is optional)
BoundedContext Orders for Sales

// Body properties (alternative to header keywords)
BoundedContext Orders for Sales {
    classification: CoreDomain   // Alternative to 'as'
    team: SalesTeam              // Alternative to 'by'
    businessModel: "B2B"
    evolution: "Custom Built"
    archetype: "Execution"
}

The for keyword links a bounded context to its parent domain.

Terminology (ubiquitous language)

BoundedContext Orders for Sales {
    terminology {
        term Order: "A customer's request to purchase one or more items"
        term OrderLine: "A single line item representing a product and quantity"
        term OrderStatus: "Current state of an order (Pending, Confirmed, Shipped)"
            aka Status
            examples "Pending", "Confirmed", "Shipped"
    }
}

Terms support:

• aka (or synonyms) — alternative names for the term
• examples — example values

Decisions and governance

Classification Architectural

BoundedContext Orders for Sales {
    decisions {
        decision EventSourcing: "Capture every state change"
        policy Refunds: "Allow refunds within 30 days"
        rule MinOrder: "Minimum order value is $10"
    }
}

Decisions, policies, and rules can be tagged with a classification:

BoundedContext Orders for Sales {
    decisions {
        decision [Architectural] EventSourcing: "Capture every state change"
        rule [Architectural] Idempotency: "All write operations must be idempotent"
    }
}

Metadata

Metadata keys must be declared before use:

Metadata Status
Metadata Language
Metadata Repository

BoundedContext Orders for Sales {
    metadata {
        Status: "Production"
        Language: "TypeScript"
        Repository: "github.com/acme/orders"
    }
}

Inline relationships

Use the this keyword inside a bounded context to define relationships inline:

BoundedContext Orders for Sales {
    relationships {
        this [OHS] -> [CF] Billing
        Payments -> [ACL] this
    }
}

Teams and classifications

Classification CoreDomain
Classification SupportingDomain
Classification GenericSubdomain

Team SalesTeam
Team PlatformTeam
Team DataTeam

Context maps

ContextMap SalesSystem {
    contains Orders, Billing, Shipping, Inventory, Legacy

    Orders [OHS] -> [CF] Billing
    Orders -> [ACL] Shipping
    Orders [P] Inventory
    Orders [SW] Legacy
}

Relationship arrows

Integration patterns

Directional patterns (with ->, <-, and <->)

Symmetric patterns (no arrow)

Symmetric patterns sit between entities with no arrow. Separate Ways also has the >< arrow form.

Pattern placement rules:

• With ->, <-, <->: patterns go between the entity and the arrow: Entity [Pattern] -> [Pattern] Entity, Entity [Pattern] <- [Pattern] Entity, Entity [Pattern] <-> [Pattern] Entity
• [OHS], [PL], and [S] go on the upstream side
• [CF], [ACL], and [C] go on the downstream side
• [SK], [P], and [SW] are symmetric — placed between entities with no arrow: A [SK] B
• >< is an arrow form for Separate Ways only: A >< B (equivalent to A [SW] B)
• Multiple patterns per side: [OHS, PL]

// ✅ Correct: OHS on upstream, CF on downstream
Orders [OHS] -> [CF] Billing

// ✅ Correct: ACL on downstream (right side)
Orders -> [ACL] Shipping

// ✅ Correct: Shared kernel (symmetric, no arrow)
Orders [SK] Inventory

// ✅ Correct: Customer/Supplier
Orders [S] -> [C] Billing

// ✅ Correct: Separate Ways (three equivalent forms)
Orders [SW] Legacy
Orders [SeparateWays] Legacy
Orders >< Legacy

// ✅ Correct: Reverse directional
Payments [ACL] <- Orders

// ✅ Correct: Bidirectional directional form
Orders [OHS] <-> [CF] Shipping

// ❌ Wrong: CF on upstream side — validator warns
Orders [CF] -> [OHS] Billing

Relationship semantics

The arrow and pattern determine the relationship type:

Domain maps

DomainMap Portfolio {
    contains Sales, Support, Platform
}

Domain maps reference domains (not bounded contexts) for high-level portfolio visualization.

Namespaces

Namespace Acme.Sales {
    Domain Sales { vision: "Revenue generation" }
    BoundedContext Orders for Sales { }
}

// Reference with fully qualified name
ContextMap System {
    contains Acme.Sales.Orders
}

Standard library (domainlang/patterns)

The official standard library provides ready-made DDD classifications and metadata keys.

Install:

dlang add domainlang/patterns@v1.0.0

Usage:

import "domainlang/patterns" as Patterns

BoundedContext Orders for Sales as Patterns.Strategic.CoreDomain by SalesTeam {
    description: "Order lifecycle"
    evolution: Patterns.Evolution.CustomBuilt
    archetype: Patterns.Archetypes.Execution

    metadata {
        Patterns.Meta.Status: "Production"
        Patterns.Meta.Language: "TypeScript"
    }

    decisions {
        decision [Patterns.Governance.Architectural] CQRS:
            "Use CQRS for read/write separation"
    }
}

The package namespaces are Strategic, Evolution, Archetypes, Governance, and Meta. Use an import alias (e.g. as Patterns) to qualify references and avoid ambiguity.

Available namespaces:

Prefer using the standard library over declaring custom classifications for these common DDD concepts.

Imports

// Relative imports
import "./shared/teams.dlang"
import "../common/classifications.dlang"

// Path alias imports (configured in model.yaml)
import "@shared/teams"
import "@domains/sales"

// External package imports
import "acme/ddd-core" as Core

// Use imported types with alias prefix
BoundedContext Orders for Core.SalesDomain as Core.CoreDomain { }

Project structure

model.yaml manifest

model:
  name: my-company/domain-model
  version: 1.0.0
  entry: index.dlang

paths:
  "@": "./"
  "@shared": "./shared"
  "@domains": "./domains"

dependencies:
  acme/ddd-core: "v1.0.0"
  acme/compliance:
    ref: v2.0.0
    description: "Compliance classifications"

overrides:
  acme/utils: "v3.0.0"

governance:
  allowedSources:
    - github.com/acme
  requireStableVersions: true

Typical file organization

my-project/
├── model.yaml
├── model.lock           # Generated by dlang install
├── index.dlang          # Entry point
├── domains/
│   ├── sales/
│   │   └── index.dlang
│   └── shipping/
│       └── index.dlang
└── shared/
    ├── teams.dlang
    └── classifications.dlang

CLI commands

Validation rules

The language server validates models and reports issues:

Complete example

// shared/classifications.dlang
Classification CoreDomain
Classification SupportingDomain

// shared/teams.dlang
Team SalesTeam
Team ShippingTeam

// domains/sales.dlang
import "@shared/classifications"
import "@shared/teams"

Metadata Language
Metadata Status

Domain Sales {
    description: "Revenue generation and customer acquisition"
    vision: "Make it easy to buy"
}

BoundedContext Orders for Sales as CoreDomain by SalesTeam {
    description: "Order lifecycle and orchestration"

    terminology {
        term Order: "A customer's request to purchase"
            aka PurchaseOrder
            examples "Order #12345"
        term OrderLine: "A single line item in an order"
    }

    decisions {
        decision EventSourcing: "Capture every state change"
        policy Refunds: "Allow refunds within 30 days"
        rule MinOrder: "Minimum order value is $10"
    }

    metadata {
        Language: "TypeScript"
        Status: "Production"
    }

    relationships {
        this [OHS] -> [CF] Billing
    }
}

BoundedContext Billing for Sales as SupportingDomain by SalesTeam {
    description: "Invoice generation and payment tracking"
}

// index.dlang
import "@domains/sales"
import "@domains/shipping"

ContextMap SalesLandscape {
    contains Orders, Billing, Shipping

    Orders [OHS] -> [CF] Billing
    Orders [OHS] -> [ACL] Shipping
}

DomainMap Portfolio {
    contains Sales, Shipping
}

Reference

• Full syntax: SYNTAX.md
• Standard library: domainlang.net/guide/standard-library
• Documentation: domainlang.net
• Language reference: domainlang.net/reference/language
• Getting started: domainlang.net/guide/getting-started