System Design (LLD)Introduction to DDD

Introduction to Domain-Driven Design

LevelIntermediate

Duration60 mins

TopicIntroduction to DDD

3 / 4

Ubiquitous Language

The Language of the Domain

In 2003, when Eric Evans introduced Domain-Driven Design, he made a provocative claim: the most important artifact in software development is not the code, not the architecture diagrams, not the requirements documents—it's the language that the team uses to talk about the domain.

This language, which Evans called the Ubiquitous Language, is a rigorous, shared vocabulary that connects domain experts, developers, testers, and all stakeholders. It's 'ubiquitous' because it appears everywhere—in conversations, in documentation, in code, in tests. Every discussion uses it. Every class name reflects it. Every method call expresses it.

The Ubiquitous Language is perhaps the most underestimated concept in DDD. Teams often rush past it to get to the 'real work' of coding. But without a shared language, all the Entities, Value Objects, and Aggregates in the world won't save your project from the creeping fog of miscommunication.

What You Will Learn

By the end of this page, you will understand what the Ubiquitous Language is, why it's essential, and how to develop and maintain it. You'll learn to recognize when language drift is harming your project and how to bring the language back into alignment. Most importantly, you'll see how the language is reflected in code.

The Hidden Cost of Translation

Consider a typical scene in software development:

Domain Expert: "When a subscriber's benefit period resets, we need to restore their coverage caps based on their plan tier, accounting for any carryover allowances and pro-rated adjustments."

Developer's Mental Translation: "Okay, so there's a User, and they have a subscription status field. When the yearly flag triggers, I update the limits table. There's some math for the percentage stuff."

What happened here? The developer heard business terminology and translated it into their own technical vocabulary. This translation happens constantly—and it's deeply problematic.

Where Translation Breaks Down:

Information Loss: The developer's simpler mental model discards nuances. 'Subscriber' becomes 'User', losing the relationship implications of subscription.
Drift Over Time: As the system evolves, the translation table in developers' heads diverges. One says 'account', another says 'user', a third says 'customer'.
Verification Failures: When domain experts review code or test the system, they can't connect what they see to what they specified.
Onboarding Costs: New team members must learn two languages—the domain language AND the arbitrary technical vocabulary.

The Translation Problem in Action
Domain Expert Says	Developer Thinks	Code Says	Problem
"Policy reinstatement"	"Reactivate the record"	`user.status = 'active'`	Nuance lost; reinstatement ≠ simple activation
"Accrued but unpaid interest"	"Some interest calculation"	`calculateInterest()`	Domain concept invisible in code
"Grace period"	"Extra time buffer"	`delayDays: 14`	Magic number with no meaning
"Beneficiary designation"	"Who gets the money"	`recipientId: string`	Rich concept reduced to ID reference
"Claims adjudication"	"Process the claim"	`processItem()`	Critical business process hidden

The Translation Tax

Every time a developer translates domain concepts into technical jargon, the team pays a cognitive tax. This tax compounds over time. After a year, the codebase is written in a private language that only current developers understand—and even they have forgotten why certain terms were chosen.

What is the Ubiquitous Language?

The Ubiquitous Language is a rigorously defined, shared vocabulary for the domain model that is:

Ubiquitous: Used everywhere—in team discussions, requirements documents, design sessions, code, tests, and user interfaces. There's no 'business language' vs 'technical language'. Just one language.

Precise: Terms have specific, agreed-upon meanings. 'Customer' means exactly one thing. If there's ambiguity, we resolve it by refining the language.

Bounded: The language applies within a Bounded Context. In different contexts, the same word may have different meanings—and that's explicitly acknowledged.

Evolving: As understanding of the domain deepens, the language evolves. New terms are introduced. Existing terms are refined. Outdated terms are retired.

Executable: The language is directly reflected in code. Class names, method names, variable names all use the Ubiquitous Language. The code IS the model, expressed in the language.

Properties of a Good Ubiquitous Language

•Domain Expert Readable — Domain experts can look at class names and method signatures and recognize their concepts. 'Yes, that's how claims work.'
•Developer Usable — The language follows naming conventions that work in code. Names are pronounceable, typeable, and don't conflict with keywords.
•Consistent — The same concept is always referred to by the same term. No synonyms allowed within a context.
•Complete — All significant domain concepts have names. If something is important enough to code, it's important enough to name explicitly.
•Documented — A glossary exists that defines each term, even if informally. New team members can learn the vocabulary.
•Enforced — The team actively corrects language violations. If someone uses the wrong term, they're gently reminded of the correct one.

