Vocabulary Collision

A marketplace reports 41,000, 118,000 and 76,000 "active sellers" on three dashboards, each correct under its own rule: paid in 30 days, edited a listing in 90 days, logged in within 60 days. A fee-waiver job reads the search service's number and waives fees for roughly 77,000 sellers who were never meant to qualify. A vocabulary collision is one word carrying several meanings across a boundary, and the system works perfectly while doing the wrong thing.

Why it matters

Services exchange data that looks fine: valid type, plausible range, successful response. Because the value passes every technical check, no alert fires. The damage shows at the business level, weeks later, as revenue, compliance or trust. It is anti-pattern territory in the sense that it grows quietly as teams are added: each team defines terms locally, and the collision count rises with the number of teams.

Implementation patterns

• Names that carry the rule: seller_paid_30d instead of active_seller.
• One owner per definition: the service that computes it. Consumers read it and may not redefine it.
• Definition in the contract: the API schema description states the window, the event counted and the time zone, and a contract test fails when the definition changes.
• A glossary linked to owners: each term points to its service and a contact; edits to a definition require a review that lists consumers.
• Versioned changes: introduce seller_paid_30d_v2, run both for a cycle and retire the old one.
• Audit for collisions: search the codebase and dashboards for the same noun with different queries; start with the five terms in the most executive reports.

Industry example

This is an archetype rather than a single documented incident. A pattern widely reported across organisations is the "customer" with different meanings in sales, billing and support systems, which domain-driven design addresses through bounded contexts, each with its own model, and explicit translation at the borders. Eric Evans described this in Domain-Driven Design (2003) as the reason a single enterprise-wide model fails. The practical lesson is to translate at boundaries instead of forcing one meaning everywhere.

Failure scenarios

• Silent misuse: a job treats 118,000 as 41,000, with an 11-hundred-thousand-dollar bill at month end.
• Hard-coded fix: the team pins 41,000 in the job; the next definition change breaks it again unnoticed.
• Merged reports: a finance report adds counts from two services that define the term differently.
• Migration drift: a new service reuses an old name with a refined meaning, and half the consumers keep the old assumption.
• Dashboard disputes: a quarterly meeting spent arguing which number is right.

Trade-offs

When not to use it

A five-person company working in one room can rely on shared understanding, and a formal glossary is overhead. The discipline pays once different teams own different systems and a value crosses a service boundary, particularly where the value drives money or access.

Interview question

Q: Two teams report different monthly active user numbers and leadership wants one. What do you do?

What a strong answer covers: do not pick a winner first; list each definition with its purpose; name each precisely; decide which, if any, deserves the plain name; assign an owner; publish it in a contract and a glossary; and add a test that fails when the definition changes.

Quick check

Quiz: Why does monitoring fail to catch a vocabulary collision? The call succeeds and the data is valid; only the meaning differs.

Flashcard: What should a field name like seller_paid_30d carry? — The rule: who is counted and over what window.