ArchitectureLegacy Design Drafts
Domain Definition Language
Domain Definition Language
Status: Implemented
This specification describes the domain definition language for Modeller. We chose a custom DSL parsed with Pidgin parser combinators, rather than YAML (see Format Options for the rationale).
This specification defines a domain definition format designed for:
- Business readability - Definitions read like documentation that business stakeholders can review
- Technology agnostic - Describes what the business does, not how systems implement it
- AI agent friendly - Structured for AI understanding and generation
- Code generation ready - Translatable to multiple output formats
Core Principles
Separation of Concerns
| Concern | Belongs In | Does NOT Belong In |
|---|---|---|
| Domain Model | Entity/Value Object definitions | Database IDs, technical keys |
| Persistence | Separate storage definitions | Domain definitions |
| Interfaces | Command/Query definitions | Entity internals |
| Business Rules | Rules engine (future) | Scattered in definitions |
Domain Building Blocks
┌─────────────────────────────────────────────────────────────┐
│ SERVICE │
│ (Bounded Context) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ ENTITIES │ │ VALUE │ │ REFERENCE │ │
│ │ │ │ OBJECTS │ │ DATA │ │
│ │ - Identity │ │ - No ID │ │ - External │ │
│ │ - Lifecycle │ │ - Immutable │ │ - Read-only │ │
│ │ - Mutable │ │ - Equality │ │ - Not owned │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────────────────┐ ┌───────────────────────────┐│
│ │ COMMANDS │ │ QUERIES ││
│ │ (Business Actions) │ │ (Business Questions) ││
│ │ - Change things │ │ - Retrieve information ││
│ │ - Notify when done │ │ - No changes made ││
│ └─────────────────────────┘ └───────────────────────────┘│
└─────────────────────────────────────────────────────────────┘Implementation
The DSL is implemented with:
| Component | Technology | Location |
|---|---|---|
| Parser | Pidgin parser combinators | src/Modeller.Parser/ |
| Domain Models | Immutable C# records with factory validation | src/Modeller.Domain/ |
| VS Code Extension | TextMate grammar + custom icons | editors/vscode-modeller/ |
| Sample Domain | Full example definitions | samples/modeller/ |
Documents
| Document | Description |
|---|---|
| Overview | Philosophy and design goals |
| Domain Concepts | Entities, Value Objects, Shared Data |
| Behaviours | Commands, Queries, Workflows, and Events |
| File Structure | Project organization |
| Examples | Concrete definition examples |
| AI Integration | How AI agents consume and generate definitions |
| Data Types | Type system reference |
| Glossary | Key terms and definitions |
| Format Options | Why we chose custom DSL over YAML |
| Templates | Code generation templates and engines |
| Implementation Status | Current build status and next steps |
Design Goals
- Business-first - Technical concerns (storage, interfaces) are separate
- Natural language - Reads like English, understandable by non-technical stakeholders
- AI-friendly - Clear semantics for AI understanding and generation
- Version-aware - Support for evolution over time
- Composable - Services can reference other services' data