# Content Fragment Models — design and evolution

> **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/assets/content-fragments/content-fragments-models

Open this when designing models, deciding between a fragment reference and inline fields, or changing a model that is already live.

## Setup

1. In the Configuration Browser, create a configuration under `/conf/<project>` with **Content Fragment Models** and **GraphQL Persisted Queries** enabled.
2. Apply that configuration to the DAM folder that will hold the fragments (`/content/dam/<project>`) through the folder's properties.
3. Models then live at `/conf/<project>/settings/dam/cfm/models`, which means they ship in `ui.content` like any other configuration and promote through the pipeline.

## Field types, and what to use them for

| Type | Use for | Notes |
|---|---|---|
| Single-line text | Titles, slugs, short labels | Add a regex validation for slugs |
| Multi-line text | Body copy | Queryable as `html`, `plaintext` or `json` — pick one and stick to it |
| Number, Boolean, Date and time | Exactly what they say | Dates are ISO-8601 in the API |
| Enumeration | Closed lists (status, tier) | Changing the allowed values is a content migration |
| Tags | Cross-cutting classification | Filterable, and shared with the rest of AEM |
| Content Reference | An asset or a page | Returns a path; ask for the delivery URL field instead of building one |
| Fragment Reference | Another fragment | Always restrict the allowed models |
| JSON Object | An escape hatch | Not for authored data — nothing validates it, nothing queries inside it |

## Reference or inline?

**Reference** when the child has a life of its own: it is reused across fragments, governed or translated separately, or big enough that consumers will not always want it (Author, Product, CTA, Location).

**Inline fields** when it does not: an address on a single store fragment, a pair of CTA label and URL used once.

Then:

- Restrict the allowed models on every fragment reference. An unrestricted reference makes the generated GraphQL schema a union of everything and makes queries unpredictable.
- Cap nesting at two or three levels. Every level multiplies the work a query does, and deep graphs are the usual reason a GraphQL response is slow and too big to cache well.
- Use **Tab placeholders** to group fields for authors. A model with 30 fields in one column is a model authors will fill in wrongly.
- Put validation in the model (required, max length, regex, allowed asset types, unique) rather than in each consumer. It is the only place that applies to every channel.

## Naming and organisation

- Field names become GraphQL field names: stable camelCase, no renames after go-live.
- Organise fragments in DAM folders by domain and locale (`/content/dam/acme/en/articles`) so queries filter by `_path` and permissions follow the folder structure.
- Use **variations** for channel- or audience-specific copy of the same fragment, not duplicate fragments. Variations are addressable in GraphQL, so a consumer can ask for the one it needs.

## Evolving a live model

A Content Fragment Model is a public API. Treat a change the way you would treat a breaking change to a REST contract.

- **Additive only**: new optional fields and new models are safe.
- **To replace a field**: add the new one, migrate content, update and re-persist the queries, let consumers move, then remove the old field. Never change a field's name or type in place — every fragment and every persisted query using it changes at once.
- Lock models in higher environments and promote changes through `ui.content` or an agreed content-promotion process, so production models cannot drift from the repository.
- Keep a record of which persisted queries use which models, because that list is what tells you the blast radius of a change.

## Permissions and preview

- Fragment permissions follow DAM folder permissions. Model the folder tree around who may author what, before the first fragment exists.
- The **preview tier** serves unpublished content to an authenticated consumer, which is how a front end shows an author a draft without exposing it publicly. Point a preview build of the app at the preview host; do not add a "draft" flag to the public API.
- The form-based **Content Fragment editor** is the default authoring surface for headless content; the Universal Editor covers in-context editing of the rendered app. They are siblings, not alternatives — most projects use both.
