Content Fragment Models: Designing the Structure Behind Your Content

Define the contract before authors create the content

A Content Fragment can be independent of a page and still be inconsistent with every other fragment of the same kind. If one Product has a description and image while another has price and technical fields, neither authors nor API consumers have a reliable contract.

A Content Fragment Model is that contract. It defines the fields and relationships available to a fragment before authors enter values. The model should come from the business concept, not from a list of fields a particular page happens to display.

The Problem Is Not the Authors

It might be tempting to solve this by simply asking authors to follow a documented structure.

For a small project, that may work.

But enterprise content rarely stays small.

Authors change.

Teams grow.

New products are introduced.

New people join the content team.

Over time, relying on everyone to remember the same rules becomes difficult.

The problem isn't that authors are doing something wrong.

They are working with the information available to them.

The real problem is that the structure was never formally defined.

If the organization expects every Product to contain the same type of information, that structure needs to be established before the author starts creating individual Product Content Fragments.

This is the point where content modeling becomes necessary.

Defining the Product Before Creating the Content

Before creating Product Content Fragments, the team should agree on what information defines a Product. For the glucose monitor, that might include:

Product Name
Description
Features
Specifications
Product Image
Category

These are business decisions, not AEM decisions. Define the business concept first, then represent it with an AEM model so authors and consuming applications share a predictable structure.

A Model Creates a Common Contract

Once the structure has been agreed upon, the team can define it as a Content Fragment Model.

For our Product example, the model might define:

Product
 ├── Product Name
 ├── Description
 ├── Features
 ├── Specifications
 ├── Product Image
 └── Category

The author now works within this agreed structure and supplies the values for each product.

For example:

Product Name: Glucose Monitor
Description: Continuous glucose monitoring device
Features: ...
Specifications: ...
Product Image: ...
Category: Medical Devices

Other products have different values but follow the same structure, giving consuming systems a consistent contract.

The Model Should Represent the Business, Not the Page

The Product Model should describe the business concept, not the way it happens to appear on today's website. For example, a product page might display:

Product Name
Product Image
Description
Features
Call to Action

Avoid modeling the fragment around presentation-only elements such as a call to action. A mobile app or another frontend may use a different subset or arrangement of product data. Ask what information defines this Product regardless of where it is presented? The presentation can change without changing the underlying business content.

What Happens When the Model Is Designed Poorly?

The impact of a content model is not always visible when the first few fragments are created.

The model may look perfectly reasonable when the project is small.

The problems usually appear later, when more content and more consumers depend on it.

For example, imagine the Product Model stores all technical specifications inside one large text field.

At first, that seems convenient.

The author can enter everything in one place.

But later, the mobile application needs to display each specification separately.

Now the application has to interpret a block of text instead of receiving structured information.

The same problem can happen when information that should be reusable is stored directly inside the Product Fragment.

Suppose the same manufacturer is associated with hundreds of products.

If the manufacturer name is stored as plain text in every Product Fragment, changing or managing that information becomes a content maintenance problem.

The issue is not with the authoring interface.

The issue is that the model did not represent the business concept correctly.

Once authors and consuming applications depend on the model, changing it may require content migration and updates to those applications. The next section looks at that contract-change risk in detail.

Model Ownership and Collaboration

Content modeling should not be decided by the AEM developer alone:

• The business identifies what information matters.
• Content authors explain how it needs to be created and maintained.
• Frontend teams identify how consuming applications use it.
• Architects ensure the model represents the business concept and supports its consumers.

The model should not be created in isolation, but that does not mean every team must design every field together. Start with the question: What business concept are we trying to represent? Then provide enough structure for consistent content without unnecessary complexity.

The goal is a model that represents the business clearly, gives authors a predictable structure, and provides consistent content to applications while remaining practical to evolve.

Model changes are contract changes

Let's return to the glucose monitor example one more time.

Imagine the Product Model has already been used to create hundreds of Product Content Fragments.

The business now decides that technical specifications should be available individually.

Instead of one large specification field, they now want:

Sensor Type
Measurement Range
Battery Life
Connectivity

On a new project, this change might seem straightforward.

But the existing content was created using the original structure.

Now the team has to think about what happens to those existing fragments.

Do they need to be migrated?

Will the API structure change?

Do frontend applications need to be updated?

Are there integrations that depend on the existing structure?

A seemingly simple model change can become a production change once fragments and applications depend on the original structure. You cannot predict every future requirement, so design for a clear business concept and plan how existing content and consumers will change when requirements do evolve.

The decision to carry forward

Treat a model change as a potential content and API contract change: consider existing fragments, validations, GraphQL consumers, and publishing before changing the structure.

Next: Fragment References and Content References model relationships without copying the related content.