Skip to main content

Evolve a live object schema

Object definitions are live API contracts. A schema write can change REST record keys, generated GraphQL identifiers, filters, webhook event names, display labels, and the values accepted from every connected system. Treat it like an application deployment, not a settings edit.

Identity and names serve different jobs​

Tourfold keeps a stable identity separate from its current readable handle:

ResourceStable identityCurrent handle
WorkspaceWorkspace/tenant identityDomain and display name
Objectobject.idobject.slug
Attributeattribute.idattribute.slug
Select optionoption.idoption.value
Statestate.idstate.value
Recordrecord.id within its workspace and objectOptional unique business-key value

Use handles in logs and interactive requests. Persist IDs and the workspace identity in integration metadata. An ID without its workspace context is not a global cross-tenant reference.

Cloning a workspace or template creates new IDs for objects, attributes, options, and states. Build an explicit source-to-target mapping during cloning or promotion; do not infer equivalence from copied UUIDs.

Classify the change before writing​

ClassExamplesExpected rollout
AdditiveOptional attribute, new option, description, translationUsually one deployment; regenerate schema-aware clients when relevant
Contract-changingSlug/value rename, requiredness, cardinality, unit, rating maximumCoordinated producer and consumer rollout
DestructiveAttribute/option/state deletion, relationship deletion, object deletionData migration, explicit approval, recovery plan

“The write succeeds” is not the same as “every integration remains compatible.” The server protects schema consistency; your rollout protects consumers.

Impact map​

ChangeREST impactGraphQL impactWebhook/integration impact
Localized name or descriptionRecord JSON unchangedIdentifiers unchanged; descriptions may changeDisplay-only consumers may change
Object slug renameOld slug no longer addresses the object; UUID remains validRoot field and generated type family changeRecord event type uses the new slug; ID-backed subscription remains attached
Attribute slug renameRecord data key changes; attribute UUID remains validField, filter, order, and possibly enum type names changeParsers using the old key must be updated
Option/state value renameOld readable write handle changes; stored ID remainsEnum symbol may changeStore and route by option/state ID where durability matters
Option/state title changedata unchanged; display_name changes where a display template uses the attributeIdentifiers unchanged; enum value descriptions and display_name changeRecords are not updated; refresh cached labels
Add requirednessNew writes must provide a valueOutput remains nullable for historical safetyBackfill and update all writers first
Add uniquenessBecomes a durable business-key contractField type is unchangedExisting duplicates must be resolved; uniqueness cannot later be toggled off
Single/multiple changeSelect values may become arrays. Relationship writes change between one UUID/reference and arrays; reads change between one reference or null and {items, page}Field can change between scalar/object and list/connection shapesCoordinate all writers and generated clients
Delete owned attributeStored values are removedField and filters disappearWebhook consumers and imports must stop using it first
Delete owner relationshipEdges and managed reverse disappearBoth traversal fields disappearTarget-side readers lose the projection

For object-record webhooks, subscriptions are stored against the immutable object ID even though delivered event names contain the current slug. Route durable logic on data.object.object_id, not only on type.

Use IDs in declarative updates​

PUT /definitions/objects/{definition_ref} replaces the full set of attributes owned by that object. Send the current object and child IDs back:

{
"slug": "equipment_asset",
"name": {
"en": {"singular": "Equipment asset", "plural": "Equipment assets"}
},
"lock_version": 7,
"attributes": [
{
"id": "10000000-0000-4000-8000-000000000001",
"slug": "name",
"type": "text",
"name": {"en": "Name"},
"config": {"is_required": true}
},
{
"id": "10000000-0000-4000-8000-000000000002",
"slug": "asset_number",
"type": "text",
"name": {"en": "Asset number"},
"config": {"is_required": true, "is_unique": true}
}
]
}

The IDs tell Tourfold that asset_number is a renamed existing attribute rather than a new field. An id-less child with the same current slug/value also keeps its identity, but explicit IDs remove ambiguity from generated provisioning documents.

Omitting an owned attribute deletes it. Managed reverse attributes are not owned by the target object: omit them from its PUT, and change them through the declaring relationship attribute. Including a managed reverse returns 422 rather than transferring ownership.

Always send the lock_version you read when automated provisioning can race with an administrator or another deployment. On 409, fetch the latest definition, reconcile, and create a new replacement document—do not replay a stale one.

A safe rollout sequence​

1. Inventory consumers​

Search for the current object slug, attribute slug, option/state value, GraphQL operation, webhook route, and generated client symbol. Include exports, low-code flows, and customer-managed integrations, not only your primary application.

2. Capture the current contract​

Store:

  • the complete object definition and lock_version;
  • immutable IDs for every changed child;
  • the GraphQL schema body and ETag; and
  • representative records, including missing and edge-case values.

This snapshot is evidence for review and a basis for recovery. It is not a promise that deleted data can always be reconstructed automatically.

3. Make the change additive when possible​

For a semantic migration, add the new optional attribute first. Deploy writers that populate both old and new fields, backfill historical records, then switch readers. Delete the old field only after every consumer has moved.

A direct slug rename is appropriate when you control all consumers and can deploy them together. It is not inherently backward-compatible merely because the UUID survives.

4. Validate before tightening​

Before adding requiredness, uniqueness, a lower maximum, or a smaller cardinality, query every existing record for violations. Correct data and deploy compatible writers first. A schema constraint is the final guard, not the migration mechanism.

5. Refresh schema-aware clients​

Revalidate GET /graphql/schema with If-None-Match. A changed schema returns 200 with a new ETag; an unchanged schema returns 304. Regenerate and compile clients against the returned SDL before rolling them out.

6. Observe and reconcile​

Monitor RFC 9457 validation problems, GraphQL validation errors, webhook failures, and unexpected nulls. Run a targeted REST reconciliation after a destructive or identity-affecting change; webhook delivery is at-least-once and is not a replacement for verifying current state.

Rollback is another schema change​

Renaming a slug back can restore a readable handle while preserving its UUID. Deleting and recreating an attribute, option, state, or object creates a new identity and does not restore removed values or links.

For destructive changes, define recovery before execution: export affected records, record ID mappings, and understand which relationships and generated types will need reconstruction.

Review checklist​

  • The change is classified as additive, contract-changing, or destructive.
  • Every durable integration stores workspace context and immutable IDs.
  • The replacement document contains all owned attributes and omits managed reverses.
  • Current lock_version is supplied.
  • Existing data satisfies new constraints.
  • REST keys, GraphQL operations/codegen, and webhook routing have rollout owners.
  • The current schema body and ETag are captured.
  • Reconciliation and rollback steps are written down.

For record movement during the rollout, use Synchronizing records.