Change schema safely

Use this guide when a builder needs to change an existing kind in Company Schema. Finish with the intended definition read back from the Workspace.

Before you start

A schema change starts with the current kind and the full proposed field and Interface definitions. Confirm the Workspace and identify the callers that use the fields. The builder needs authoring access. A change needing a plan also needs an authorized approver. Schema model explains field and binding rules. Keep manual follow-up visible when it cannot run as a migration step.

Preview the change

A schema change must be compared against the current definition before choosing its path.

1. Read the kind through ontology.getKind. Check that the fields match the version you intend to change.
2. Submit the proposal to ontology.migrations.preview. Read the changes, consumer impacts, classification, and proposed steps.
3. Choose the path in the classification table. Keep any non-overridable consumer remedy ahead of the schema write.

Changing reviewCode from text to number changes the field's type while its name stays the same. The field fragment shows the change. Preview checks the field's callers before classifying its impact. Keep the rest of the definition in the full proposal.

@@ -1,1 +1,1 @@{"name":"reviewCode","type":"text"}{"name":"reviewCode","type":"number"}

## Change the field type

File: `review-code-field.json` (json)

### Before
```json
{"name":"reviewCode","type":"text"}
```

### After
```json
{"name":"reviewCode","type":"number"}
```

Apply the proposal

A schema change with breaking impact needs a plan that matches the current diff. Approval prepares that plan. It does not apply the definition.

1. For a breaking change, create the plan through ontology.migrations.plan. Inspect its steps and any manual follow-up.
2. Have the authorized approver use ontology.migrations.approve. Check that the plan is approved.
3. Declare the proposal through ontology.declareKind, with the required acknowledgement or approved plan. Read the returned definition before continuing.

Checkpoints

A schema change has three checkpoints. Preview describes impact. Approval records consent to the plan. Declaration applies the change. Compare the stored fields and Interface bindings with the proposal. When a plan applies, check its applied state. A retired field stays reserved for history. A mapping marked for remap still needs follow-up. Applying the plan does not rewrite that mapping.

Success

A schema change succeeds when the current kind readback contains the intended definition and any required plan is applied. Read the kind again through its operation or the Console's Entity page. Verify a dependent Record view or caller against the changed fields. Record any manual follow-up before resuming work that depends on it. An approval alone is not the success checkpoint.

When it fails

ontology_migration_stale_plan

A schema change no longer matches the approved plan because the current definition moved. Read the kind again, preview the revised diff, and obtain a matching plan and approval. Reusing the old plan cannot approve a different change.

installed_product_incompatible

A schema change would break an active installed Product contract. Follow the named consumer's remedy: upgrade, rebind, or retire the installation as appropriate. A migration plan cannot override this incompatibility.

ontology_migration_step_failed

A schema change step failed during application. The definition write and executed steps roll back together. The plan remains approved. Inspect the named step and repair its cause before trying to apply that plan again.

Recovery

A schema change should resume from fresh evidence. Unknown impact is classified as breaking. Restore the missing impact source before deciding the change is safe. Use the Console's Entity authoring flow to review the change. For scripts, API owns access setup and syntax. Each linked operation names its available Surfaces. Read the current kind again after applying the repaired change.

Next steps

• Reusable logic explains revision bindings when a shared value rule also needs to change.
• Records and history helps operators inspect values under the applied definition.
• Inspect action runs checks work that resumes after the schema repair.