Skip to manual
gluon

GOL language

Migration

A Migration lists the steps from one major version to the next, so old names keep working until their removeIn version.

Model author or developer

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.

FieldPresenceShape
fromRequiredrange
toRequiredsemver
stepsRequiredarray
dependentsOptionalenum: 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.

ClassExamplesMinimum bump
Cosmetictitle, description, display, layout, synonymspatch
Additivenew type, optional property, enum value on extensible, new link, relaxed constraintminor
Breakingremove or rename, retype, optional to required, tightened constraint, multiplicity narrowed, primary key change, enum value removed, marking added to a deployed propertymajor, plus a Migration
GOL · YAML
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

Shell
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.

Contoso's 2026-03-contract-v2 Migration in the designer's YAML pane, with its validation status.
Contoso's 2026-03-contract-v2 Migration in the designer's YAML pane, with its validation status.