Where it goes
Contoso keeps 2026-03-contract-v2 in migrations/2026-03-contract-v2.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in lowercase kebab-case. The name must be unique among the package's Migration resources.
Limits
Three steps run today: renameType, renameProperty and renameLinkRole, each with an alias for the old name. The validator refuses retype, splitType, mergeTypes, moveType, dropProperty and primary-key changes with GLN-E603.
Fields
The keys under spec. Nested shapes follow MigrationSpec in the GOL JSON Schema.
| Field | Presence | Shape |
|---|---|---|
from | Required | range |
to | Required | semver |
steps | Required | array |
dependents | Optional | enum: acknowledge, fail |
Syntax and rules
The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.
12. Compatibility and Migration
The validator diffs two versions and classifies every change.
| Class | Examples | Minimum bump |
|---|---|---|
| Cosmetic | title, description, display, layout, synonyms | patch |
| Additive | new type, optional property, enum value on extensible, new link, relaxed constraint | minor |
| Breaking | remove or rename, retype, optional to required, tightened constraint, multiplicity narrowed, primary key change, enum value removed, marking added to a deployed property | major, plus a Migration |
kind: Migration
metadata: { name: 2026-10-merge-void-state }
spec:
from: "2.x"
to: 3.0.0
steps:
- renameProperty: { type: procurement.Contract, from: endDate, to: expiryDate }
- retype:
{ ref: "procurement.Contract#value", to: "std::Money", cast: "gluon.money(old, 'EUR')" }
- mapEnum: { type: procurement.ContractState, from: void, to: expired }
- dropProperty: { ref: "procurement.Contract#legacyCode", after: backup }
- backfill: { ref: "procurement.Contract#region", expr: "self.supplier.country.region" }
- splitType / mergeTypes / moveType / renameType / renameLinkRole
dependents: acknowledge # every view, action, policy, app using a changed element is listed in the report
Compatibility window. Every breaking step keeps the old shape usable until the removeIn version of the element it changes (default: the next major after to). renameProperty, renameType and renameLinkRole register the old name as an alias: reads, writes, CEL, views, MCP tool schemas and prompts accept both names, and the API and MCP manifests list the old name as deprecated with its removeIn. retype keeps the old representation readable through the cast in reverse where one exists. dropProperty and mergeTypes are the only steps that cannot be aliased; they are refused while any deployed consumer still references the element (GLN-E611), so the deployment page's consumer check is the gate. Migrations run expand, migrate, contract: the new version is deployed while the store still serves the old shape (expand), backfills run as resumable jobs with progress on the deployment page (migrate), and the old shape is removed only at removeIn (contract). Two audiences on two versions therefore always read one store.
Supported in the first release. Additive changes, and renameProperty, renameType and renameLinkRole with aliases. retype, splitType, mergeTypes, moveType, dropProperty and a primary-key change are recognised by the schema but refused by the validator with GLN-E603 until their expand, migrate, contract machinery ships; a proposal that needs one is blocked, not deferred to runtime. An alias that collides with an existing member name is GLN-E604. A cast is applied forward only; the old representation is served from the stored value, never by inverting the cast.
Check your package
gluon validate examples/contoso
gluon test examples/contoso
validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.