Language as a First-Class Artifact

Treat your Ubiquitous Language as seriously as your code. Refactoring a class name because the domain term changed is as legitimate as refactoring for performance. A typo in the language is as serious as a bug in the logic.

The Language in Code

The Ubiquitous Language isn't just for meetings—it must be directly reflected in the code. When a domain expert describes a business process, the corresponding code should read almost like a transcript of that description.

The Goal: A domain expert should be able to look at the domain layer code and say: "Yes, I can see my concepts here. I recognize this. This is how our business works."

This is possible when we:

Name classes after domain concepts
Name methods after domain operations
Name parameters and variables after domain terms
Organize code to mirror domain structure

poor-language.ts
Poor Language
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// ❌ Technical jargon, no domain language
 
class DataHandler {
    processItem(obj: any, flag: boolean): void {
        if (flag && obj.status === 1) {
            obj.status = 2;
            this.calculateValue(obj);
            this.save(obj);
        }
    }
    
    calculateValue(obj: any): void {
        obj.val = obj.items.reduce(
            (sum, i) => sum + i.amt * i.qty, 0
        );
    }
}
 
class RecordProcessor {
    handleEvent(data: Record<string, any>): void {
        const record = this.lookup(data.id);
        if (record.type === 'A') {
            this.doActionA(record);
        } else {
            this.doActionB(record);
        }
    }
}
 
// What domain is this? What business process?
// Impossible to tell without context
// Domain experts cannot verify correctness

ubiquitous-language.ts
Ubiquitous Language
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// ✅ Domain language expressed in code
 
class Order {
    confirm(): ConfirmationResult {
        if (!this.canBeConfirmed()) {
            return ConfirmationResult.failed(
                'Order cannot be confirmed'
            );
        }
        
        this.status = OrderStatus.Confirmed;
        this.calculateOrderTotal();
        this.raise(new OrderConfirmed(this.id));
        
        return ConfirmationResult.success();
    }
    
    private calculateOrderTotal(): void {
        this.total = this.orderLines.reduce(
            (sum, line) => sum.add(line.lineTotal),
            Money.zero(this.currency)
        );
    }
}
 
class ClaimsAdjudicator {
    adjudicate(claim: Claim): AdjudicationResult {
        if (claim.isWithinCoveragePeriod()) {
            return this.processApprovedClaim(claim);
        } else {
            return this.rejectForExpiredCoverage(claim);
        }
    }
}
 
// Insurance domain? Order processing?
// Immediately clear from the code
// Domain experts can review and validate

Notice the difference:

In the poor example, we have 'handlers', 'processors', 'items', 'records', 'flags'. These are implementation concepts that reveal nothing about the domain.

In the Ubiquitous Language example, we have 'Orders', 'OrderLines', 'Claims', 'Adjudication', 'Coverage Periods'. These are domain concepts that a business expert would recognize.

The second example isn't just more readable—it's verifiable. A domain expert can examine this code and confirm that it correctly represents the business process. They can point out missing edge cases or incorrect assumptions because they can understand what the code is saying.

Building the Ubiquitous Language

The Ubiquitous Language isn't discovered in a single meeting or documented in a glossary and forgotten. It emerges through continuous collaboration between domain experts and developers, and it evolves as understanding deepens.

The Process:

1. Listen Actively to Domain Experts

Pay attention to the specific words domain experts use. When they say 'reinstatement' instead of 'reactivation', that's meaningful. When they distinguish between a 'quote' and a 'proposal', there's a difference.

2. Question Ambiguities

When you hear the same word used differently in different contexts, flag it. "When you say 'customer' here, is that the same as 'customer' in billing?" Often, these reveal different concepts that need different names.

3. Model in Language

Before writing code, describe the model in words. "So an Order contains OrderLines. Each OrderLine references a Product and has a Quantity. An Order can be Confirmed, which calculates the OrderTotal..." This verbal modeling surfaces gaps.

4. Validate with Code

Implement the model using the language. If naming something is awkward, that's a sign the concept isn't clear. If a domain expert can't recognize their concepts in the code, the language isn't ubiquitous yet.

5. Refine Continuously

As you learn more, update the language. Rename classes. Split concepts that turned out to be multiple things. Merge concepts that were unnecessarily separated.

Converting Mermaid diagram...

Techniques for Language Discovery

