Relationships and composition

Why Relationships Need to Be Explicit

Relationships are one of the areas where CMS platforms diverge most.

If a source model only says “this field points to another thing” without saying how that relationship behaves, translators are forced to guess. CMMF makes relationship intent explicit so that downstream choices can be made deliberately and logged clearly.

Object Versus Reference

The first important distinction is between object and reference.

object

Use object when the field is conceptually embedded structure.

This usually means:

• it exists as part of the parent content
• it does not have an independent editorial identity
• its lifecycle is typically tied to the parent

reference

Use reference when the field points to another model with its own identity.

This usually means:

• the related content can exist independently
• the related content may be reused elsewhere
• editorial ownership may be separate from the parent entry

Relationship Options

Repeatability uses field-level list, while the relation object adds more detail to reference semantics.

list

Repeatability is expressed at the field level with list: true.

For reference fields, this answers the same modelling question that cardinality used to answer: is this relationship singular or repeatable?

This keeps repeatability consistent across primitives, objects, and references.

If list is omitted, the field is singular.

Legacy relation.cardinality

Older reference fields may still use:

• one
• many

That form remains useful for compatibility during migration, but new models should prefer list.

ownership

Defines the intended ownership model.

• linked
• contained

linked means the related item is conceptually separate. contained means the parent conceptually owns the related item, even if the target CMS forces that content into a separate implementation shape.

This is especially important because two translators might implement contained differently while still preserving the same source intent.

ordered

Indicates whether order matters.

This matters for:

• page composition
• curated lists
• sequences and journeys

uniqueItems

Indicates whether duplicates are allowed.

minItems and maxItems

Define list size constraints.

Why contained Is Valuable

contained is one of the most important signals in the model because it separates conceptual ownership from technical implementation.

For example, a contained relationship might become:

• a nested embedded structure in one CMS
• a separate type hidden behind a parent editor in another
• a first-class content type with translator-managed containment rules in a more limited platform

Without an explicit containment signal, those translations can drift in meaning.

Lists in CMMF

CMMF uses one repeatability mechanism across field types:

• primitives use list: true
• objects use list: true
• references use list: true

The distinction between embedded structure and independent content still comes from object versus reference, not from separate repeatability keywords.

What Explicit Relationships Enable

Stronger relationship modelling enables better tools, including:

• translators that can explain their decisions
• validation that detects suspicious patterns
• diagrams that distinguish embedding from linking
• architecture reviews that focus on modelling intent instead of raw field syntax

Source: canonical 1.2.0 material at 32604441 · Download original Markdown