Everything so far has been about pages. A coffee is not a page. It is a thing Northwind sells, which happens to have a page — and which will later also appear in a list, a cross-sell rail, a search result and a sitemap, none of which are that page.
That distinction is the whole of this part. Model the coffee, and let the page be one of the places it turns up.
The Contract
Northwind’s coffee Contract, with the interesting column on the right:
| Field | Type | Modifiers |
|---|---|---|
| Name | Short text | mandatory, localizable |
| Producer | Short text | — |
| Description | Rich text | localizable, personalizable |
| Tasting notes | Short text | localizable, enumerable |
| Price, Bag size | Number | — |
| Image | Component | written inline |
| Origin | Component | (part 5) |
| Roast, Process | Category | (part 6) |
Four of the five field modifiers are on this one Contract, and each is there for a reason worth being able to state out loud.
Mandatory is a promise about publishing
name is mandatory, so a coffee without one cannot be published. Not "is highlighted in red" — cannot be published. That is a rule the publish step enforces, which is exactly why it is worth using sparingly: every mandatory field is a way for a colleague to be blocked at five to five.
Localizable is a decision about axes, not about languages
Marking a field localizable says this value can legitimately differ by language. Northwind has one language, so today it differs by nothing at all.
The thinking is in what is not marked. producer is not localizable. A farm’s name is a proper noun — Finca El Injerto is Finca El Injerto in every language, and a field that offers to translate it is inviting somebody to try.
Localizable does not mean "text". It means "text that legitimately differs by language."
Part 15 is where this pays for itself, and it can only pay for itself because the decision was made here, while it cost nothing and meant nothing.
Enumerable is cardinality, and cardinality is a modifier
tasting-notes holds several values — blackcurrant, cocoa, a long finish. In a lot of systems that would be a different field type: a "list of strings" sitting beside a "string".
Here it is the same field type with isEnumerable set. That sounds like a detail and is not, because it means cardinality composes with everything else instead of multiplying the type list. A localizable enumerable field is one translated list per language, and nobody had to invent a LocalizableListOfShortText for it to exist.
It does leave you a shape to get right, and it is worth getting right on paper before the compiled schema tells you off:
// One list per locale — right.
{ default: ["blackcurrant", "cocoa"], locales: { fr: ["cassis", "cacao"] } }
// A list of separately-translated strings — wrong.
[{ default: "blackcurrant", locales: {} }, { default: "cocoa", locales: {} }]
The second one looks reasonable until a language wants four notes where English has three, at which point it cannot express the thing at all. Localizable wraps enumerable, never the other way round.
Personalizable, doing absolutely nothing
description is marked personalizable. There are no audiences in this organization, so it behaves exactly like an ordinary rich-text field — same editor, same delivered value, no visible difference of any kind.
It stays that way until part 16. The reasoning is the same as localizable: the axis is cheap to declare now and expensive to retrofit, and you generally know which fields are candidates long before you know whether you will use them.
An image is a Contract, not a Blob field
The obvious way to put a photograph on a coffee is a Blob field. Northwind does not do that. There is a small image Contract instead:
| Field | Type | Notes |
|---|---|---|
| File | Blob | mandatory — the bytes |
| Alt text | Short text | mandatory, localizable |
The reason is the second row. A Blob is bytes, and bytes cannot be described — there is nowhere on a bare Blob field to put the one thing every image on a public website is required to have.
Making alt text mandatory on a Contract turns it from a good intention into a publishing rule. Making it localizable means it gets translated with everything else, rather than being the one English string left on an otherwise French page.
Inline, this time
That image is written inline on each coffee — the value lives inside the coffee’s own document rather than pointing at something in the library.
That is right here because no two coffees share a photograph. There is no version of the image several coffees point at, nothing to correct in one place, and nobody who will ever go looking for one in the library on its own.
Part 5 asks the identical question about a coffee’s origin and reaches the opposite answer, for the opposite reasons. The two side by side are the lesson; neither is worth much alone.
A node that is not a page
The coffee pages live at /coffees/<slug>, which means there is a node at /coffees for them to hang from. That node has no payload — it is structure, not a page, and its own path returns a 404 until part 8 gives it an index.
That is a legitimate state rather than a gap. The tree is the site’s shape, and not every level of a shape is somewhere a visitor can stand.
The types file we are going to delete
This is the first part where untyped content genuinely hurts. component.content arrives as an object, the renderer wants content.name, and TypeScript has no idea whether that field exists.
So the sample gains src/lib/cmsTypes.ts: a hand-written module restating each Contract as a TypeScript interface. It works. It is also, from the moment it is written, capable of being silently wrong — rename a field in the CMS and this file keeps compiling against the old name, because nothing connects the two.
We are going to live with that for nine parts and then delete it in part 13. Feeling the problem first is the point; a generated types file is not very interesting until you have maintained a hand-written one.
About the pictures
Every image in the sample repository is produced by a generator script that ships with it. That is a licensing decision rather than an aesthetic one: the repository is public domain and exists to be copied, so a photograph found online would quietly poison the licence for everyone downstream. Your own coffees will look considerably better.
Where this leaves us
A coffee, a page for it, and two modifiers doing nothing yet.
Next: three of Northwind’s coffees come from Ethiopia, which raises the question this model has so far avoided — when should two things share content, and when should each keep its own?
