Schema Design Principles for Headless CMS at Scale

You launched with 10 content types and everything felt clean. A year later you have 40 types, several of which do roughly the same thing, and your GraphQL queries are three levels deep. No single decision made the schema messy — it was a hundred small ones made without a framework. Here's what that framework looks like.

Separate Structure from Presentation

A CallToAction type should store a heading, a supporting line, and a button label. It should not store a background colour, a padding value, or a layout variant. Presentation belongs in your Next.js or Nuxt component, not in the CMS. When you conflate the two, you end up with dozens of near-identical types — BlueCtaSection, DarkCtaHero — that your editors can't distinguish and your developers hate maintaining.

Use References, Not Duplication

If five page types all display an author bio, store the author once in an Author type and reference it everywhere. The same applies to product features, pricing tiers, and team members. Duplication feels faster at first; it creates painful inconsistencies at scale when someone updates a bio in one place but not the other four.

• Reference shared entities: authors, categories, tags, product specs
• Embed data that truly belongs to one entry: a page's intro paragraph, a blog post's publish date
• Use many-to-many references for collections: a post belonging to multiple categories

Design for the Query, Not the Form

Think about what your TypeScript SDK will query before you finalise a field. If your homepage needs post title, author name, and category slug in a single response, model those as top-level fields on linked types — not nested inside rich-text or JSON blobs. A field buried in an unstructured blob can't be queried, filtered, or sorted. A proper field can.

ContentGrid's schema editor shows you the API shape as you build types, which makes it easier to catch problems before they're committed. Check that the response shape matches what your frontend needs, not just what the form looks like in the editor.

Plan for Deprecation

At scale, you'll need to retire old fields and types. Build with that in mind from the start. Name fields clearly and consistently — heroHeading not h1, publishedAt not date. Consistent naming makes it easier to write codemods when you do need to migrate. Keep a short internal doc listing types, what they're for, and when they were added. This pays off when you're onboarding a new developer who needs to understand why LegacyArticlePage still exists.

Schema debt compounds slowly and then suddenly. The teams that avoid it treat their content model as a versioned, reviewed artifact — not something one developer sets up in an afternoon and never revisits.