Sanity top tip: the Grandma test

Before we even touch upon Sanity Schema, I want to do a brief rundown of Structured content because it's important when assessing what needs to be in/out of your schema.

Structured content is a method of organising and managing information in a standardised, consistent format. It improves content accessibility and discoverability, making it easier for users and developers to find and use the information they require. Sanity is a powerful platform for structured content.

Give me an example in real terms

An example is a blog post you've almost definitely come across. They all have different fields but let's address the ones that nearly always appear:

Title
Publish date
Author
Body of text

Structured content is all about organising the above into an easy-to-understand structure without forcing your content creators to spend 20 mins scanning through forms.

The grandma test

How do we make structured content in a simple, consistent way? We design it for our grandmas'.

Instead of thinking of our schema as a complex collection of data, we approach it as if it's a note we left on the fridge. Keep it casual, friendly and assume pitfalls when writing it.

E.g. don't make a title too short.

Here's an example of writing the above schema with Grandma in mind:

import {FaNewspaper} from 'react-icons/fa'

export const SingleArticle = {
  title: 'Article',
  name: 'article',
  type: 'document',
  icon: FaNewspaper,
  // Nice little icon to help people understand what type of document this is.
  fields: [
    {
      name: 'title',
      title: 'Title',
      description:
        "Every page should have a title that isn't too long or too short. We recommend page titles are between 10 and 60 characters.",
      type: 'string',
      validation: (Rule: any) => Rule.required(),
    },
    {
      name: 'date',
      title: 'Published Date',
      description:
        "Make sure to select a publish date in the future if you plan to release it at a later date, or if you're planning on publishing today, use todays date",
      type: 'datetime',
      validation: (Rule: any) => Rule.required(),
      initialValue: () => new Date().toISOString(),
    },
    {
      name: 'description',
      title: 'Description',
      description:
        "Page descriptions shouldn't be too long or too short. Long page descriptions will only be partially shown in search results and short descriptions are unlikely to to be helpful to users. We recommend page descriptions are between 100 and 320 characters.",
      type: 'text',
      rows: 3,
      validation: (Rule: any) => [
        Rule.required(),
        Rule.min(100).warning('We advise writing a description above 100 characters'),
        Rule.max(320).warning('Any more and it will get truncated'),
      ],
    },
    {
      name: 'image',
      title: 'Image',
      type: 'image',
      description:
        'Add an image to make it nice for people to view when sharing it on social media. Remember to make sure the image is bigger than 1200 pixels, you can always crop it with the hotspot',
      validation: (Rule: any) => Rule.required(),
      options: {
        hotspot: true,
      },
      fields: [
        {
          name: 'alt',
          type: 'string',
          title: 'Alt Text',
        },
      ],
    },
    {
      name: 'author',
      title: 'Author',
      type: 'reference',
      description:
        'Remember to attribute this blog to an author, that way it shows that they have written it on the page.',
      to: [{type: 'author'}],
    },
    {
      name: 'portableText',
      title: 'Document text',
      description:
        'This is where you enter the majority of the text, not forgetting to add headings, lists, images, etc.',
      type: 'portableText',
    },
  ],
  preview: {
    select: {
      title: 'title',
      subtitle: 'description',
      media: 'image',
    },
  },
  orderings: [
    {
      title: 'Publishing Date, Newest First',
      // Make sure to add this to see your latest published by the publish date
      name: 'dateDesc',
      by: [{field: 'date', direction: 'desc'}],
    },
  ],
}

The more you think of writing up schema as if it's a note to Grandma, the better it will be. It'll be less confusing; it will take a little longer to write but guaranteed to save you time in the future.

We're probably going to be releasing more tips in the future so keep your eyes peeled for more advice on getting the most out of Sanity.