8 Content Modeling Pitfalls to Avoid

8 content modeling pitfalls to avoid

What do you need to consider when modeling content? In this article, our MVP Ilesh Mistry shares his experience and talks about his top 8 content modeling “gotchas”.

Ilesh Mistry

Ilesh MistryPublished on Jul 21, 2020

Working with a headless CMS is often seen as the promised land, particularly from a developer’s perspective. The opportunity to open the development toybox and leverage the latest and greatest frameworks and patterns is mouth-watering.

However, there is much more to a headless CMS implementation than just frameworks and patterns. Content modeling is an activity that’s fundamental for a successful delivery. Get this wrong and, as the project develops, you will run into major problems for both content editors and your development team. More importantly, it can lead your clients to feel that the headless CMS is not going to deliver what you expected, and worse, make you feel that choosing the headless CMS was a wrong decision.

Approaching content modeling in a thoughtful and future-proof manner is essential, acknowledging the capabilities and constraints of the CMS as well as identifying the optimum experience for clients.

For those new to content modeling, have a read through Michael Kinkaid’s ebook Content Modeling in a Headless CMS and, bearing in mind the current climate, also check out the best practices on remote content modeling from my colleague Rick Madigan.

My top 8 content modeling gotchas

For those who are about to start content modeling, there is a range of approaches, and these come with their own pitfalls. I’m going to talk about some of the things you would need to consider when modeling content. So, here are my top 8 content modeling gotchas:

1. Don’t build your content models without communication   

Within any project, there are several involved parties—experience design, product backlogs, technical architecture, and editors, to name a few. Charging straight into content modeling in isolation, without room for adjustments, forces you to create the models based purely on the information you may have at that point in time. But as we all know, projects are living, breathing things where change and evolution are commonplace. The models you create may not cover the lean MVP requirements established by the product owner and will likely miss the discussions and adjustments coming from refinement sessions.


Work closely with all members of the team and keep in constant communication, acknowledging the subtle shifts in requirements. Establish key meetings and touchpoints to not only plan out content models but also to implement in line with development, avoiding wasted time.  

2. Avoid creating Content Types for individual Content Items

There are times during content modeling when you need to create a Content Type purely for a single Content Item. An example of this could be the ‘Home’ type, where there are no other possible instances that could reuse that Content Type. However, there are times when you create a new Content Type for the sake of subtle differences. Think about this in the bigger picture, and these micro-decisions start to spiral, and, before you know it, you’ve created Content Types for singular Content Items and have an expansive list that is hard to manage, increasing the complexity for development. 


Think about reusability wherever possible and, more importantly, be ruthless and actively seek out ways to consolidate content types. 

3. Add restrictions to the fields 

When modeling content, it’s really easy to get carried away and create Content Types without consideration towards the target audience—your content editors. You can get caught up in thinking about the fields/elements that are required based purely on the designs. However, this lack of consideration can lead to ruin. Not adding restrictions to them can cause catastrophic issues in the long run.

For example, if you have a Hero Content Type and thereʼs a limited amount of space for the title, summary text, and CTA to show on the page, then not adding restrictions to the fields/elements will quickly break the content type output. As with the previous point, things can spiral rapidly as you scale out to the bigger picture.


Carefully consider the different fields/elements in each content type. Decide what character limits are needed, whether they need to be a required field or not, what sort of linked items are allowed within a given area, and any other limitations to avoid your development team cowering under the desk from content model nightmares.

4. Avoid overcomplicating your content types 

While reusability is a good practice, it’s easy to abuse it and overcomplicate your content modeling.

For example, you may build a content type and then decide to create sub-content types within it to match a specific design. There are, of course, valid scenarios for this behavior but, if left unchecked and used without consideration, you can soon find yourself with parent content types containing a lot of unnecessary child levels or a large number of nonessential linked items. The content editor is forced to double or triple their cognitive load dealing with an overly complex content type. Not only that, but you may have also just gone over the quota for Content Items or Content Types, which could incur big costing implications.


Your target audience is your primary consideration. Go for simpler structured data content modeling where possible and be smart with the potential linked items you introduce. Above all, avoid content type ‘whirlpools’ that can get messy and costly fast! 

