Reference and tags
A reference points at an entry in a collection and arrives in the view already loaded. Tags are short labels editors reuse across entries.
Reference
f.ref(() => collection) picks one entry; f.refList(() => collection) picks several. The target is a function, so two collections can point at each other without an import cycle:
import { articles } from "@/smoodly/collections";
// …
fields: {
heading: f.text(),
items: f.refList(() => articles).max(6),
},Editors see a search picker over the collection's entries in the language they are editing, each with its status. A list takes each entry once and stops at .max().
What the view receives
A reference resolves before render, in one batched read per collection, so the view gets the entry as { id, path, fields } rather than an id:
{(items ?? []).filter((a) => a !== null).map((a, i) => (
<ArticleCard key={i} article={a.fields} url={url(a.path!)} locale={locale} />
))}An entry that is unpublished, or was deleted after the page went live, resolves to null, which is why the view filters before it maps. The value's type follows the target collection's fields.
The same rule holds in every read: sections, q lists and single reads, entry pages and globals. How deep a reference goes is the field's decision:
`f.ref(() => authors)``{ id, path, fields }`; the author's own references stay id strings.`.resolve("company")`The named reference of the target resolved one level too.`.resolve()`The whole chain resolved.Types follow the depth, so a.fields.company is an id or a resolved entry as declared. One gap: where the chain meets a cycle it stops at ids, while the type says resolved.
Where references may go
A reference lives at the top level of a section, element or collection schema. It cannot sit inside a list or an object, in a page field, or in an element that richtext embeds, because the reference index addresses fields by their top-level key. A schema that breaks the rule fails at startup with the path.
Tags
f.tags() stores an array of short strings and shows them as chips. Editors type a tag and press Enter, or paste a comma-separated list, and pick from the tags other entries of the collection already use in that language:
tags: f.tags().localized(),Tags are trimmed, and two that differ only in case are one tag: typing design when Design exists reuses it. .min() and .max() count tags. Each entry keeps its own list; there is no tag collection to manage. The starter shows an article's first tag on its card and all of them on the article page.
Next, Conditional fields.