Sanity
Learn
CoursesHandling schema changes confidentlyUpdating the schema to match imported content
Track
Sanity Developer Certification

Handling schema changes confidently

Lesson
2

Updating the schema to match imported content

Check document validation status across a whole dataset. Update schema with missing fields for content that's found in the dataset's documents.

Log in to mark your progress for each Lesson and Task

Start the Studio locally, open localhost:3333, and explore the different documents. You’ll notice that there is content that the Studio doesn’t recognize.

Start the development server with sanity dev
Open your local development Studio at http://localhost:3333

Since you have only three schema types, it’s not that hard to get a sense of what’s going on from looking through the documents. Most projects with some maturity might have a lot of schema types and a lot of content. This is where it becomes useful to use the Sanity CLI to investigate mismatches between your content and the schema that is supposed to describe it.

Run the validate documents command in your CLI
sanity documents validate

The CLI will give you a small warning about potential pitfalls with this command, if you want to skip this warning in the future, you can run the following:

sanity documents validate -y

When the command has run, you should have a list of warnings in your terminal that look like this:

Output from the command
WARN   artist  artist-justin-timberlake
├─ description ................... ⚠ Field 'description' does not exist on type 'artist'
└─ photo ......................... ⚠ Field 'photo' does not exist on type 'artist'


WARN   artist  artist-phil-collins
├─ description ................... ⚠ Field 'description' does not exist on type 'artist'
└─ photo ......................... ⚠ Field 'photo' does not exist on type 'artist'


 WARN   venue  venue-madison-square-garden
├─ city .......................... ⚠ Field 'city' does not exist on type 'venue'
└─ country ....................... ⚠ Field 'country' does not exist on type 'venue'


 WARN   venue  venue-montreux-jazz-festival
├─ city .......................... ⚠ Field 'city' does not exist on type 'venue'
└─ country ....................... ⚠ Field 'country' does not exist on type 'venue'

This means there is content for your document types in the import that the Studio’s schema doesn't describe. Let’s add these types to get rid of these warnings!

To understand what field types we should add to our document types in the schema, you can open one of the documents and look for the yellow warning “Unknown fields found.”

Explore the warning messages for “Artists” in the Studio’s document form

Here, you see that description is a plain text string, while photo is of the type image.

Add the description field to the artistType’s fields
schemaTypes/artistType.ts
defineField({
  name: 'description',
  type: 'text', // plain text that supports multiple lines
  title: 'Artist description'
}),
Add the image field called photo to the artistType
schemaTypes/artistType.ts
defineField({
  name: 'photo',
  type: 'image',
  title: 'Artist photo',
  options: {
    hotspot: true,
  },
}),

Save these changes to the schema type file. You should see the Studio reload and replace the warning with input fields with the content.

Run sanity documents validate -y to confirm that you have fewer warnings

Running the validation command should leave us with only warnings for the venue document type.

See if you manage to get rid of these warnings using the same approach as above and by updating the fields in venueType.ts

Update the fields for venueType to get rid of the validation warnings

If you did this successfully, sanity documents validate -y should output:

Validation results:
✔ Valid:    265 documents
✖ Errors:   0 documents, 0 errors
⚠ Warnings: 0 documents, 0 warnings

Great! You have now updated the schema to validate against your imported content. You are now ready to do the opposite, namely, changing the schema and updating the content accordingly.