Guide

What is content modeling?

This guide is the first in a series dedicated to the craft of content modeling. We lay a foundation for what content is, touch on the basics of the content modeling process, and look at the different ways a content model can manifest.

Ronald Aveling

Ronald works with content for Sanity.io

Knut Melvær

Knut runs developer relations and support at Sanity.io.

This guide kicks off a journey through the world of content modeling. If you've never participated in a content modeling exercise, or just want to understand the process better – you’re in the right place.

We start here with first principles, and by the end of the series we'll have designed a working content model.

Along the way we’ll discover that the design of well-structured content depends a great deal on the particulars of your unique situation.

Content modeling is always worth the effort. It can be fun, creative, and scales to teams of all sizes. Once you understand the basics of the method you’ll find that you can apply it to any project to make your content more valuable, durable, and improve the workflows that surround it.

What is content?

Before we dive into modeling, we thought we'd better define exactly what we'll be modeling.

For the purposes of this guide, we’ll define content as:

Any piece of digital information, or asset, that you create or depend upon in order to fulfill your operational goals and the needs of your audience.

It's a pretty inclusive definition. In practical terms, your content can be any combination of:

  • Text (plain, or rich)
  • Media asset (image, video, etc.)
  • Data (metadata, user data, product inventory, etc.)

Content is diverse and spans your entire organisation, not just marketing. When content is regarded as a central asset and managed from a single source of truth, it spans internal silos, creates more meaning, and builds bridges of interaction and value exchange between you and your audience.

Protip

Content is contextual

When it comes to content, every organization is different.

You have a unique mix of goals, audience needs, and operational workflows. So it makes sense to create and manage your content in ways that directly relate to your circumstances.

It is common for friction and inefficiency to arise when off-the-shelf approaches to content management are forced upon the unique reality of your organisation.

What is content modeling?

Content modeling is the process of identifying, collating, and relating all of that content into a centralized structure – so that you can build efficient workflows and data structures from it.

It's is a big part of creating structured content, and when you have well-structured content your content can do more things and go more places.

Who contributes to the content model?

The modeling process involves bringing together a group of participants who can:

  • represent the varied needs of your organization and audience
  • implement the new model in code.

Here’s a list of roles you may want to include:

Content people

Your editors, copywriters, content strategists, and content managers. They have a direct connection to the production and management of your content, and will have valuable insights related to improving it along with their workflows.

Developers

They’ll build the schema that supports your content model. Your developer knows about the kinds of fields and structures you can use, when it's appropriate to use them, how to relate them to one another, and how to efficiently access all that content in the presentation layer.

User researchers

Content should exist for a reason. In most cases that reason is to help someone achieve a goal of some kind. In order to properly understand how your audience reason and interact with your content, you need to do user research.

Marketers

They know about your audience’s motivations and the channels that your content needs to travel through to reach them. They have insight into how structured content and metadata can support Search Engine Optimization (SEO) needs. Marketers often need to publish materials aimed at specific market segments, and need reusable content that they can compose across.

User interface designers

Your content gets presented to your audience through an interface of some kind. It could be a responsive website, mobile app, voice assistant, or something else entirely. Include these designers on your team to ensure that the content model addresses presentation layer concerns related to layout and accessibility.

Subject matter experts

The closer your model maps to what you do, and who you do it for – the more useful it will be. Subject matter experts can help define and relate your content in ways that make the most sense to your audience. They do this by understanding and communicating the mental models, and vocabulary terms that your audience already know and use.

Other stakeholders

This can be anyone including a valued customer, your CEO, a lawyer, accountant, or external consultant. There’s no reason why your model can’t also support the operational needs of accounting, legal, and others.

Protip

Defining the size of your content modeling group

When it comes to gathering your team,you should aim to strike a balance between the representation needs of your project and the size of your group.

If you’re a large organisation tackling complex content needs, consider creating a core working group and including external contributors on an as-needs basis.