5. Think first before using fixed Components in Rich Text fields/elements 

When you model content, there could be scenarios when you need to use a content type in a single instance. Examples of this are a Tweet placed between blocks of copy or even a call-to-action “interrupting” a piece of text. It’s tricky to model these out as they don’t sit within a given position in the text. Essentially, the content editor has the power and decides where they want to use this. This is perfectly fine, but it’s vital that the content editors understand that Components (the name for these single-use content items) are not reusable—unless they are converted to be reusable.

Also, spare a thought for the poor developers. If you need specific fields within the components to be included in the search as a filter, it is time consuming and complex to trawl through the Rich Text field for modular content and extract the information you need.


Think carefully about where and when you allow for the use of Components within Rich Text and, of course, make sure you limit the number of different types that can be used. As always, think about the bigger picture and how it could impact features like search. 

6. Not considering the different channels you need to serve 

An advantage of the headless CMS is the ability to structure your content away from the traditional editorial experience—and all the limitations that a traditional CMS brings. Essentially, you are creating a content hub, managing the content within one place, and serving it to different channels.

The potential is awesome, but if you don’t approach it in the right way, you can easily dig yourself a big hole and potentially overshoot the boundaries of your pricing plan.

The most common mistake is mixing content with channel variables. Let’s take the home page as an example. If you add all the metadata, page information, and web-specific information into the same Content Type as your homepage specific content, introducing a new channel is instantly problematic. Not only are you facing a nightmare separating channel information from content, but then content editors tackling different channels are falling over themselves. If you’re also introducing layout information into that Content Type (shame on you if you are!), that problem swiftly grows.


Strategy is everything. Don’t approach content modeling with tunnel vision. Yes, you may need to deliver an MVP, but at least think about where this sits in the bigger picture. Thinking ahead about your channels will make your life easier in the long term. And definitely avoid layouts in your Content Types. That’s what a traditional CMS is for! 

7. Utilizing the projects and spaces you have available

Headless CMSs can be divided into open source and Software as a Service (or Content as a Service). For the latter, every vendor offers a range of subscription plans. Understanding what is available within those plans is important in making sure you can get the best out of the CMS. For example, if you have an unlimited number of projects/areas in which you can create Content Types and Content Items, use them! If you put all of your eggs into the one basket, then your basket is going to be very heavy and hard to manage.

Consider a piece of content, manageable text that appears in multiple places within your project. In Kentico Xperience, you would call this a Resource String. Now imagine you have lots of content items representing various pages and components across the site. These smaller pieces quickly get lost. Folding everything into a single project isn’t necessarily the right thing to do—even if you have a great search and filter.


Think about your content structure and consider how different spaces can be used to provide a greater content experience. For example, a project/area for your “resource strings,” another for pure content for Site 1, another for pure content for Site X (assuming there are multiple websites), and another for shareable content between your different sites. Organizing your content modeling and content this way will make it easier to manage in the long term.

8. Avoid the content hub overruling others when it is not needed 

There comes a time when you’re dealing with different data sources and the headless CMS is not the only piece of your complex architectural jigsaw. This isn’t the old world. The CMS is no longer the central store of everything. If you’re using a commerce platform and have product information, you don’t need to replicate that information into the CMS. There are smarter ways to work with Custom Elements that avoid the pain that comes with unnecessary duplication. It’s the same for any system in this new architecture.


Map out your architecture thoroughly and understand where the core content and connecting data should sit. Clearly identify your master sources for each set of data and think about the mapping and relationships between data sets, e.g., core product information in PIM or e-commerce and associated rich media for products in the CMS.


So, there you have it. Those were my top 8 things to be aware of when undertaking content modeling. It can be time consuming and challenging but also very rewarding when done correctly. As you can tell, there are lots of ways to get it wrong, and clearly defined best practices can keep you on the straight and narrow. If you need any help with this, contact me via email (, and I can help you with it further.

Ilesh Mistry
Written by

Ilesh Mistry

I’m a MVP and Senior Front-End Engineer, who likes to talk about his favourite headless CMS. I'm also the Founder and organise the IM Tech Meetup's for front-end enthusiasts. Want to know more? Get in touch!

More articles from Ilesh