Open this when designing models, deciding between a fragment reference and inline fields, or changing a model that is already live.
Setup
In the Configuration Browser, create a configuration under /conf/<project> with Content Fragment Models and GraphQL Persisted Queries enabled.
Apply that configuration to the DAM folder that will hold the fragments (/content/dam/<project>) through the folder's properties.
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.
# 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.