Small organisations need not be daunted by all of the roles mentioned above. Don’t let your size or makeup stop you from modeling – use the resources that you have, and do just enough research in the areas where you’re lacking.

How a content model is documented

You can represent a content model in a range of ways:

Diagram

A common representation is a diagram that displays the main content types and their relationship to one another.

A content model diagram can look like this. Showing a range of content types and their relationship to one another.

This kind of visual reference is useful for sharing the model overall structure to people of varying backgrounds. A diagram by itself often lacks the level of technical detail required to build the actual model. It is usually supplemented with other documentation, and/or code.

Gotcha

Losing sync

To avoid confusion and inaccuracies over time, be mindful of losing sync between the diagrams you create and the underlying reality of your model. Auto-generating model diagrams from your codebase can help this.

Spreadsheet

An example of a content model in a spreadsheet. Listing content types and attributes. Also demonstrating greater detail and relationships in separate spreadsheet tabs.

Spreadsheets are often coupled with diagrams to communicate details that a diagram cannot. They can also include content examples for various fields. Spreadsheets can be really useful when starting out, or for small models. If you’re dealing with large or complex models it’s often more practical and expedient to model the content in code.

Code

Modeling in code can be very helpful for developers, and helps identify technical issues early on. Below is an example of how a content type is expressed in code for the Sanity Studio:

// Example of a 'staff member' content type in Sanity.io

export default {
  title: 'Staff',
  name: 'staffMember',
  type: 'document',
  fields: [
    {
      title: 'First name',
      name: 'firstName',
      type: 'string',
    },
    {
      title: 'Last name',
      name: 'lastName',
      type: 'string',
    },
    {
      title: 'Role',
      name: 'role',
      type: 'reference',
      to: [
        {type: 'role'}, // What they do
      ]
    },
    {
      title: 'Department',
      name: 'department',
      type: 'reference',
      to: [
        {type: 'department'}, // Marketing, manufacturing, etc.
      ]
    },
    {
      title: 'Location',
      name: 'location',
      type: 'reference',
      to: [
        {type: 'location'}, // Corporate HQ, fulfilment center, etc.
      ]
    },
    {
      title: 'Bio',
      name: 'bio',
      type: 'text',
    },
    {
      title: 'Contact details',
      name: 'contact',
      type: 'contact',
    }
  ]
}

Protip

Rapid content schemas

We’ve tried to make it effortless for developers to add, change, and remove fields in their content model through the Sanity schema.

Modeling in the schema means you can work with code from day one and version control as you go, while retaining the speed and flexibility to iterate on your model with colleagues in real-time

The value of this way of working is that you can prove your ideas with actual content, and allow that content to influence and stress-test the shape of your model as you go.

There are lots of upsides to a code-first approach, but your colleagues who are not used to reading code may have trouble understanding it. A supporting diagram can help here, but be mindful of losing sync with any diagrams that reference your code.

Protip

Sanity plugin: content model graph

We have an ecosystem of plugins available that extend Sanity in interesting ways.

The content model graph plugin automatically generates a real-time diagram of your Sanity content schema (that you can download) and makes it available in your Sanity desk. It can be a handy way to accommodate the need for diagrams without losing sync with your codebase.

On process, outcomes, and consensus

You may be thinking that a diagram or series of documents is a bit of a lackluster outcome for the time invested. But when it comes to content modeling, the process is often just as important as the model itself. The real value of the model is to:

  • generate consensus on how you think about, and act upon content
  • place content at the heart of everything your organization does

Summary

In this guide, we looked at what content is, what content modeling is, the kinds of team members and perspectives you can include in a content modeling exercise, and how a content model can manifest.

With the basics in place, we’ll talk more about the importance of content modeling in the next article in this series.

Protip

Got questions? Join our Slack community

Because content design is highly contextual, it’s hard to provide blanket answers for every situation in this guide.

So if you have a question that we haven’t answered, consider joining our Sanity Slack community. We have a channel dedicated to #content-modeling, and love to talk about the many ways you can solve content problems by design.