•Event Storming — Collaborative workshop where domain experts and developers map out domain events on sticky notes, naturally surfacing the vocabulary.
•Example Mapping — Start with concrete examples of business scenarios. The terms used to describe examples become the language.
•Glossary Maintenance — Keep a living glossary document that defines each term. Update it in every session where language is discussed.
•Code Reviews with Domain Experts — Periodically have domain experts review domain layer code. Their confusion or corrections refine the language.
•Write Tests in Domain Language — Test names and test data that use domain terms validate that the language works in practice.

Language Boundaries and Contexts

A critical insight: the Ubiquitous Language is scoped to a Bounded Context. This is liberating rather than limiting.

In an enterprise, different departments legitimately use the same words to mean different things:

Sales Context: 'Customer' is a prospect or active buyer with purchasing history, preferences, and negotiated prices
Support Context: 'Customer' is a ticket requester with support history and SLA tier
Shipping Context: 'Customer' is simply a delivery recipient with an address

Attempting to create a single, enterprise-wide definition of 'Customer' that satisfies all contexts creates a bloated abstraction that serves no one well.

Context-Specific Languages:

Within each Bounded Context, the Ubiquitous Language is crisp and unambiguous. Between contexts, we acknowledge that words may differ. When integrating, we explicitly translate—and the Anti-Corruption Layer pattern exists precisely for this purpose.

This context-scoping has practical implications for code organization:

context-languages.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
// Each Bounded Context has its own Ubiquitous Language
// and therefore its own domain model
 
// ═══════════════════════════════════════════════════════
// SALES CONTEXT - Language focuses on buying behavior
// ═══════════════════════════════════════════════════════
namespace SalesContext {
    // In Sales, we call them "Customers"
    export class Customer {
        constructor(
            public readonly customerId: CustomerId,
            public readonly accountManager: AccountManager,
            public readonly pricingTier: PricingTier,
            public readonly purchaseHistory: PurchaseHistory,
            public readonly discountAgreements: DiscountAgreement[]
        ) {}
        
        // Sales language: "placing an order"
        placeOrder(items: OrderRequest[]): Order {
            const applicableDiscounts = this.findApplicableDiscounts(items);
            return Order.create(this.customerId, items, applicableDiscounts);
        }
        
        // Sales language: "qualify for tier upgrade"
        qualifiesForTierUpgrade(): boolean {
            return this.purchaseHistory.totalSpend()
                .exceeds(this.pricingTier.upgradeThreshold);
        }
    }
}
 
// ═══════════════════════════════════════════════════════
// SUPPORT CONTEXT - Language focuses on issue resolution
// ═══════════════════════════════════════════════════════
namespace SupportContext {
    // In Support, we call them "Requesters" (different concept!)
    export class Requester {
        constructor(
            public readonly requesterId: RequesterId,
            public readonly externalCustomerId: string,  // Link to Sales
            public readonly supportPlan: SupportPlan,
            public readonly ticketHistory: TicketHistory,
            public readonly preferredChannel: CommunicationChannel
        ) {}
        
        // Support language: "opening a ticket"
        openTicket(issue: IssueDescription): SupportTicket {
            const priority = this.supportPlan.determinePriority(issue);
            return SupportTicket.create(
                this.requesterId,
                issue,
                priority,
                this.supportPlan.slaDeadline(priority)
            );
        }
        
        // Support language: "escalation eligibility"
        canEscalate(ticket: SupportTicket): boolean {
            return this.supportPlan.allowsEscalation() &&
                   ticket.hasExceededInitialResponseTime();
        }
    }
}
 
// ═══════════════════════════════════════════════════════  
// SHIPPING CONTEXT - Language focuses on delivery
// ═══════════════════════════════════════════════════════
namespace ShippingContext {
    // In Shipping, we call them "Recipients" (different again!)
    export class Recipient {
        constructor(
            public readonly recipientId: RecipientId,
            public readonly externalCustomerId: string,
            public readonly deliveryAddress: DeliveryAddress,
            public readonly deliveryPreferences: DeliveryPreferences,
            public readonly accessInstructions: string | null
        ) {}
        
        // Shipping language: "can receive delivery"
        canReceiveDeliveryOn(date: Date): boolean {
            return this.deliveryPreferences.acceptsDeliveriesOn(date);
        }
        
        // Shipping language: "requires signature"
        requiresSignature(): boolean {
            return this.deliveryPreferences.signatureRequired;
        }
    }
}

Same Person, Different Concepts

Customer, Requester, and Recipient might all refer to the same real-world person. But they represent different concepts—different views of that person that are relevant to different business capabilities. The Ubiquitous Language isn't about the real world; it's about how the model views the world.

