Don'ts and Dos

Don't model your content for display

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 re-design at some point. If you did your content modelling right, the content can power that new page structure with little to no rework.

This however does not mean that you can't use Sanity to control display accurately. Say you're building something that allows the people over in marketing to easily assemble landing pages on their own. As Sanity lets you embed data and reference documents in block text you could design articles that reuses information you already have in your data model and combine it with copy. This leads to more reuse of content and less rework.

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 your 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.

On with the show

Now, let's talk about the building blocks we provide to make proper content modelling enjoyable!

Previous: The SchemaNext: The Building Blocks