Skip to content
←Domain-Driven Design

// Domain-Driven Design · 01

Ubiquitous Language

Lost in translationleads toper contextOne shared language

Experts and code use the same words, with the same meaning.

How it fits together

Ubiquitous Language structureClaims context«client»Claims handlersays "settle the claim"«client»Developerwrites Settle()Claims glossaryClaim, Policy, ExcessSettle: pay the claimClaimSettle(amount)Policy, Excess«client»Claim testsSettle_AboveExcess_PaysOut«record»ClaimSettledsame word in events1 agree terms1 agree terms2 class names2 test names3 raises
uses / callscreates· numbered steps replay in order
  • Claims handler uses / calls Claims glossary (1 agree terms)
  • Developer uses / calls Claims glossary (1 agree terms)
  • Claims glossary creates Claim (2 class names)
  • Claims glossary creates Claim tests (2 test names)
  • Claim creates ClaimSettled (3 raises)

Spot it

  • Devs say Ticket when experts say Claim
  • Tickets, code and meetings use different names
  • Experts cannot read the model or the tests

It costs

Ongoing effort: renames ripple through code, schema and APIs as the language sharpens.

Go deeperThe full explanation and what to ask for · 1 min readExpand

A Domain-Driven Design practice: developers and domain experts agree on one vocabulary and use it everywhere, in conversation, tickets, class and method names, tests and events. When the expert says "settle the claim", there is a Settle method on Claim and a ClaimSettled event, not ProcessTicket with status 3.

The language is ubiquitous inside one bounded context, not across the company. "Policy" in Underwriting and "Policy" in Billing may mean different things, and that is fine as long as each context is consistent. A glossary helps, but the code is the real record, and both change when a conversation reveals a better word.

Watch for translation in people's heads: "the claim is the Ticket table" is a tax paid in every conversation and a source of bugs. When NOT to invest heavily: generic or CRUD areas with little domain to model.

Ask for it

  • ubiquitous language
  • domain expert
  • glossary
  • bounded context
  • intention-revealing names

Build a glossary for the Claims context with two claims handlers: 15 to 20 terms (Claim, Policy, Excess, Settlement) with one-line definitions, then rename code, tables, events and tests to match, e.g. Ticket to Claim and status 3 to Settled. List words that mean something else in Billing.

Connects to