Language Degradation and Revival

Languages, like gardens, require maintenance. Without active care, the Ubiquitous Language degrades. New team members introduce their own terms. Legacy code contradicts the current vocabulary. Shortcuts become normalized. Eventually, the language fragments—different parts of the team use different words for the same thing, or the same word for different things.

Signs of Language Degradation:

Warning Signs

•Synonym Proliferation — The same concept is called 'customer', 'user', 'client', and 'account' in different parts of the code.
•Constant Translation — Developers regularly translate between 'what the business calls it' and 'what the code calls it'.
•Onboarding Confusion — New team members are frequently confused about terminology and receive conflicting explanations.
•Meeting Clarifications — Discussions frequently pause for clarification: 'Wait, do you mean X-type customer or Y-type customer?'
•Code-Documentation Mismatch — Documentation uses different terms than the code, requiring mental mapping.
•Domain Expert Alienation — Domain experts stop reading code or tests because they can't recognize their concepts.

Reviving the Language:

When you recognize degradation, explicit effort is needed to restore the language:

1. Audit the Codebase: Identify all the terms currently in use. Group synonyms. Note inconsistencies.

2. Reconvene with Domain Experts: Have conversations about the current state. Which terms are correct? Which were always wrong? Which have become obsolete?

3. Create a Canonical Glossary: Document the agreed-upon terms with precise definitions. Make it accessible to the whole team.

4. Refactor Systematically: Rename classes, methods, variables to align with the canonical language. This is not optional—misnamed code is incorrect code.

5. Enforce Going Forward: Code reviews should check for language compliance. Lint rules can catch some violations. New team members should learn the glossary early.

Language Hygiene

The best time to maintain the Ubiquitous Language is continuously. Every code review should ask: 'Does this use our domain language?' Every meeting should notice when language drifts. Small, continuous corrections prevent large, painful refactoring sessions later.

Practical Guidelines for Language Use

Here are actionable guidelines for maintaining a strong Ubiquitous Language in your projects:

Ubiquitous Language Guidelines
Guideline	Do	Don't
Class Names	Use exact domain nouns: `Policy`, `Claim`, `Beneficiary`	Use technical patterns: `PolicyManager`, `ClaimHandler`
Method Names	Use domain verbs: `reinstate()`, `adjudicate()`, `underwrite()`	Use generic verbs: `process()`, `handle()`, `execute()`
Variable Names	Use domain terms: `coverageLimit`, `gracePeriod`	Use abbreviations or generic names: `cl`, `gp`, `val`
Parameters	Name for meaning: `effectiveDate: Date`	Name for type: `date: Date`
Boolean Methods	Domain predicates: `isWithinGracePeriod()`	Technical checks: `checkFlag()`
Exceptions	Domain exceptions: `GracePeriodExpired`	Generic exceptions: `InvalidStateException`
Comments	Explain why (domain reasoning)	Explain what (if code is clear, unneeded)

naming-examples.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
// ═══════════════════════════════════════════════════════
// NAMING IN THE UBIQUITOUS LANGUAGE
// ═══════════════════════════════════════════════════════
 
// ❌ Technical/Generic Naming
class AccountProcessor {
    handleRequest(req: Request): Response {
        const record = this.fetch(req.id);
        if (record.status === 'A') {
            return this.processActiveRecord(record);
        }
        throw new InvalidOperationException('Bad status');
    }
}
 
// ✅ Ubiquitous Language Naming
class PolicyUnderwriter {
    evaluateApplication(application: InsuranceApplication): UnderwritingDecision {
        const applicant = this.retrieveApplicant(application.applicantId);
        if (applicant.meetsEligibilityCriteria()) {
            return this.underwrite(application, applicant);
        }
        throw new ApplicantIneligible(applicant.id, applicant.ineligibilityReason());
    }
}
 
// ═══════════════════════════════════════════════════════
// EXCEPTION NAMING
// ═══════════════════════════════════════════════════════
 
// ❌ Technical Exception
class InvalidStateException extends Error {}
class ProcessingFailedException extends Error {}
 
// ✅ Domain Exception
class PolicyLapsed extends Error {
    constructor(public readonly policyId: PolicyId, public readonly lapseDate: Date) {
        super(`Policy ${policyId} lapsed on ${lapseDate.toISOString()}`);
    }
}
 
class InsufficientCoverage extends Error {
    constructor(
        public readonly claimedAmount: Money,
        public readonly availableCoverage: Money
    ) {
        super(`Claimed ${claimedAmount} exceeds coverage ${availableCoverage}`);
    }
}
 
