Converting string array tags to document references in Sanity schema

// schemas/tag.ts
export default {
  name: 'tag',
  type: 'document',
  fields: [
    {
      name: 'title',
      type: 'string'
    }
  ]
}

import {defineMigration, at, set, unset} from 'sanity/migrate'

export default defineMigration({
  title: 'Convert string tags to references',
  documentTypes: ['yourDocumentType'], // whatever type has the tags
  
  async *migrate(documents, context) {
    // First pass: collect all unique tag strings and create tag documents
    const uniqueTags = new Set<string>()
    
    for await (const doc of documents()) {
      if (doc.tags && Array.isArray(doc.tags)) {
        doc.tags.forEach(tag => uniqueTags.add(tag))
      }
    }
    
    // Create tag documents and build a mapping
    const tagMap = new Map<string, string>()
    for (const tagString of uniqueTags) {
      const tagId = `tag-${tagString.toLowerCase().replace(/\s+/g, '-')}`
      tagMap.set(tagString, tagId)
      
      yield {
        _type: 'tag',
        _id: tagId,
        title: tagString
      }
    }
    
    // Second pass: update documents to use references
    for await (const doc of documents()) {
      if (doc.tags && Array.isArray(doc.tags)) {
        const tagRefs = doc.tags.map(tagString => ({
          _type: 'reference',
          _ref: tagMap.get(tagString),
          _key: Math.random().toString(36).substr(2, 9)
        }))
        
        yield {
          id: doc._id,
          patch: {
            set: {
              tags: tagRefs
            }
          }
        }
      }
    }
  }
})

{
  name: 'tags',
  type: 'array',
  of: [{type: 'reference', to: [{type: 'tag'}]}]
}