Skip to content
Cloudhal
Menu
News

Connected content: reference and repeater fields arrive in Cloudhal

Cloudhal v0.10.0 lets entries link to each other and hold ordered lists of items, with language fallbacks, delete protection and agent-ready schemas built in.

An event entry, Design systems night, whose venue field and two agenda items link out to separate entries: the place Main hall and the people Elif Kaya and Deniz Aydın. Beside it: Link entries. Don't copy them.
Illustration: Cloudhal
On this page
  1. How collections got here
  2. One event, step by step
  3. Reference fields: link, don't copy
  4. What a reference protects
  5. Repeater fields: lists with a shape
  6. Which one do you need?
  7. Built for agents as much as for people
  8. Changing your mind later
  9. Limits
  10. Getting started
  11. Questions

A content model is only as good as the links between its parts. An event happens at a venue, a talk has speakers, a recipe has ingredients. Until now, Cloudhal could describe each of those things with typed fields, but it could not say how they relate. With v0.10.0 it can: reference fields link one entry to others, and repeater fields hold an ordered list of items with the same shape.

11field types, from text and dates to references and repeatersNine shipped in v0.5.0
1–5collections a reference field may point intoOne target or an ordered list
10sub-fields per repeater itemUp to 50 items per entry

How collections got here

References are the fourth stage of a plan that started a month ago. Each stage was designed in the open as an RFC in the Cloudhal repository, shipped in small steps, and kept every existing site rendering exactly as before.

Collections, stage by stage
StageWhat it addsDesign
1. CollectionsPosts, events, team and other kinds of content, each with its own permalink, feed and sitemap settingsRFC-0040
2. Typed fieldsNine field types with labels per language, required-to-publish checks and a JSON Schema agents fillRFC-0041
3. Listings, expiry, structured dataFilter and sort by up to four list fields, hide or unlist entries once a date passes, and JSON-LD for events, jobs, products and recipesRFC-0042
4. References and repeatersLink entries to each other and hold ordered lists of itemsRFC-0045

Stage 3 also moved listings into SQL. Filtering and sorting a collection by its list fields now reads a small side table instead of every entry, which is what makes larger linked collections practical:

Listing a 10,000-entry collection
  • Before
  • After (v0.6.2)
050100150200SQLiteCloudflare …SQLite, Before: 124 msSQLite, After (v0.6.2): 0.6 msCloudflare D1, Before: 176 msCloudflare D1, After (v0.6.2): 5.3 ms
Show the data
storeBeforeAfter (v0.6.2)
SQLite124 ms0.6 ms
Cloudflare D1176 ms5.3 ms

Time per query on the project's 10,000-entry benchmark, from the v0.6.2 release notes.

One event, step by step

Here is the example we use throughout: an events collection that links to places and people.

Step

1. Define the link. In the events collection, add a venue field of type reference. It may point only into Places, takes one target, and the picker offers only halls with room for 500 or more.

Events · Fields

venue

  • Type: reference
  • Target collection: Places
  • One target
  • Only places with capacity ≥ 500

A reference field points to entries of the same site: an event's venue, a talk's speakers, a product's brand. When you define one, you choose:

  • Where targets come from: one to five collections of the site.
  • How many: one target, or an ordered list without repeats (up to 20 by default, 50 at most).
  • Which ones may be picked: with a single target collection, up to four conditions on its list fields, such as "capacity of 500 or more". A target that stops meeting them later stays.

The value is the target's translation group, not a copy of its title. A Turkish page shows the Turkish version of the venue. If there is none, it falls back to the default language when the site allows it, and shows nothing otherwise. Try it:

The event page being read
Same language

Venue: Ana salon

The venue has a Turkish version, so the Turkish page links to it.

What a reference protects

References also hold their targets in place, but only while a published entry shows them. Drafts and entries in review lock nothing, so a contributor who cannot publish never pins anyone else's entry.

While a published entry references it
You try toWhat happens
Delete the target's last versionRefused, naming up to 20 published referrers
Move it to a collection the field does not allowRefused
Relink it into another translation groupRefused
Archive or unpublish itAllowed; it renders nothing, and the lock stays
Delete one language version while others remainAllowed; that language falls back or shows nothing
Unpublish the referring entryReleases its hold at once

Every entry in Studio has a Used by list of the entries that reference it, published or not, and the delete dialog shows them before you confirm. Agents get the same answer from list_references.

Because pages now depend on each other, publishing does the cache work for you. When an entry changes, the pages that reference it are purged with it, two hops deep and in every language. A publish that changes no entry and no shown image reads nothing extra.

Repeater fields: lists with a shape

A repeater is an ordered list of items that share one to ten sub-fields: an agenda's sessions, a recipe's ingredients, a job's benefits. A sub-field can be text, rich text, a number, a yes/no, a date, a link, an image, a single choice or a single reference, so an agenda item can name its speaker by linking to a person entry.

