# 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