Safe Schema Changes Guide

Learn how to modify component schemas safely without breaking existing content.

Overview

Schema changes can affect existing content. This guide helps you:

Plan schema migrations
Test changes before rollout
Migrate content safely
Roll back if needed

Safe vs Risky Changes

Safe Changes ✅

Adding optional fields
Adding new components
Changing field descriptions/help text
Renaming display names (not technical names)
Adding validation to new fields

Risky Changes ⚠️

Renaming field technical names
Changing field types
Adding required fields to existing components
Removing fields
Changing validation on existing fields

Dangerous Changes ❌

Deleting components in use
Removing required fields
Changing field type (text → number)
Breaking nested component references

Safe Change Process

Adding Optional Field

Add a new "subtitle" field to blog_post component:
1. Get current blog_post schema
2. Add subtitle as optional text field
3. Update component
4. Test on one story
5. Roll out to all stories

Result: Existing stories unaffected, new field available.

Adding New Component

Create new "testimonial" component
No migration needed - start using in new content

Risky Change Process

Renaming Field (Technical Name)

Wrong way: Just rename field ❌

Breaks all existing content
Data appears lost

Right way:

To rename "old_field" to "new_field":
1. Add new_field to component
2. Get all stories using this component
3. Copy data from old_field to new_field
4. Verify all content migrated
5. Remove old_field after 30 days

Changing Field Type

Example: Text → Richtext

To change "description" from text to richtext:
1. Add new field "description_rich" (richtext)
2. For all stories:
   - Copy description to description_rich
   - Wrap in <p> tags if needed
3. Verify migration
4. Remove old "description" field
5. Rename "description_rich" to "description"

Adding Required Field

Wrong way: Mark existing field as required ❌

Breaks validation on all existing content

Right way:

To make "category" required:
1. Add field as optional first
2. Identify stories missing category
3. Bulk update to add default category
4. Verify all stories have category
5. Mark field as required

Migration Workflows

Field Type Migration

Migrate blog_post "tags" from text to multi-option:
1. Create new datasource "blog_tags"
2. Get all unique tag values from existing stories
3. Add each as datasource entry
4. Add new field "tags_new" (multi-option from datasource)
5. For each story:
   - Parse old tags (comma-separated)
   - Map to datasource entries
   - Save to tags_new field
6. Verify migration
7. Remove old tags field
8. Rename tags_new to tags

Component Replacement

Replace old "hero" with new "hero_v2":
1. Create hero_v2 component
2. Get all stories using old hero
3. For each story:
   - Create equivalent hero_v2 block
   - Map fields (title → headline, etc.)
   - Replace hero with hero_v2
4. Verify all migrations
5. Archive old hero component

Testing Schema Changes

Test Environment

Before making changes:
1. Duplicate space as "staging"
2. Make schema changes in staging
3. Test with real content copies
4. Verify frontend renders correctly
5. If successful, apply to production

Gradual Rollout

For major changes:
1. Update component schema
2. Test on 1 story
3. If good, test on 10 stories
4. If good, test on 100 stories
5. Monitor for issues
6. Roll out to all stories

Rollback Strategy

Before Making Changes

Before modifying "product" component:
1. Export current component schema
2. List all stories using component
3. Export sample stories
4. Document migration plan
5. Set rollback deadline

If Something Breaks

To rollback schema change:
1. Stop migration immediately
2. Restore component from export
3. Check which stories were updated
4. Restore affected stories from backup
5. Investigate what went wrong
6. Plan safer migration approach

Best Practices

Always test first - Use duplicate component or space
Gradual changes - One field at a time
Keep old fields - Don't delete immediately
Verify migrations - Check all content migrated correctly
Document changes - Keep schema changelog
Communicate - Warn editors about changes
Backup first - Export before major changes
30-day buffer - Keep deprecated fields for 30 days

Migration Checklist

Schema Change Checklist:
□ Change documented
□ Impact assessed (how many stories affected)
□ Test plan created
□ Backup created
□ Staging environment tested
□ Migration script ready
□ Rollback plan documented
□ Team notified
□ Change deployed
□ Content migrated
□ Verification completed
□ Old fields deprecated (not deleted)
□ 30-day review scheduled

Need help with schema changes? Ask Claude to plan a safe migration strategy for your component updates!