Get help on Discord

How to Change the Name of a Document Type

9 replies
Last updated: Jun 11, 2022
Does anyone know of an easy way to rename a document name?
AI Update

I think you're asking about renaming a document type (like changing "post" to "article"), but let me cover a few scenarios since "document name" could mean different things:

If you want to rename a document type (the schema _type):

This is tricky because the _type field is immutable - it cannot be changed once a document is created. According to the official migration documentation, you cannot use at('_type', set('newType')) in a migration script.

The recommended approach is:

  1. Export your dataset:
sanity dataset export production backup.tar.gz

  1. Extract and edit the NDJSON file inside the tar.gz archive - manually change the _type values in the documents

  2. Delete the old documents from your dataset (those with the old type)

  3. Import the modified dataset:

sanity dataset import backup.tar.gz production
  1. Update your schema files to use the new document type name

This is admittedly manual, but it's the safest way to handle this since _type, _id, _createdAt, and other underscore-prefixed fields are system-managed and immutable.

If you want to rename a field (like "title" to "heading"):

This is much easier! You can use the migration tooling with defineMigration:

// migrations/rename-title-field/index.ts
import {defineMigration, at, setIfMissing, unset} from 'sanity/migrate'

const from = 'title'
const to = 'heading'

export default defineMigration({
  title: 'Rename title field to heading',
  documentTypes: ['post'], // specify your document type
  
  migrate: {
    document(doc, context) {
      return [
        at(to, setIfMissing(doc[from])),
        at(from, unset())
      ]
    }
  }
})

Then run:

# Test first (dry run)
sanity migration run rename-title-field

# Execute the migration
sanity migration run rename-title-field --no-dry-run

Don't forget to update your schema definition to use the new field name!

If you just want to change the display label:

If you only want to change what's shown in Studio (not the actual field name in your data), just update the title property in your schema:

defineType({
  name: 'post', // this stays the same
  type: 'document',
  title: 'Blog Article', // change this freely - it's just the display name!
})

This requires no migration at all since it's just a UI label.

Check out the content migration cheat sheet for more common migration patterns, and always backup your dataset before running migrations!

By that do you mean the 
_type
?
I think so.
More like the 
name
I want to restructure my schema by renaming the 
name
of documents
I realized this wasn’t as obvious as I expected, because renaming the 
name
results in empty data
The 
name
specified in the schema is what becomes the document’s 
_type
. So this:

export default {
  name: 'post',
  title: 'Post',
  type: 'document',
  fields: [
    // ...
  ]
}
Will result in all those documents having a 
_type
of 
post
. This is currently the suggested way to change document types. We’re looking at simplifying things.
Some sort of CLI tool would make this so easy 🤤
I will give that a try, thanks
user A
!
or if this were in Studio that would make Sanity flow perfect

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?