Content Modeling in Contentful

By: David Boland

photo of team in front of white board with Nansen and Contentful logos on an overlay


Content modeling can be a tricky thing. If done incorrectly, it can cause all kinds of headaches for editors. And trust me when I say going back to update the structure of your content after your project is live is worse. It's something you want to get right the first time.

Here at Nansen, we've been in the content management business a while. We thought it would be good to share some tips around content modeling in Contentful. If you aren't familiar with Contentful, I recommend checking it out. It's a headless content management system(CMS) that we've used in several implementations. If you are thinking about going headless, it should be your first look.

Before You Start

Before you dive in, it's important to get in the "headless" mindset. If you've worked with CMS before, you might be familiar with things like pages and blocks. You may have set up your page navigation with a page tree interface. Everything gets tied to the context of a website.

In Contentful, you want to separate your content from context. This doesn't mean you can't build the page, or other content types that help you define elements of a website. But you need to be able to know when to decouple elements from that context.

Let's look at an example.

Let's say you are in the retail space. You are looking to rebuild your website. You also installed some digital in-store displays at your brick and mortar locations.

two individuals looking at an in store display with an app on their phone

You want to use Contentful to manage the content for both.

Luckily, this kind of situation is exactly what Contentful was designed for. Both your site and in-store display will share a lot of the same information. Product name, sizes, colors, etc. This Product can be our first content type. It can be pulled in by our in-store display.

Screenshot of Contentful admin panel that shows the fields of a product content type

While we will still need this information on the product detail page of our website, we also need a bit more. We will need SEO data, additional page copy, maybe some references to related products. This is where the Page content type comes in.

Screenshot of Contentful admin panel that shows the fields of a page content type

This gives us everything we need. Content for our in-store display. Content for our site. And most importantly, the context and content are separated. This will help future proof our content model. We can both scale our content, or add new contexts for consuming your content. Both without effecting your existing store display or website.

Sound good? Now let's cover some of our content modeling tips.

Include Everyone in the Discussion

The job of content modeling isn't on any one project stakeholder. It's on the team as a whole. From the developers to the business team, and everyone in-between. The developers can call out what's possible from a development perspective.

They can also usually communicate what the end result will be like for the editors. The business end will help you work out the best way to model your content to align with business goals.

Brainstorming is helpful. Here are some photos of some whiteboarding we did as a team for one of our implementations.

By the end, you should all be in agreement on the expected project outcome.

photo of whiteboard with post-it notes that have page properties
photo of whiteboard with post-it notes showing the layout of a blog listing page

Leverage Content Hierarchy

The context of your content may include some sort of navigation. For example, if you are using a website, pages might have subpages. If you have a mobile app, you may need to take the users through a multi-step process. This structure can be represented in your content modeling.

A common example would be a blog listing page. You can think of your start page as the root with a path of The blog listing page would then be a sub-page of the start page at Each blog post would be one more level down at

The diagram below helps visualize this.

In Contentful, you can represent this structure with what's called "Top-Down Hierarchy". If you have a Page content type, it can have a reference to one (or many) other instances of Page type content items.

This top-down referencing structure can reflect the same page tree structure you see in a standard CMS.

This allows you to define a relationship between content, without limiting your content model to a specific context.

Model of a page tree of content

Avoid Deep Nesting

In the product detail page example above, we had an instance of page content reference an instance of product content. This idea of content referencing other content is called nesting. In all the examples we have gone through so far, we leveraged nesting.

While nesting is a necessary feature, if taken too far it can be confusing for editors. Contentful recommends not nesting more than 4 to 5 levels. We would say that's should be considered the max.

If you can avoid going more than 3 levels, that is ideal. Over 3 levels, it's easy for editors to lose context. Meaning if editors are editing content for a website, after 3 levels they might see properties that they know they need to edit. However, they might not understand how those properties apply to the website.

This model gives an example of how quickly you can lose context the more levels you nest.

diagram that shows a tree of Contentful content

While Banner Callout content might not reference all the possible CTAs and links, it still in theory could. So it makes sense that it can get confusing for an editor.

As the number of references grows, so will the complexity. If an editor is working on content for the Blue Button CTA, they may forget if it's being edited for Page Teaser or the Banner Callout. They might even forget which page they are on.

Use Flexible Assemblies Contentful refers to content types that can reference other content types as assemblies. If your content type allows for a single reference, it's considered a fixed assembly. If it can have multiple references, its referred to as a flexible assembly.

When in doubt, always opt for a flexible assembly model. We have come across instances where content modelers use fixed assemblies, or even topics (content types that don't have any references). The idea being that if you have a blog page type, it will only need the basic page data, as well as a rich text editor for the post.

The problem with that approach is that requirements are always changing. Take the blog page scenario. The requirement might start out with a blog page. But what happens if you want to show teasers to related articles? Or if your post discusses a new product? You might want to reference it on the page. It's better to make these types of flexible assemblies from the start.

Final Thoughts

These tips are what we look to first when starting to build out our content models. Do we stick to them always? No. Every project is unique, with its own set of requirements.

The most important thing is to work on that headless mindset. Once you have that down, knowing which of these tips best applies to your project will become easy.

Are you a Contentful content modeler? Contact us via Twitter and/or Linkedin with some of your favorite content modeling tips.