Northwind buys from five countries and sells eight coffees, so three of them are Ethiopian. Each of those pages wants to say something about where the coffee comes from.
Write that in three places and it is wrong in three places the day a detail changes. Write it once and point at it, and every page corrects itself. Put like that the answer is obvious — which is exactly why it is worth being careful about when it is not, because a coffee’s photograph in part 4 was written inline, and that was also right.
The question is not the one you expect
The instinct is to reason about storage. References avoid duplication, duplication wastes space, therefore reference everything. That is a database argument, and it gives the wrong answer often enough to be worth putting down.
The useful question is about the thing itself:
Does it have an independent life? Is it shared, is it separately publishable, and is it worth finding in the library on its own?
Three questions, and they tend to agree with each other.
A coffee’s photograph: not shared, has no publishing schedule of its own, and nobody will ever hunt for it by name. Three noes — inline.
An origin: named by several coffees, correcting a detail about the region ought to correct it everywhere at once, and it has a page of its own at /origins/ethiopia. Three yeses — a Component that things point at.
The reference field
coffee.origin is a Component field in reference mode, and two settings do the real work:
allowedContractIds— which Contracts a value may point at. Without it, "a reference to an origin" is a reference to anything, and the first person to bind a brew guide there will find nothing in their way.allowedModes— whether an author may write inline here, point at an existing Component, or either. Northwind allows reference only, because inline would defeat the entire purpose of the field.
Constraints like these are worth adding as you go. They are the difference between a model somebody can use confidently and one that needs a person standing next to it.
A reference is a promise about identity, never about availability
This is the part that catches people, and it is worth internalising before it happens to you.
A reference points at a Component. It does not promise that Component is published. The origin might be a draft, or unpublished last week, or withdrawn this morning — and the coffee page is still live, still referencing it, and still has to render.
So the renderer reads the expanded origin through the SDK’s <Resolve>, which renders nothing at all when there is nothing to render:
<Resolve value={content.origin}>
{(origin) => <OriginCard origin={origin} />}
</Resolve>
No card, no gap, no error. The page is a page about a coffee; the origin is an enrichment it works without.
That posture runs right through the Delivery API and it is deliberate: an unresolvable reference reports honestly that it resolves to nothing, rather than inventing a placeholder or failing the whole request. What the page looks like without it is a design question, and it is yours.
The link that is not here yet
There is something obviously missing from this part. The coffee page shows an origin card, and that card does not link to the origin’s own page.
That is deliberate, and the reason is the one from part 3. Nothing in this step knows the origin page’s URL. Building one out of the origin’s name — /origins/ plus a slugified Ethiopia — would work today and would be precisely the mistake internal links exist to prevent: a guess about where a page lives, written in code, with nothing anywhere to detect it going stale.
The right answer needs a way to ask what path a Component is published at. That query arrives in part 8, and the link lands with it. A part that ends with a known gap and names the part that closes it is worth more than one that ends with a plausible guess.
Where this leaves us
Five origins, eight coffees pointing at them, and one card that is not yet a link.
What Northwind still cannot answer is "show me the light roasts". Next: closed sets of values that people filter by, and why they are not text fields.
