Ubiquitous Language

A single vocabulary to speak, code, document — eliminate the implicit translations between business and tech that are the primary source of semantic bugs.

Problem

In an EDI spec meeting, the domain expert says "when we invoice, we generate the invoice". The developer hears "create an Invoice in the DB". The tester hears "emit an EDIFACT INVOIC". The integration architect hears "publish the InvoiceIssued event". Four silent translations, four implementations not covering the same scope. In production we discover that "to invoice" actually means: create in DB, validate, Factur-X sign, send via AS4, archive 10 years, and notify the client. Six things, one word. The word does not carry the semantics.

Forces

• The business uses polysemous words. "Invoice" = document, process, event, legal act, accounting entry — depending on context.
• Developers translate in their head. If the translation is implicit, two developers translate differently.
• Code and documentation diverge. The spec says "invoice", the code says Bill, the event says InvoiceCreated, the partner says INVOIC. Four vocabularies.
• Senior business expertise disappears. The sole expert who knew what "close the invoice" meant moves roles. Without a written glossary, knowledge evaporates.

Solution

Build with the business an ubiquitous glossary per bounded context. Each term receives: a precise definition, an example, a counter-example ("not to be confused with..."), the external synonym (EDIFACT, X12, partner) and the code mapping. The glossary is git-versioned, in the context's repo, next to the code. The source code uses glossary terms in class, method, event, DB table names. Meeting names use the same terms. PRs are reviewed against this criterion.

Invoicing context — ubiquitous glossary:

  Invoice              ≠ Bill ≠ Receipt ≠ Statement
  IssuedAt             — supplier-side issuance timestamp
  ReceivedAt           — hub-side reception timestamp
  CreditTerm           — days until due date
  Debtor               — entity owing payment
  Creditor             — entity owed payment
  PaymentTerms         — terms (net 90, 2% discount at 10 days...)
  InvoiceLine          — invoice line (never just "line")
  TotalAmountExclVAT   — net total
  TotalAmountInclVAT   — gross total (incl. tax)

  Verbs:
  - "invoice"  → IssueInvoice (command)
  - "send"     → SendInvoice  (transport action)
  - "deliver"  → DeliverInvoice (debtor-side reception)
  - "collect"  → CollectPayment (settlement)

EDI implementation

Concrete case: an EDI team writes its "B2B Invoicing" context glossary: "Issue an invoice" = create the DB record & assign a sequential invoice number; "Send an invoice" = transmit to the partner via AS2/AS4; "Deliver an invoice" = CTC transmission to the regulated tax platform (Chorus Pro, PEPPOL); "Collect" = receive payment. Kafka events become InvoiceIssued, InvoiceSent, InvoiceDelivered, PaymentCollected. Partner interfaces (EDIFACT INVOIC, X12 810) are mapped in the glossary appendix. Same for the "Hospital" context: "Patient" ≠ "Visitor" ≠ "Beneficiary" ≠ "Person" — each with its precise scope.

Anti-patterns

• Glossary imposed top-down by tech. Without the business, terms are not adopted and the code uses an isolated language.
• Unified glossary across the whole organisation. "One definition of Customer for the group": doomed. One glossary per bounded context, translators at boundaries.
• Glossary sleeping in Confluence. If not in the code repo and PR-reviewed, it drifts from the code in six months. Keep it next to code (markdown).
• Ambiguous words tolerated "because everyone knows". "Everyone" is the retiring expert. Force the written definition.

Related patterns

• Bounded Context — each context has its own glossary.
• Anti-Corruption Layer — the ACL translates external glossary to internal.
• Domain Event — event names follow ubiquitous language.
• Aggregate — aggregate names and their methods follow ubiquitous language.

Sources

• Evans E. — Domain-Driven Design, Addison-Wesley 2003. Chap. 2 "Communication and the Use of Language".
• Fowler M. — UbiquitousLanguage (martinfowler.com, 2006). The pedagogical synthesis. martinfowler.com — UbiquitousLanguage
• Vernon V. — Implementing Domain-Driven Design, Addison-Wesley 2013. Chap. 1 and 2 detail the construction of the ubiquitous glossary.
• Brandolini A. — Event Storming. The workshop method to surface ubiquitous language with the business. eventstorming.com
• ddd-crew — Bounded Context Canvas. Tool to document the bounded context and its ubiquitous language. github.com/ddd-crew/bounded-context-canvas