Adovo

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 a model that can change without losing meaning: table 6
Design choicePrefer whenCheck before committing
Structured fieldThe information has independent meaning, validation or reuseEditors and consumers agree on its semantics
Composed experienceLayout and presentation are part of the reusable unitTarget channels can use that composition appropriately
Reference to another content objectShared ownership or lifecycle needs to remain separatePermissions, locale, publication and deletion behavior are defined
Copy data into AEMEditorial control or an approved local snapshot is requiredSynchronization, reconciliation and overwrite rules exist
Retrieve data from the source at delivery timeThe delivery contract genuinely needs current source dataAvailability, 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.

Worked scenario of a model change with two consumers: table 9
RecordContract to agree
IdentifierStable across ordinary updates; creation and replacement are distinct operations
Availability statusDefined allowable meanings and business owner
Expected dateMeaning, locale/display responsibility and missing-value behavior
DescriptionWhich copy is centrally managed and which is locally editable
Image referenceRequired destination/locale and behavior when missing or withdrawn
Consumer transitionOwners, 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.

Worked scenario of a model change with two consumers: table 11
TestIllustrative observationConsequence
Existing portal consumes the retained contractWorksContinue the transition trial
Website renders the new fieldsWorks for complete dataTest the other fixture states before acceptance
Expected date absentWebsite prints an empty labelRepair consumer behavior
Re-import after local editingLocal description is overwrittenMandatory ownership rule fails
Image withdrawnPortal keeps a broken referencePublication/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.

W05 Structured content and consumer contract: table 17
RecordEntry
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]

Continue exploring

Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 1: Strategy, value, ownership and adoption

What outcome justifies the work, and who will operate it?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 10: Preview, publication, scheduling and withdrawal

How do we release and remove the complete approved experience?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 11: Delivery, Dispatcher, CDN, domains and caching

Which layer controls the request, redirect or stale response?

Read more
Explore data and analytics services →