Org Skills
Referenceaem-headless

Content Fragment Models — design and evolution

Supporting material for aem-headless. Agents load it on demand; it ships inside the skill folder.

RawSource

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.