Domain glossary

One definition per term#

The glossary is where your team writes down what its words mean. Each term has exactly one definition within its scope, and every requirement, scenario and context purpose that uses the term links back to it. When a definition changes, every place that uses the word points at the new meaning.

This is the ubiquitous language from Domain-Driven Design, stored as data instead of in people's heads. It matters even more with agents in the loop: an agent that reads reservation in a requirement can look up exactly what Northwind means by it before it writes code or proposes a change.

Term fields#

Here is one of Northwind's Orders terms:

Context-scoped and shared terms#

Most terms belong to one context. Scoping a term keeps its definition next to the rules that depend on it, and lets two contexts use the same word for different things without a fight.

Make a term Shared only when it means the same thing in every context. At Northwind, Customer is shared: the person with an account in Identity, who places orders, pays and receives notifications. Changing a shared term affects every context at once, so keep that list short.

The same word in two contexts#

At Northwind, Order means something different on each side of the Orders to Fulfilment relationship:

Both definitions are correct inside their own context. The glossary holds both, each scoped, and a requirement in Fulfilment links to the Fulfilment meaning. If the overlap keeps causing confusion in conversation, rename one side, for example to Shipment request in Fulfilment, and list Order as an alias to avoid there.

Aliases to avoid#

Aliases record the words your team agreed not to use. Northwind's Orders context says Cart and lists basket and bag as aliases to avoid. When a proposal uses an avoided alias in a requirement or scenario, the review shows a hint with the preferred term, so drift gets caught before anyone approves it.

Add an alias the first time you see a second word for the same idea in a review thread. It costs one line and saves the same argument next month.

Automatic linking#

SpecsGraph links glossary terms wherever they appear in requirement statements, scenario steps and context purposes. A link resolves in the context of the text around it: in an Orders requirement, Order links to the Orders definition, and in a Fulfilment scenario it links to the Fulfilment one. Hover a linked term to read the definition without leaving the page.

The glossary is also published to specsgraph/glossary.md with every term and its definition, so the vocabulary sits in the repository next to the code that uses it.

Propose a change to a term#

Terms change through proposals, like everything else in the graph. When you add a term, sharpen a definition or change its scope, reviewers see the old and new text side by side along with every requirement that links to the term. A small wording change can reach many requirements, and the review makes that visible before it is approved. Removing a term works the same way: the diff lists every requirement that still links to it.

Record the reason for a meaningful change in the decision log, for example when Northwind decided that a reservation expires after 15 minutes idle rather than when the browser session ends.

How agents use the glossary#

Agents read terms with list_glossary_terms, usually filtered to the context they are working in, and suggest new or refined terms with propose_term. Two habits help:

• Ask the agent to read the context's terms before it drafts requirements, so it writes Reservation and not stock lock.
• When an agent introduces a new concept, have it propose the glossary term in the same proposal as the requirement that needs it.

More habits like these are in Working well with agents.

Next steps#

• Requirements and scenarios to put your terms to work.
• Actors to name the people and systems your scenarios talk about.
• Proposals and reviews to see how term changes get approved.