Part 02 of 16 · Day 1 · ubiquitous language, message contract
Same word, different meaning
Problem and experience
Same word, different meaning
An “application” means something different to the adviser than to risk or the database. If we don't agree on the language, a message is just a JSON shape.
Three teams, one word
- Adviserapplication = conversation with the client
- Riskapplication = exposure under assessment
- Databaseapplication_row
Consequence
- Message “Application”everyone reads it differently
- Bug only in production
From practiceWhich term means something different in different teams where you work?
TakeawayThe domain language is the first contract.
What it means
A shared domain language means event and command names come from the speech of people who know the domain.
Why we use it
The most expensive integration bugs come from misunderstandings, not from technology.
When it makes sense
Whenever two teams share messages.
Where it breaks
- Naming an event after a table or a screen.
- Using one word for two things.
- Adopting a vendor's system names without translation.
Imagine
For the adviser an “application” is a conversation with the client; for Risk it is only the submitted MortgageApplicationSubmitted. It helps when the message says so clearly.
First we agree on the words, then on the format.
Principle, application and exercise
What belongs inside and what goes out
Inside a service we speak our own way. Outwards we publish a stable, named and versioned contract.
Anti-vzor
- Domain eventIncomeChanged
- Broker
- Risk Servicebreaks after refactoring
Translation
- Domain eventApplicationSubmitted
- Translationanti-corruption
- Integration eventMortgageApplicationSubmitted v1
- Risk Service
Trade-offThe extra translation is work and one more place to maintain. It protects us from every refactoring breaking other services.
TakeawayWe can change the internal model. Not the public contract.
What it means
Domain events describe what happened inside an aggregate. Integration events are public messages with a fixed shape and version.
Why we use it
When other services subscribe to internal events, every refactoring breaks them and the services become coupled.
When it makes sense
As soon as an event leaves the service boundary.
Where it breaks
- Publishing internal events to the broker.
- An integration event shaped like a database table.
- Changing a contract without versioning.
Imagine
The calculator renames the income field. Risk Service keeps receiving the same MortgageApplicationSubmitted and notices nothing.
What we share with the world must be kept more stable than what we have at home.
Training for your team
Would you like this training for your team?
We run the training on your code and your domain problem. We agree the scope, dates and format with you.
Discuss the training →