AEM Sites Playbook, Chapter 5: Structured content, fragments and headless delivery
How should structured content be modeled, managed and consumed?
November 10, 2026
Model information for its consumers
Use structured content when a stable set of facts needs management independently of one page layout. Begin with the consuming tasks and the editors' responsibilities. Decide which fields are required, how references work, what can vary by locale and how consumers handle missing or withdrawn content. Avoid designing a model solely around the first component that displays it.
A Content Fragment supplies structured content; an Experience Fragment represents a reusable composed experience. They serve different contracts. Edge Delivery fragment patterns also need their own implementation assessment. The structured-content API overview and headful/headless guidance help distinguish management, delivery and rendering responsibilities.
Name a schema owner and the consumers that depend on each model. Agree on identifiers, field meanings, allowable values and reference behavior. When a field changes, identify whether consumers can tolerate it, require a coordinated release or need a transition period. Maintain sample content that tests both valid and difficult cases.
Separate management from delivery
An API used by an integration to create content is not automatically the right API for a public application. Adobe distinguishes delivery-oriented Content Fragment APIs from management APIs; the older Content Fragment support in the Assets HTTP API is deprecated in favor of newer API families. Choose the current supported interface for the operation and target deployment. API boundaries
For a hypothetical product import, define the source of truth for product identifiers and factual fields, then protect editor-owned descriptions or local additions. The Salsify integration discussion explores these design choices without a final author-confirmed implementation. Repeated imports need reconciliation and clear overwrite rules before performance tuning.
Test creation, update, duplicate input, withdrawal, deletion and broken references. Have a representative editor find and correct imported content. Have a consumer demonstrate what happens when the expected field or referenced image is unavailable. An import that creates nodes but leaves unmanageable content has not met its editorial requirement.
Verify the complete consumer response
For GraphQL, decide which queries the application needs, which parameters are allowed and how pagination bounds the result. Persisted queries can use cacheable GET delivery through the documented infrastructure; browser and shared-cache controls differ. Apply the persisted-query guidance to the actual route and verify freshness in chapter 11.
Check dependency publication separately. The 6.5.14 fragment-workflow question concerns missing associated images/tags, while the LTS component discussion describes existing rendering with failing authoring. Together they require tests for both content consumers and future editing. Neither establishes a general custom-code recipe.
The data-layer exporter discussion also distinguishes browser instrumentation from a component JSON contract. A value visible in one interface need not appear in another. Write explicit response assertions rather than infer one contract from another screen.
Design a model that can change without losing meaning
Give each field a business definition, source, editor, locale rule and consumer expectation. A field called description is ambiguous if one consumer expects promotional copy and another expects a technical specification. Identify whether a reference is required for publication and what the consumer should do when it is absent.
Scroll horizontally if needed.
| Design choice | Prefer when | Check before committing |
|---|---|---|
| Structured field | The information has independent meaning, validation or reuse | Editors and consumers agree on its semantics |
| Composed experience | Layout and presentation are part of the reusable unit | Target channels can use that composition appropriately |
| Reference to another content object | Shared ownership or lifecycle needs to remain separate | Permissions, locale, publication and deletion behavior are defined |
| Copy data into AEM | Editorial control or an approved local snapshot is required | Synchronization, reconciliation and overwrite rules exist |
| Retrieve data from the source at delivery time | The delivery contract genuinely needs current source data | Availability, latency, access, caching and fallback are acceptable |
Community discussions explore competing ingestion and retrieval approaches without establishing a proven winner. The decision table asks what the team must operate under each choice. Keep integration complexity visible even when the first content model is small.
Worked scenario of a model change with two consumers
The following content, versions and results are hypothetical. A product fragment has a shared identifier, factual attributes, a marketing description and an image reference. A website and a partner portal consume it. The product team wants to split a single availability field into status and expected date.
The model owner inventories the current consumers and asks how each behaves if the field is absent, renamed or temporarily inconsistent. Instead of changing all assumptions at once, the team trials a documented transition: retain the old contract for existing consumers while introducing explicitly defined new fields. The actual supported schema/API migration procedure must be selected for the target deployment.
Scroll horizontally if needed.
| Record | Contract to agree |
|---|---|
| Identifier | Stable across ordinary updates; creation and replacement are distinct operations |
| Availability status | Defined allowable meanings and business owner |
| Expected date | Meaning, locale/display responsibility and missing-value behavior |
| Description | Which copy is centrally managed and which is locally editable |
| Image reference | Required destination/locale and behavior when missing or withdrawn |
| Consumer transition | Owners, supported response versions, test fixtures and retirement condition |
The team creates a fixture for an available product, a future product, missing optional data and a withdrawn reference. It also re-imports a product after a local editor changes permitted copy. This tests the model as an editorial and integration contract, not only a successful API response.
Scroll horizontally if needed.
| Test | Illustrative observation | Consequence |
|---|---|---|
| Existing portal consumes the retained contract | Works | Continue the transition trial |
| Website renders the new fields | Works for complete data | Test the other fixture states before acceptance |
| Expected date absent | Website prints an empty label | Repair consumer behavior |
| Re-import after local editing | Local description is overwritten | Mandatory ownership rule fails |
| Image withdrawn | Portal keeps a broken reference | Publication/consumer contract remains incomplete |
The decision is to hold the wider model change, repair overwrite and missing-reference behavior, and retain the existing consumer contract until transition criteria pass. A successful response for one complete fragment does not justify deleting the old field immediately.
Separate the interfaces in the acceptance record
Use current API guidance to identify management and delivery interfaces. Record the actual endpoint family, credential model, caller and consumer. Test create/update operations under the integration identity and delivered reads under the intended audience separately. Include bounded result size, relevant pagination and query/parameter behavior in the consumer tests.
For persisted GraphQL, retain the approved query identity and parameters with the fixture. Verify the response fields and freshness through the real delivery route; do not infer delivery from a management GET. When a different frontend owns rendering, that team must own missing-data behavior and preview integration.
Test future authoring as a compatibility requirement
The LTS fragment-component question, reports working rendering and failing new author selection. The author planned to pursue Core Components but did not confirm the result. Treat an existing response and an editable future content state as separate acceptance checks.
Ask an ordinary editor to create a new object, find it, change references, compare the expected content and submit approval. Record which fields are unclear, which tasks need developer assistance and what happens after a consumer/model release. The model is ready for wider use when both editors and consumers can operate its lifecycle within the agreed ownership rules.
Retain the contract
Complete W05 with models, source ownership, consumer contracts, identifiers, references and change handling. Business owners approve content meaning; API/frontend owners approve consumption; editors accept maintainability. Record the tested deployment and unresolved edge cases. Use chapter 14 for authentication and integration retries, and chapter 10 for the publication dependency set.
W05 Structured content and consumer contract
Use with chapter 5. Make source ownership and API meaning explicit.
Scroll horizontally if needed.
| Record | Entry |
|---|---|
| Model/field meanings, identifiers and validation | [enter] |
| Source-owned and editor-owned fields with update/delete rules | [enter] |
| Locale/reference relationships and missing-reference behavior | [enter] |
| Management API and separate delivery API/consumer contract | [enter] |
| Model-change compatibility and transition plan | [enter] |
| Duplicate/re-import, withdrawal and consumer test evidence | [enter] |
