What We Learned From Modeling Content in a Headless CMS
Three years of architecting content models in Contentful taught us that the real challenge isn't the CMS — it's understanding your content's relationships before you touch the UI.
Content modeling is the discipline that headless CMS projects live or die on. Get it right and the CMS becomes a joy for editors and developers alike. Get it wrong and you end up with content types that are impossible to reuse, references that create circular dependencies, and migration costs that nobody budgeted for.
Model the Domain First, Not the Page
The most common mistake we see is building content types that mirror page layouts rather than the actual domain model. “HomePage”, “ServicePage”, and “ContactPage” are page types, not content types.
A better approach: identify the discrete entities in your domain first.
- What are the atomic units of content? (Article, Product, Person, Location)
- What are the relationships? (Article has many Tags, Product belongs to Category)
- What content is shared across contexts? (A Team Member appears on About, on Blog posts, and in case studies)
Once you model the entities correctly, assembling them into pages becomes a configuration concern, not a data modeling concern.
Field Validation is Documentation
Headless CMS platforms let you set validation rules on fields: required, min/max length, allowed values, regex patterns. Use them aggressively. When a Short Text field for “meta description” has a max of 160 characters, editors get real-time feedback. When a slug field requires a URL-safe pattern, you eliminate an entire class of deployment errors.
Validation rules encode the rules of your system in the tool that editors actually use. That’s more durable than a style guide nobody reads.
Localization Architecture
If there’s any chance the content will be translated, design for it from day one. Retrofitting localization onto an unlocalized content model is brutal — field types, reference resolution, and URL routing all need changes.
In Contentful, set locale-specific fields at the individual field level, not at the entry level. This lets you have an Article where the title and body are localized but the slug and author reference are not — which is usually what you want.
Rich Text vs. Structured Content
Rich text fields are tempting because editors love them. Resist. Rich text is a black box — your rendering layer has to handle every possible HTML structure, and over time editors will produce markup you didn’t anticipate.
Where possible, replace rich text with structured fields: a list of ContentBlock entries, each with a type (paragraph, pullquote, image, codeblock) and typed fields. This gives you full rendering control and makes the content portable across channels.
Use rich text only for long-form editorial content where structure can’t be predicted, and restrict the allowed marks and block types.
Migration Strategy
Plan your migration before you build. Headless CMS projects almost always involve importing content from a legacy system. Define your data mapping before you finalize your content types — the import requirements often reveal modeling decisions you hadn’t considered.
Write idempotent migration scripts. Run them multiple times against staging before touching production. Content migrations that go wrong at 2 AM are memorable for all the wrong reasons.