// ═══════════════════════════════════════════════════════
// METHOD/PREDICATE NAMING
// ═══════════════════════════════════════════════════════
 
// ❌ Technical Predicates
class Account {
    isValid(): boolean { /* ... */ }
    hasStatus(status: string): boolean { /* ... */ }
    checkAmount(amount: number): boolean { /* ... */ }
}
 
// ✅ Domain Predicates
class InsurancePolicy {
    isInGoodStanding(): boolean { /* premium paid, no pending issues */ }
    allowsClaim(claimType: ClaimType): boolean { /* coverage includes type */ }
    isWithinCoveragePeriod(date: Date): boolean { /* date falls in active period */ }
    exceedsCoverageLimit(amount: Money): boolean { /* amount vs remaining limit */ }
}

Summary: The Power of Shared Language

The Ubiquitous Language is the invisible thread that connects domain experts, developers, code, documentation, and tests. Without it, translation errors compound into failed projects. With it, the entire team speaks with one voice about the domain.

Key Takeaways

•Translation is expensive — Every time developers translate domain concepts into technical jargon, information is lost and errors creep in.
•The language must be ubiquitous — Used in conversations, documentation, code, and tests. One language, everywhere.
•Code reflects language — Class names, method names, and exceptions should use domain vocabulary. Domain experts should recognize their concepts in code.
•Language is bounded — The Ubiquitous Language applies within a Bounded Context. Different contexts may use different terms for similar concepts.
•Language evolves — As understanding deepens, the language is refined. This triggers refactoring, not just documentation updates.
•Language requires maintenance — Without active care, languages degrade. Regular attention prevents painful restoration later.

What's Next:

We've covered the foundational concepts of DDD: what it is, its strategic and tactical dimensions, and the Ubiquitous Language that ties it together. The final question is: When should you use DDD? Not every project warrants this level of investment. In the next page, we'll explore the criteria for deciding when DDD is appropriate—and when simpler approaches are better.

Page Complete

You now understand the Ubiquitous Language—what it is, why it matters, how to build it, and how to maintain it. This language is the foundation of successful DDD projects. Next, we'll explore when DDD is the right choice versus when simpler approaches are more appropriate.

3 / 4

Loading learning content...

System Design (LLD)Introduction to DDD

Introduction to Domain-Driven Design

LevelIntermediate

Duration60 mins

TopicIntroduction to DDD

3 / 4

Ubiquitous Language

The Language of the Domain

What You Will Learn

The Hidden Cost of Translation

Consider a typical scene in software development:

Domain Expert: "When a subscriber's benefit period resets, we need to restore their coverage caps based on their plan tier, accounting for any carryover allowances and pro-rated adjustments."

What happened here? The developer heard business terminology and translated it into their own technical vocabulary. This translation happens constantly—and it's deeply problematic.

Where Translation Breaks Down:

Information Loss: The developer's simpler mental model discards nuances. 'Subscriber' becomes 'User', losing the relationship implications of subscription.
Drift Over Time: As the system evolves, the translation table in developers' heads diverges. One says 'account', another says 'user', a third says 'customer'.
Verification Failures: When domain experts review code or test the system, they can't connect what they see to what they specified.
Onboarding Costs: New team members must learn two languages—the domain language AND the arbitrary technical vocabulary.

The Translation Problem in Action
Domain Expert Says	Developer Thinks	Code Says	Problem
"Policy reinstatement"	"Reactivate the record"	`user.status = 'active'`	Nuance lost; reinstatement ≠ simple activation
"Accrued but unpaid interest"	"Some interest calculation"	`calculateInterest()`	Domain concept invisible in code
"Grace period"	"Extra time buffer"	`delayDays: 14`	Magic number with no meaning
"Beneficiary designation"	"Who gets the money"	`recipientId: string`	Rich concept reduced to ID reference
"Claims adjudication"	"Process the claim"	`processItem()`	Critical business process hidden

The Translation Tax

What is the Ubiquitous Language?

The Ubiquitous Language is a rigorously defined, shared vocabulary for the domain model that is:

Precise: Terms have specific, agreed-upon meanings. 'Customer' means exactly one thing. If there's ambiguity, we resolve it by refining the language.

Bounded: The language applies within a Bounded Context. In different contexts, the same word may have different meanings—and that's explicitly acknowledged.

Evolving: As understanding of the domain deepens, the language evolves. New terms are introduced. Existing terms are refined. Outdated terms are retired.

