Logo

Schema Migrations

As your organisation's requirements evolve, you may need to update your schemas. Schema migrations allow you to transform existing model card data from one schema version to another, without requiring model owners to manually re-enter their information.

Only administrators will have the following options available to them.

Common questions this page answers:

  • How do I migrate models to a new schema version?
  • What is a schema migration plan?
  • What is the difference between draft and final migrations?

When to use schema migrations

Use migrations when you've updated a schema and need to transform existing model card data to match.

Common scenarios:

  • You've updated a schema to add new required fields
  • You're reorganising the section structure of a schema
  • You're retiring an old schema and moving models to a newer version

How migrations work

A migration plan maps each question from a source schema to either a new location in the target schema or marks it for deletion. For each question in the source, you specify one of two actions:

  • Move - The answer is copied from the source location to a specified location in the target schema
  • Delete - The answer is discarded and not carried over to the target schema

The migration plan preserves all existing data that you choose to move, while allowing you to restructure how it is organised in the new schema.

Comparing schemas

Compare two schemas side by side to identify differences before planning a migration.

  1. Navigate to Schemas from the navigation sidebar
  2. Select Compare
  3. Fill in the comparison schemas:
    • Source Schema: The schema you are migrating from
    • Target Schema: The schema you are migrating to

Creating a migration plan

Create a migration plan from the Schemas navigation item by mapping source questions to target locations.

  1. Navigate to Schemas from the navigation sidebar
  2. Select Migrations
  3. Click New schema migration plan
  4. Fill in the migration schemas:
    • Source Schema: The schema you are migrating from
    • Target Schema: The schema you are migrating to
  5. Click Begin migration to proceed to the migration details screen.
  6. Fill in the migration details:
    • Migration name: A descriptive name for the migration (e.g. "v1 to v2 model card migration")
    • Migration description: What this migration does and why
  7. With the migration details saved, you can now map each question. For each question in the source schema, specify:
    • Move: Map it to a path in the target schema
    • Delete: Mark it for removal
  8. Once all questions have been mapped, verify the intended actions under View Actions.
  9. Save as Draft (for testing) or Final (ready to use)

Draft vs final

  • Draft migrations can be edited and tested but cannot be applied to models
  • Final migrations are locked and can be applied to models

It is recommended to save as a draft first, verify the mappings are correct, and then mark as final when ready.

Applying a migration

Once finalised, a migration plan can be applied to individual models that use the source schema:

  • Models with the source schema will display "There is a migration available for this model." with a Migrate button
  • Model owners may then Select a Migration Plan
  • This transforms the model's existing model card data according to the migration plan and switches the model to the target schema

Note: Applying a migration creates a new model card version. The previous version is preserved in the model's history, so you can always see what the data looked like before the migration.

Best practices

Test migrations as drafts, migrate incrementally, and communicate changes to model owners.

  • Test with a draft first: Create the migration as a draft and review the mappings carefully before finalising
  • Migrate incrementally: If you're making large changes, consider breaking them into smaller migration steps
  • Communicate with model owners: Let them know a migration is happening and that they may need to fill in any new fields that don't have mappings from the old schema
  • Check after migration: Verify that the migrated data appears correctly in the model card form

Viewing existing migrations

View all migration plans and their status from the Schemas navigation item:

  1. Navigate to Schemas from the navigation sidebar
  2. Select Migrations
  3. The list shows all migrations with their name, source schema, target schema, and draft/final status

Related pages

Copyright © Crown Copyright 2026.