Every coffee has a roast level and a process. Light, Medium, Medium-dark, Dark. Washed, Natural, Honey.
You could model those as short-text fields and be done in a minute. Do that and within a month there is "Med-dark", "medium dark" and "Medium-Dark", none of which match each other, and a filter that quietly returns the wrong three coffees.
What makes something a taxonomy
Two properties, and it needs both.
It is a closed set. Somebody decides what the values are. An author picks from them and cannot quietly invent a new one — which is a feature, even though it will occasionally be the thing standing between a colleague and going home.
People filter by it. The values are not merely displayed, they are selected. That is what makes consistency load-bearing rather than tidy.
A coffee’s tasting notes fail the first test: they are open-ended prose, and a fixed taxonomy of them would be an act of violence against the person writing them. Roast level passes both, comfortably.
Groups the organization owns
So Northwind creates two Category Groups in Settings, roast and process, each with its own categories, and coffee gains a Category field pointing at each.
They live at the organization level rather than on the Contract, which is right: the same roast taxonomy will be wanted by a subscription product, a wholesale sheet and a blog post about roasting, and none of those is a coffee.
One detail worth knowing before you hit it: a Category field’s allowedCategoryGroupIds takes { provider, key } references rather than bare ids. A bare Guid is rejected at save time with a validation error naming the field — which is the settings schema doing its job, and is the kind of refusal that saves you a silently-empty constraint later.
What a category value actually stores
Here is the part worth understanding properly, because it is a deliberate exception to a rule this series has otherwise been strict about.
A category value stores a pointer. It does not store "Light".
And "Light" — the label — is read live at delivery, not frozen into the page when it was published.
Everything else here works the other way round. Publishing freezes a snapshot; editing a draft does not change what visitors are seeing; that is the guarantee which makes publishing mean anything at all. Categories are the exception, on purpose.
Rename a category in Settings and it is renamed everywhere it appears, immediately, with nothing republished.
Which is exactly what you want. If Northwind decides "Medium-dark" should read "Medium/Dark", that is one edit — not a hunt for every coffee carrying it followed by republishing all of them. The label is a display of the group’s current opinion, and the coffee’s own document only ever claimed membership.
It is also the strongest argument for a taxonomy over a text field. A closed set gets to be renamed centrally. Prose does not.
Rendering them is unremarkable, which is the point — the delivered descriptor already carries the label, so nothing has to look one up:
export function CategoryTags({ categories }: { categories: (CategoryDescriptor | undefined)[] }) {
const present = categories.filter(
(c) => c !== undefined && c.resolved !== false && Boolean(c.value),
)
if (present.length === 0) return null
return (
<ul className="mt-4 flex flex-wrap gap-2">
{present.map((c) => (
<li key={c.key} className="rounded-full bg-accent/10 px-3 py-1 text-sm">
{c.value}
</li>
))}
</ul>
)
}
Categories that go away
Because a category value is a pointer, it can point at something that has since been deleted. The delivered descriptor carries a resolved flag saying so, which lets a renderer drop the tag instead of printing an empty chip.
Northwind’s tag component checks it, and yours should. A deleted category is not an error — somebody tidied a taxonomy, which is a thing people do — and the delivery API tells you rather than guessing on your behalf. The alternative designs are both worse: dropping the value silently would hide the tidying from anyone who cared, and refusing to deliver the document would take a whole page down over one chip.
Where this leaves us
Eight categories, two groups, and a coffee that knows which of them it belongs to — which is everything part 8 will need to build a catalogue people can filter.
First, though, Northwind needs more than one coffee. Next: filling the catalogue without typing any of it, and the first place a plan limit shows up.