Executable: The language is directly reflected in code. Class names, method names, variable names all use the Ubiquitous Language. The code IS the model, expressed in the language.

Properties of a Good Ubiquitous Language

•Domain Expert Readable — Domain experts can look at class names and method signatures and recognize their concepts. 'Yes, that's how claims work.'
•Developer Usable — The language follows naming conventions that work in code. Names are pronounceable, typeable, and don't conflict with keywords.
•Consistent — The same concept is always referred to by the same term. No synonyms allowed within a context.
•Complete — All significant domain concepts have names. If something is important enough to code, it's important enough to name explicitly.
•Documented — A glossary exists that defines each term, even if informally. New team members can learn the vocabulary.
•Enforced — The team actively corrects language violations. If someone uses the wrong term, they're gently reminded of the correct one.

Language as a First-Class Artifact

The Language in Code

The Goal: A domain expert should be able to look at the domain layer code and say: "Yes, I can see my concepts here. I recognize this. This is how our business works."

This is possible when we:

Name classes after domain concepts
Name methods after domain operations
Name parameters and variables after domain terms
Organize code to mirror domain structure

poor-language.ts
Poor Language
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// ❌ Technical jargon, no domain language
 
class DataHandler {
    processItem(obj: any, flag: boolean): void {
        if (flag && obj.status === 1) {
            obj.status = 2;
            this.calculateValue(obj);
            this.save(obj);
        }
    }
    
    calculateValue(obj: any): void {
        obj.val = obj.items.reduce(
            (sum, i) => sum + i.amt * i.qty, 0
        );
    }
}
 
class RecordProcessor {
    handleEvent(data: Record<string, any>): void {
        const record = this.lookup(data.id);
        if (record.type === 'A') {
            this.doActionA(record);
        } else {
            this.doActionB(record);
        }
    }
}
 
// What domain is this? What business process?
// Impossible to tell without context
// Domain experts cannot verify correctness

ubiquitous-language.ts
Ubiquitous Language
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// ✅ Domain language expressed in code
 
class Order {
    confirm(): ConfirmationResult {
        if (!this.canBeConfirmed()) {
            return ConfirmationResult.failed(
                'Order cannot be confirmed'
            );
        }
        
        this.status = OrderStatus.Confirmed;
        this.calculateOrderTotal();
        this.raise(new OrderConfirmed(this.id));
        
        return ConfirmationResult.success();
    }
    
    private calculateOrderTotal(): void {
        this.total = this.orderLines.reduce(
            (sum, line) => sum.add(line.lineTotal),
            Money.zero(this.currency)
        );
    }
}
 
class ClaimsAdjudicator {
    adjudicate(claim: Claim): AdjudicationResult {
        if (claim.isWithinCoveragePeriod()) {
            return this.processApprovedClaim(claim);
        } else {
            return this.rejectForExpiredCoverage(claim);
        }
    }
}
 
// Insurance domain? Order processing?
// Immediately clear from the code
// Domain experts can review and validate

Notice the difference:

In the poor example, we have 'handlers', 'processors', 'items', 'records', 'flags'. These are implementation concepts that reveal nothing about the domain.

In the Ubiquitous Language example, we have 'Orders', 'OrderLines', 'Claims', 'Adjudication', 'Coverage Periods'. These are domain concepts that a business expert would recognize.

Building the Ubiquitous Language

The Process:

1. Listen Actively to Domain Experts

2. Question Ambiguities

3. Model in Language

4. Validate with Code

5. Refine Continuously

As you learn more, update the language. Rename classes. Split concepts that turned out to be multiple things. Merge concepts that were unnecessarily separated.

Converting Mermaid diagram...

Techniques for Language Discovery

•Event Storming — Collaborative workshop where domain experts and developers map out domain events on sticky notes, naturally surfacing the vocabulary.
•Example Mapping — Start with concrete examples of business scenarios. The terms used to describe examples become the language.
•Glossary Maintenance — Keep a living glossary document that defines each term. Update it in every session where language is discussed.
•Code Reviews with Domain Experts — Periodically have domain experts review domain layer code. Their confusion or corrections refine the language.
•Write Tests in Domain Language — Test names and test data that use domain terms validate that the language works in practice.

Language Boundaries and Contexts

A critical insight: the Ubiquitous Language is scoped to a Bounded Context. This is liberating rather than limiting.

In an enterprise, different departments legitimately use the same words to mean different things:

