# Settle what "completed order" means before writing a line of SQL

> A WHERE clause silently picks one meaning, and an FDE on a client site pays for the wrong one in lost trust.

Original: https://fdetimes.net/en/guides/business-glossary-before-writing-code/

Picture your second week at a retail company. You demo a dashboard called "Completed orders this month". The head of sales nods; the chief accountant frowns, because the figure is higher than her books. There is no bug in the pipeline. The two of them are simply counting different things under the same name.

Martin Fowler describes this as something that recurs project after project: polysemous words such as "Customer" or "Product" cause endless confusion. For an engineer building internal products, the cost is a few meetings.

For an FDE sitting at a client's site, the cost is trust: once people have seen one wrong number, they will read every number after it with suspicion.

The reason to deal with this before writing code is simple. Fowler writes that software does not cope well with ambiguity. People can say "completed order" and still understand each other in context. A `WHERE status = 'completed'` clause has to pick exactly one meaning, and it picks quietly, without telling anyone.

## Why does one word have three meanings?

Alberto Brandolini, the creator of Event Storming, says plainly that terminology is inherently ambiguous: each person interprets the same word in their own way, because each department has a different perspective and different needs.

A post on the Codurance blog gives an example from inside a single company: a sales expert and an accounting expert can attach two different concepts to the same word.

Fowler makes a point that is more worth remembering. The boundaries between business contexts are usually not set by technology but mainly by human culture: which groups work together, which department is responsible for what. Each context may have an entirely different model of the same concept.

So your goal is not to win an argument about the "right" meaning. Three Dots Labs puts it clearly: the same word meaning different things in different contexts is normal, as long as the boundaries between the contexts are clearly drawn.

The FDE's job is to bring each meaning into view, give it a name and record where it applies.

**Key point:** Do not force the whole company onto one meaning; give each meaning a name of its own.

## One word, "completed", three numbers

Back to the hypothetical retail company. Sales treats an order as completed when the customer's payment succeeds. The warehouse treats it as completed when the goods have been scanned out and handed to the carrier. Accounting treats it as completed only when the customer has received the goods, the return window has passed and there has been no refund.

Put numbers on it to make it concrete: suppose this month has 1,000 orders with successful payment, 920 shipped from the warehouse, and 850 past the return window without a refund. Your dashboard counts by the payment status column, so it shows 1,000. Accounting records 850. That gap of 150 orders is not a data error; it is a definition error.

Now add a customer service agent that answers "is my order completed?". If the agent reads the word in the sales sense, it will say "yes" for an order still sitting in the warehouse. Same definition error, but this time it goes straight to the end customer.

The settled glossary for this example might look like this:

| Canonical name | Owning department | Measurable rule | Data field | Edge case settled |
|---|---|---|---|---|
| Paid order | Sales | Payment transaction succeeded | `payment_status = 'captured'` | When does a cash-on-delivery order count? |
| Shipped order | Warehouse | Has an outbound warehouse scan | `shipped_at IS NOT NULL` | Partially delivered orders |
| Revenue-settled order | Accounting | Delivered, past return window, no refund | `settled_at IS NOT NULL` | Orders exchanged for a different product |

Note that the table deliberately no longer contains the word "completed". From here on, "completed" on its own may not appear in code, metric names or the agent's prompt.

## Settling the glossary in five steps

The first step is collecting the words. Read tickets, table names, column names, the Excel files the client sends and meeting notes, then mark the nouns that appear most often. The most familiar words, such as "customer", "order" and "product", are usually the most dangerous, just as Fowler warns.

Step two: interview each domain expert separately, as Codurance advises. Do not ask "what does completed mean?", because everyone will answer in generalities. Ask with edge cases: "Does a half-refunded order count?", "If a customer swaps sizes, what does the original order count as?". These cases are what expose the definitions people actually use.

Step three: bring the departments into the same session. Three Dots Labs considers Event Storming one of the best ways to discover and align vocabulary between developers and stakeholders.

When events such as "customer pays", "goods leave the warehouse" and "return window expires" are stuck up in time order, everyone can see where their own "completed" sits on that line.

Step four: name each meaning and assign an owner. Each meaning gets its own name, a department responsible when the definition needs to change, and a rule a machine can run. "Order is fine" is not a definition. "Has `settled_at` and no refund record" is.

Step five: put the glossary into the system. Eric Evans calls this destination the ubiquitous language: a shared, rigorous language between developers and business users, used identically in meetings and in code. Variable names, column names, metric names and the agent's tool descriptions must all use the canonical names.

Tools help at this step. dbt's semantic layer lets you define a metric once at the modelling layer so that every business unit shares the same definition, whatever tool they use.

When a definition changes, the change propagates to everywhere that calls it. At Palantir, the Ontology describes the client organisation in terms of objects, properties and links. But tools only store definitions; choosing which definition is still a matter between people.

## The mistakes that kill a glossary early

The most common mistake is picking the meaning of whoever talks loudest, or of the department paying for the project. The other department will not argue in the meeting; it will quietly keep its own Excel file, and your system becomes the second system nobody trusts.

The second mistake is a glossary that lives on a wiki and never reaches the code. If the column is still called `is_completed`, a new engineer six months later will use it in whatever sense they guess.

The third mistake is freezing the glossary. Fowler stresses that the language must evolve with the team's understanding of the domain, so record the date each term was settled and who approved it, and reopen it when the client's processes change.

## Turning this skill into a career advantage

When reading FDE job descriptions, look for phrases such as "domain modeling", "ontology", "semantic layer" or "work with business stakeholders". They signal that the company needs exactly this skill.

On your CV, do not write "good communication with clients". Write a line with a concrete result, such as having settled a set of metric definitions with three departments and eliminated the gap between the dashboard and the accounting books.

In interviews, have a story ready about a term that made two departments misunderstand each other: how you discovered it, which edge cases you asked about, and where the final definition lives in the system. A story like that shows you can work with both data and people, which is exactly what the role demands.

## Exercise: one status column, one afternoon

Open an orders or customers table you are working on, run `SELECT DISTINCT` on the status column and list every value it contains. For each value, write an edge-case question such as "which value does a partially refunded order get?".

Take that list to people in two different departments, then fill in the results in a five-column table like the example above. Wherever the two answers differ is the first row of your glossary.

Wrong code can be fixed in an afternoon. A misunderstood word that has already spread into every table, every report and every agent answer has to be fixed in the client's head too, so settle its meaning before you type the first `WHERE`.

**Try this week:**

- Pick the three words that appear most often in the tickets or table names of your current project, ask two people from two different departments separately what each word means, and note where their answers differ.
- For each word, write two edge-case questions (partially refunded order, customer exchange) and go back and ask them.
- Rename one ambiguous metric in the code or dashboard so its name states which meaning it measures.

## Sources

- [Bounded Context (Martin Fowler)](https://martinfowler.com/bliki/BoundedContext.html)

- [Ubiquitous Language (Martin Fowler)](https://martinfowler.com/bliki/UbiquitousLanguage.html)

- [Alberto Brandolini on Domain-Driven Design and EventStorming (codecentric)](https://www.codecentric.de/en/knowledge-hub/blog/alberto-brandolini-domain-driven-design-eventstorming)

- [Talk to the business (Codurance)](https://codurance.com/2015/10/26/Talk-to-the-business/)

- [Ubiquitous Language (Three Dots Labs Academy)](https://academy.threedots.tech/knowledge/ubiquitous-language/)

- [dbt Semantic Layer (dbt Docs)](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-semantic-layer)

- [Ontology overview (Palantir Foundry docs)](https://www.palantir.com/docs/foundry/ontology/overview/)