Schema Evolution

Schemas change over time. Minions handles this gracefully by preserving old data.

Migration Rules

Change	What Happens
Field added	Existing minions get the default value (or nothing)
Field removed	Old values move to _legacy
Field type changed	Incompatible values move to _legacy
Field made required	Existing minions are flagged for migration
Validation changed	Old values are NOT retroactively validated

Using migrateMinion

TypeScript

import { migrateMinion } from 'minions-sdk';

const oldSchema = [
  { name: 'name', type: 'string' },
  { name: 'age', type: 'number' },
];

const newSchema = [
  { name: 'name', type: 'string' },
  { name: 'role', type: 'string', defaultValue: 'user' },
  // 'age' removed
];

const migrated = migrateMinion(myMinion, oldSchema, newSchema);
// migrated.fields.role === 'user' (default applied)
// migrated._legacy.age === 30 (preserved from old data)

Python

from minions import migrate_minion
from minions.types import FieldDefinition

old_schema = [
    FieldDefinition(name="name", type="string"),
    FieldDefinition(name="age", type="number"),
]

new_schema = [
    FieldDefinition(name="name", type="string"),
    FieldDefinition(name="role", type="string", default_value="user"),
    # "age" removed
]

migrated = migrate_minion(my_minion, old_schema, new_schema)
# migrated.fields["role"] == "user" (default applied)
# migrated._legacy["age"] == 30 (preserved from old data)

The _legacy Namespace

When fields are removed or become incompatible, their values are preserved in _legacy. This ensures no data is silently lost during schema changes.

{
  "fields": { "name": "Alice", "role": "user" },
  "_legacy": { "age": 30 }
}