Sales Context: 'Customer' is a prospect or active buyer with purchasing history, preferences, and negotiated prices
Support Context: 'Customer' is a ticket requester with support history and SLA tier
Shipping Context: 'Customer' is simply a delivery recipient with an address

Attempting to create a single, enterprise-wide definition of 'Customer' that satisfies all contexts creates a bloated abstraction that serves no one well.

Context-Specific Languages:

This context-scoping has practical implications for code organization:

context-languages.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
// Each Bounded Context has its own Ubiquitous Language
// and therefore its own domain model
 
// ═══════════════════════════════════════════════════════
// SALES CONTEXT - Language focuses on buying behavior
// ═══════════════════════════════════════════════════════
namespace SalesContext {
    // In Sales, we call them "Customers"
    export class Customer {
        constructor(
            public readonly customerId: CustomerId,
            public readonly accountManager: AccountManager,
            public readonly pricingTier: PricingTier,
            public readonly purchaseHistory: PurchaseHistory,
            public readonly discountAgreements: DiscountAgreement[]
        ) {}
        
        // Sales language: "placing an order"
        placeOrder(items: OrderRequest[]): Order {
            const applicableDiscounts = this.findApplicableDiscounts(items);
            return Order.create(this.customerId, items, applicableDiscounts);
        }
        
        // Sales language: "qualify for tier upgrade"
        qualifiesForTierUpgrade(): boolean {
            return this.purchaseHistory.totalSpend()
                .exceeds(this.pricingTier.upgradeThreshold);
        }
    }
}
 
// ═══════════════════════════════════════════════════════
// SUPPORT CONTEXT - Language focuses on issue resolution
// ═══════════════════════════════════════════════════════
namespace SupportContext {
    // In Support, we call them "Requesters" (different concept!)
    export class Requester {
        constructor(
            public readonly requesterId: RequesterId,
            public readonly externalCustomerId: string,  // Link to Sales
            public readonly supportPlan: SupportPlan,
            public readonly ticketHistory: TicketHistory,
            public readonly preferredChannel: CommunicationChannel
        ) {}
        
        // Support language: "opening a ticket"
        openTicket(issue: IssueDescription): SupportTicket {
            const priority = this.supportPlan.determinePriority(issue);
            return SupportTicket.create(
                this.requesterId,
                issue,
                priority,
                this.supportPlan.slaDeadline(priority)
            );
        }
        
        // Support language: "escalation eligibility"
        canEscalate(ticket: SupportTicket): boolean {
            return this.supportPlan.allowsEscalation() &&
                   ticket.hasExceededInitialResponseTime();
        }
    }
}
 
// ═══════════════════════════════════════════════════════  
// SHIPPING CONTEXT - Language focuses on delivery
// ═══════════════════════════════════════════════════════
namespace ShippingContext {
    // In Shipping, we call them "Recipients" (different again!)
    export class Recipient {
        constructor(
            public readonly recipientId: RecipientId,
            public readonly externalCustomerId: string,
            public readonly deliveryAddress: DeliveryAddress,
            public readonly deliveryPreferences: DeliveryPreferences,
            public readonly accessInstructions: string | null
        ) {}
        
        // Shipping language: "can receive delivery"
        canReceiveDeliveryOn(date: Date): boolean {
            return this.deliveryPreferences.acceptsDeliveriesOn(date);
        }
        
        // Shipping language: "requires signature"
        requiresSignature(): boolean {
            return this.deliveryPreferences.signatureRequired;
        }
    }
}

Same Person, Different Concepts

Language Degradation and Revival

Signs of Language Degradation:

Warning Signs

•Synonym Proliferation — The same concept is called 'customer', 'user', 'client', and 'account' in different parts of the code.
•Constant Translation — Developers regularly translate between 'what the business calls it' and 'what the code calls it'.
•Onboarding Confusion — New team members are frequently confused about terminology and receive conflicting explanations.
•Meeting Clarifications — Discussions frequently pause for clarification: 'Wait, do you mean X-type customer or Y-type customer?'
•Code-Documentation Mismatch — Documentation uses different terms than the code, requiring mental mapping.
•Domain Expert Alienation — Domain experts stop reading code or tests because they can't recognize their concepts.

Reviving the Language:

When you recognize degradation, explicit effort is needed to restore the language:

1. Audit the Codebase: Identify all the terms currently in use. Group synonyms. Note inconsistencies.

2. Reconvene with Domain Experts: Have conversations about the current state. Which terms are correct? Which were always wrong? Which have become obsolete?

3. Create a Canonical Glossary: Document the agreed-upon terms with precise definitions. Make it accessible to the whole team.

