Sanity Studio v3 is here. Find out more on our blog →

Best practices for content modelling

How to approach structured content modelling

Don't model your content for presentation

Someone coming from conventional content management systems, might be accustomed to think of content in terms of "pages" with an assortment of more or less visually motivated units of content. In Sanity you should think of your content not as pages, but as meaningful information that a given front end will eventually possibly put on pages—or maybe not.

At some point your data may be required to power a service for a digital assistant, a smart-watch app, or the digital notification board on a bus shelter. And even if your main application always will operate in terms of pages, that page structure might be reshuffled in a redesign at some point. If you did your content modelling right, the content can power that new page structure with little to no rework.

On the other hand, this does not mean that you can't use Sanity to control display. Say you're building something that allows the people over in marketing to easily assemble landing pages on their own. This could very well be modelled 1:1 with the front-end templating as series of components living on pages that are subject to A/B/N testing and other variations based on whoever is looking at it. For this case there is no "true" model hiding behind the presentation that you could capture.

Do model according to what it "means"

Model your content in terms of article, person, project, product, story, newsItem, contactDetail, artwork, chapter. Have a clear sense of what the types and fields you define mean. Types and fields come cheap, so rather than a general items field, make it creditedArchitects, relatedProjects, milestones. The more your front-end code can assume about the meaning of an item of content, the better decisions a designer can make in terms of rendering that information clearly and beautifully.

Don't organize your content for delivery

The Sanity query language GROQ is designed to let the front-ends gather data from several documents, potentially following references and then returning only the pieces of information required. Using GROQ the front end can fetch a number of authors selecting only their names and bios, attaching each authors 5 latest books, a count of each author's books, and the id, source and title of the most recent review for each author in one single query. We did all that work to make sure you can model your content according to the natural logic of your content, and not have to think (too much) about how your data will be used in the end.

Do organize for versatility

Sanity makes it simple to reference one document from another. Make sure you divide your content into separate document types so that content may be shared and your editors don't have to update content in several places. If your books have authors, make the authors separate documents referenced from the books. When you add more data or update an author, it immediately updates the information for every book.

If you are building a documentation site and you want to provide definitions for some of your concepts in order to provide clarification in side-bar boxes or on hover: have the definitions be a separate document set and either use the advanced markup-facility in the block-editor to link to those documents, or maybe even auto-detect when a defined term is being used. Either way: write the definitions once in a separate document type so that you may share them across all documents and update them once to fix all the definitions.

On the other hand: Sanity gives you the ability to embed objects inside your documents too: use it when you have content whose structure need to be reused, but whose content is only applicable for this specific document. Let's say you're building a database about movies, and let's say you did the right thing and had a separate document type for your people-records. But for each movie you have an array of cast members. Maybe you started out having this be an array of references to people, but then you realized this is not like authors: cast members have more metadata like the name of the character, the specific form of the actors name that was billed in the end credits.

This is only relevant for this specific actor in this specific movie: Here you'd typically use an embedded object so that this information lives and dies inside the movie document as an array. Then again this embedded document should probably itself contain a reference to that specific person playing the role.

Was this article helpful?