Evolution and migrations

Describe the change

Adding a Field, changing its type and removing a relation have different effects. Before activating a new definition, inspect affected data, views, Actions and work. Stable identities make changes recognizable.

Change	Expected analysis	Verification
Add a Field	Initial value and required behavior	Creation and existing records
Change a type	Compatibility and value transformation	Data and controls
Rename a key	References and identity	Queries, views and Actions
Change a relation	Objects and cardinality	Selection and reverse links
Modify a Flow	Ongoing runs and results	Version and recovery

Prepare and review

Changes identify scope, necessary transformations and conflicts. A preview lets you examine effects before activation. Human content must not be rewritten merely because presentation changed.

Example

You require Email for new clients. Historical records without email must be identified and handled according to the chosen policy. Adding form validation alone does not make existing data conformant.

Activate and inspect

After application, verify affected objects and journeys. Installed versions, migration operations and diagnostics explain the result. Older contracts retain their interpretation instead of silently accepting newer properties.

For a published upgrade, choose the exact version and then the destination of each Space. The review distinguishes keeping current behaviour from adapting to the new version; adapting a Space requires authority over its content. Declared names stay those of the source application, even if the new version’s destinations have different names. An uncertain response resumes the same confirmation. After the upgrade is recorded, retry only opening the application if that fails: do not confirm again. Access to the new guide that needs restoration is reported separately from the recorded upgrade.

Applied examples : Evolve an existing record

Preserve Field keys and compare the new presentation before applying it to instances.

Configuration

Fragment placed in presentation.recordProfiles[]. Properties and accepted values.

{
  "key": "client",
  "definitionPaths": [
    "workspace/clients/surface/client"
  ],
  "editActionKey": "edit-client",
  "identity": {
    "title": {
      "kind": "field",
      "fieldPath": "fields/company"
    },
    "avatar": {
      "kind": "initials",
      "maximumLetters": 2
    },
    "subtitle": {
      "kind": "field",
      "fieldPath": "fields/status"
    }
  },
  "valueLabels": [
    {
      "fieldPath": "fields/status",
      "values": [
        {
          "value": "prospect",
          "label": "Prospect"
        },
        {
          "value": "active",
          "label": "Active"
        }
      ]
    }
  ],
  "card": {
    "summary": {
      "kind": "field",
      "fieldPath": "fields/notes"
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "metricKeys": [],
    "openLabel": "Open client"
  },
  "queryBindings": [],
  "metrics": [],
  "detail": {
    "primaryActionKey": null,
    "creationActionKeys": [],
    "actionKeys": [],
    "sections": [
      {
        "kind": "fields",
        "key": "follow-up",
        "label": "Client follow-up",
        "fieldPaths": [
          "fields/notes",
          "fields/status"
        ]
      }
    ],
    "settings": {
      "fieldPaths": [
        "fields/email"
      ]
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "relatedGroups": [],
    "primaryActionLabel": null
  }
}

Variation and connection

Fragment placed in forms[]. Properties and accepted values.

{
  "contract": "WorkspaceForm@2",
  "key": "edit-client",
  "label": "Edit client",
  "actionKey": "edit-client",
  "targetDefinitionPath": "workspace/clients/surface/client",
  "mode": "edit",
  "fields": [
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "company",
      "label": "Company",
      "input": "text",
      "binding": {
        "kind": "field",
        "fieldKey": "company"
      },
      "required": true,
      "ruleKeys": [],
      "options": []
    },
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "status",
      "label": "Status",
      "input": "choice",
      "binding": {
        "kind": "field",
        "fieldKey": "status"
      },
      "required": true,
      "ruleKeys": [],
      "options": [
        "prospect",
        "active"
      ]
    },
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "notes",
      "label": "Notes",
      "input": "multiline",
      "binding": {
        "kind": "field",
        "fieldKey": "notes"
      },
      "required": false,
      "ruleKeys": [],
      "options": []
    }
  ],
  "ruleKeys": []
}

UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Target object
2. Proposed change
3. Checks
4. Confirm

SurfaceClients / North StudioExample

Evolution and migrationsEvolve an existing record

Clients

NS

North StudioQuote S-1042

Needs review

Proposed change

Preserve Field keys and compare the new presentation before applying it to instances.

Data and references

Client · Need · Pricing

BackReview then confirm