4. Refactor Systematically: Rename classes, methods, variables to align with the canonical language. This is not optional—misnamed code is incorrect code.

5. Enforce Going Forward: Code reviews should check for language compliance. Lint rules can catch some violations. New team members should learn the glossary early.

Language Hygiene

Practical Guidelines for Language Use

Here are actionable guidelines for maintaining a strong Ubiquitous Language in your projects:

Ubiquitous Language Guidelines
Guideline	Do	Don't
Class Names	Use exact domain nouns: `Policy`, `Claim`, `Beneficiary`	Use technical patterns: `PolicyManager`, `ClaimHandler`
Method Names	Use domain verbs: `reinstate()`, `adjudicate()`, `underwrite()`	Use generic verbs: `process()`, `handle()`, `execute()`
Variable Names	Use domain terms: `coverageLimit`, `gracePeriod`	Use abbreviations or generic names: `cl`, `gp`, `val`
Parameters	Name for meaning: `effectiveDate: Date`	Name for type: `date: Date`
Boolean Methods	Domain predicates: `isWithinGracePeriod()`	Technical checks: `checkFlag()`
Exceptions	Domain exceptions: `GracePeriodExpired`	Generic exceptions: `InvalidStateException`
Comments	Explain why (domain reasoning)	Explain what (if code is clear, unneeded)

naming-examples.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
// ═══════════════════════════════════════════════════════
// NAMING IN THE UBIQUITOUS LANGUAGE
// ═══════════════════════════════════════════════════════
 
// ❌ Technical/Generic Naming
class AccountProcessor {
    handleRequest(req: Request): Response {
        const record = this.fetch(req.id);
        if (record.status === 'A') {
            return this.processActiveRecord(record);
        }
        throw new InvalidOperationException('Bad status');
    }
}
 
// ✅ Ubiquitous Language Naming
class PolicyUnderwriter {
    evaluateApplication(application: InsuranceApplication): UnderwritingDecision {
        const applicant = this.retrieveApplicant(application.applicantId);
        if (applicant.meetsEligibilityCriteria()) {
            return this.underwrite(application, applicant);
        }
        throw new ApplicantIneligible(applicant.id, applicant.ineligibilityReason());
    }
}
 
// ═══════════════════════════════════════════════════════
// EXCEPTION NAMING
// ═══════════════════════════════════════════════════════
 
// ❌ Technical Exception
class InvalidStateException extends Error {}
class ProcessingFailedException extends Error {}
 
// ✅ Domain Exception
class PolicyLapsed extends Error {
    constructor(public readonly policyId: PolicyId, public readonly lapseDate: Date) {
        super(`Policy ${policyId} lapsed on ${lapseDate.toISOString()}`);
    }
}
 
class InsufficientCoverage extends Error {
    constructor(
        public readonly claimedAmount: Money,
        public readonly availableCoverage: Money
    ) {
        super(`Claimed ${claimedAmount} exceeds coverage ${availableCoverage}`);
    }
}
 
// ═══════════════════════════════════════════════════════
// METHOD/PREDICATE NAMING
// ═══════════════════════════════════════════════════════
 
// ❌ Technical Predicates
class Account {
    isValid(): boolean { /* ... */ }
    hasStatus(status: string): boolean { /* ... */ }
    checkAmount(amount: number): boolean { /* ... */ }
}
 
// ✅ Domain Predicates
class InsurancePolicy {
    isInGoodStanding(): boolean { /* premium paid, no pending issues */ }
    allowsClaim(claimType: ClaimType): boolean { /* coverage includes type */ }
    isWithinCoveragePeriod(date: Date): boolean { /* date falls in active period */ }
    exceedsCoverageLimit(amount: Money): boolean { /* amount vs remaining limit */ }
}

Summary: The Power of Shared Language

Key Takeaways

•Translation is expensive — Every time developers translate domain concepts into technical jargon, information is lost and errors creep in.
•The language must be ubiquitous — Used in conversations, documentation, code, and tests. One language, everywhere.
•Code reflects language — Class names, method names, and exceptions should use domain vocabulary. Domain experts should recognize their concepts in code.
•Language is bounded — The Ubiquitous Language applies within a Bounded Context. Different contexts may use different terms for similar concepts.
•Language evolves — As understanding deepens, the language is refined. This triggers refactoring, not just documentation updates.
•Language requires maintenance — Without active care, languages degrade. Regular attention prevents painful restoration later.

What's Next:

Page Complete

3 / 4