Building Scalable Content Models: A Practical Guide

Content modeling is the foundation of any successful CMS implementation. Get it right, and your content scales effortlessly. Get it wrong, and you're in for a world of pain down the road.

In this guide, we'll explore how to build content models that stand the test of time.

What is Content Modeling?

Content modeling is the process of defining the structure of your content. Think of it as creating a blueprint for your digital content architecture.

A good content model:

• Reflects your business needs
• Scales as your content grows
• Adapts to changing requirements
• Empowers your content team

Start with Your Use Cases

Before jumping into Graph (or any CMS), start with these questions:

1. What content will you manage?

List out all the types of content you need:

• Blog posts
• Products
• Team members
• Case studies
• Landing pages

2. Who will use this content?

Understanding your audience helps shape your model:

• Developers need clean APIs
• Marketers need easy editing
• Designers need flexibility

3. Where will content appear?

Modern content lives everywhere:

• Website
• Mobile app
• Email campaigns
• Third-party integrations

The Building Blocks

In Graph, you have several field types to work with:

Text Fields

{
  name: "Title",
  type: "text",
  required: true,
  validation: {
    maxLength: 100
  }
}

Rich Text

For formatted content with full editing capabilities:

{
  name: "Body",
  type: "html",
  required: true
}

Relations

Connect content together:

{
  name: "Author",
  type: "relation",
  contentType: "authors",
  multiple: false
}

Media

Images, videos, and files:

{
  name: "Cover Image",
  type: "media",
  accept: ["image/*"]
}

Real-World Example: Blog System

Let's build a complete blog system. We'll need three content types:

1. Blog Posts

{
  name: "Blog Post",
  fields: [
    { name: "Title", type: "text" },
    { name: "Slug", type: "text" },
    { name: "Excerpt", type: "textarea" },
    { name: "Body", type: "html" },
    { name: "Cover Image", type: "media" },
    { name: "Author", type: "relation", contentType: "authors" },
    { name: "Category", type: "relation", contentType: "categories" },
    { name: "Tags", type: "relation", contentType: "tags", multiple: true },
    { name: "Published Date", type: "datetime" },
    { name: "SEO Title", type: "text" },
    { name: "SEO Description", type: "textarea" }
  ]
}

2. Authors

{
  name: "Author",
  fields: [
    { name: "Name", type: "text" },
    { name: "Bio", type: "textarea" },
    { name: "Avatar", type: "media" },
    { name: "Twitter Handle", type: "text" },
    { name: "LinkedIn URL", type: "text" }
  ]
}

3. Categories

{
  name: "Category",
  fields: [
    { name: "Name", type: "text" },
    { name: "Slug", type: "text" },
    { name: "Description", type: "textarea" }
  ]
}

Best Practices

1. Keep it Simple

Start with the minimum viable model. You can always add fields later.

❌ Don't:

// Too many fields upfront
{ name: "Meta Keywords", type: "text" }  // Not used anymore
{ name: "Read Time", type: "number" }     // Can be calculated
{ name: "Word Count", type: "number" }    // Can be calculated

✅ Do:

// Start simple
{ name: "Title", type: "text" }
{ name: "Body", type: "html" }

2. Use Relations Wisely

Relations are powerful but can impact performance. Use them when you need:

• Reusable content (authors, categories)
• Complex filtering
• Content that changes independently

3. Plan for Localization

Even if you don't need it now, consider:

{
  name: "Title",
  type: "text",
  localized: true  // Enable when ready
}

4. Think in Components

For flexible layouts, use repeater fields:

{
  name: "Page Sections",
  type: "repeater",
  subFields: [
    { name: "Section Title", type: "text" },
    { name: "Section Content", type: "html" },
    { name: "Section Image", type: "media" }
  ]
}

Common Pitfalls

Over-Normalization

Problem: Creating too many small content types

Solution: Start with fewer types and split when necessary

Under-Modeling

Problem: Using a single "Page" type for everything

Solution: Create specific types for specific use cases

Ignoring Editors

Problem: Building models only developers understand

Solution: Involve content creators early

Testing Your Model

Before going to production:

1. Create sample content – Does it feel natural?
2. Test the API – Is the structure intuitive?
3. Get feedback – Ask your content team
4. Iterate – Don't be afraid to refine

Migrating Existing Content

Already have content? Here's how to migrate:

1. Export existing data

npm run export-content

2. Map to new structure

const mapped = oldPosts.map(post => ({
  title: post.title,
  slug: post.slug,
  body: post.content,
  author: findAuthor(post.authorId)
}));

3. Import to Graph

for (const post of mapped) {
  await graphcms.createEntry('blog-posts', post);
}

Conclusion

Good content modeling is both art and science. Start simple, iterate often, and always keep your users in mind.

Remember: Your content model should evolve with your business. Graph makes it easy to adapt as you grow.

Want to learn more? Join our Discord community where we discuss content architecture daily.