Repeaters stay flat on purpose: there is no repeater inside a repeater, and no multiple choice or list of references inside an item. That keeps every schema an agent receives at a fixed, small depth, and keeps the Studio form readable. An itemLabel names the sub-field that titles each item in Studio and in approval prompts ("Item 2: Keynote").

Here is what the event's values look like with both types:

{
  "venue": "entry_…",
  "agenda": [
    { "time": "19:30", "title": "Doors open" },
    { "time": "20:00", "title": "Keynote", "speaker": "entry_…" },
    { "time": "21:00", "title": "Panel", "speaker": "entry_…" }
  ]
}

Which one do you need?

I want to store…

A reference, one target. Point it at your places collection. The venue keeps its own page, and renaming it updates every event.

Built for agents as much as for people

Agents read a collection's fieldsSchema before writing, and references and repeaters fit into it without surprises: references are entry ids, repeaters are arrays of flat objects, and the schema never nests deeper than four levels. For providers with strict structured output there is fieldsSchemaStrict, along with a cost summary so an agent can tell when to send only part of it.

The usual guardrails apply. Changing field definitions always waits for a person, whatever mode the agent runs in, and approval prompts name targets readably, for example venue → "Main hall", rather than as raw ids. Translation works item by item, and when a translated list has its own shape, the agent gets the whole list back to translate in one piece. References are never translated: they already follow the reader's language.

The same field can be set up from wherever you work:

  1. Open the collection's settings, then Fields.
  2. Add a field, choose Reference or Repeater, and pick the target collections or the sub-fields.
  3. Entries of that collection get the new control in their Fields card, with a search picker for targets.

Only people who may change site settings can edit fields.

  1. list_collections returns fields, fieldsSchema and fieldsSchemaStrict.
  2. update_collection proposes the new definition; a person approves it.
  3. create_entry and update_entry take the values in fields (a merge patch) or fieldsStrict.
  4. list_references answers "what uses this entry?" in either direction.

Turn an existing text field into a reference, after a dry run:

cloudhal fields retype events venue reference --collections places --dry-run

Rename the title sub-field of agenda to heading in every item:

cloudhal fields rename events agenda heading --sub title

Changing your mind later

Content models change. Every field operation (rename, change type, turn translation on or off, remove) runs a dry run first, takes a snapshot, and can be reverted. This release adds conversions for the new types:

New type changes in v0.10.0
FromToHow values carry over
TextReferenceEach value becomes the one entry with that title in the field's collections
ReferenceTextEach target becomes its title
One referenceSeveralThe value becomes a list of one, and back
Several referencesRepeaterOne item per target, in a reference sub-field
Multi-line textRepeaterOne item per line
Repeater with one sub-fieldText or referencesOne line, or one target, per item

A conversion that carries ids over may only widen the target collections. While a conversion into references runs, entries in the target collections cannot be deleted or moved, so no value loses its target halfway through. If a value stops converting meanwhile (its target was archived, or a second entry took the same title), the operation stops and lists it, and Clear and finish drops only what no longer converts.

Limits

Limits for references and repeaters
WhatLimit
Top-level fields per collection30
Fields plus repeater sub-fields per collection100
Fields per site, sub-fields included200
Target collections per reference field1 to 5
Targets in a multiple reference20 by default, 50 at most
Items in a repeater20 by default, 50 at most
Sub-fields per repeater item1 to 10
References per entry, across fields and items100
Targets a page resolves200 per request

Getting started

Cloudflare

Deploy the site Worker first

The new types unlock per site, once the site Worker serving it reports that it can render them (v0.9.0 and later). Until then they are refused with fields_unsupported, so a site on an older attached Worker never stores values it cannot show. On Node (cloudhal dev, self-host, Docker) they work right away.

Checklist

  • Update to v0.10.0, and on Cloudflare deploy the site Worker before the admin Worker.
  • Upgrading runs a one-time check of each site's reference index. It is a safety net and should find nothing to change.
  • Add a reference or repeater field in Studio under the collection's settings, Fields.
  • Themes from v0.5.0 on show both automatically: references as links, repeaters as lists.
  • For custom markup, entryFields gives each reference as a card with title, link, summary and image, and referencedBy lists what points to an entry, such as events at this venue.

Questions

Can a reference point to an entry on another site?

No. A reference resolves and locks only through entries of the same site, so no value can reach or pin another site's content.

What happens to an event when its venue is archived?

The venue field shows nothing from then on. The event still holds the lock, so the venue cannot be deleted until the event changes or is unpublished.

Do I need to change my theme?

Not if it was copied from v0.5.0 or later: EntryFields draws references as links and repeaters as lists. For your own markup, entryFields returns each reference as a card.

Can a repeater contain another repeater?

No, by design. Items are flat, with up to ten sub-fields, which keeps forms simple and agent schemas small.

Will translating an entry change its references?

No. References are never sent for translation; each language's page already picks the target's version in that language.

The full rules and theme APIs are in the fields guide, and the design and its trade-offs are in RFC-0045. You can try it in the playground without an account.

This post was drafted by an agent through this site's MCP server, from the release notes and guides in the repository, and a person approved it before it went live.