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:
| Resource | Stable identity | Current handle |
|---|---|---|
| Workspace | Workspace/tenant identity | Domain and display name |
| Object | object.id | object.slug |
| Attribute | attribute.id | attribute.slug |
| Select option | option.id | option.value |
| State | state.id | state.value |
| Record | record.id within its workspace and object | Optional 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​
| Class | Examples | Expected rollout |
|---|---|---|
| Additive | Optional attribute, new option, description, translation | Usually one deployment; regenerate schema-aware clients when relevant |
| Contract-changing | Slug/value rename, requiredness, cardinality, unit, rating maximum | Coordinated producer and consumer rollout |
| Destructive | Attribute/option/state deletion, relationship deletion, object deletion | Data 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​
| Change | REST impact | GraphQL impact | Webhook/integration impact |
|---|---|---|---|
| Localized name or description | Record JSON unchanged | Identifiers unchanged; descriptions may change | Display-only consumers may change |
| Object slug rename | Old slug no longer addresses the object; UUID remains valid | Root field and generated type family change | Record event type uses the new slug; ID-backed subscription remains attached |
| Attribute slug rename | Record data key changes; attribute UUID remains valid | Field, filter, order, and possibly enum type names change | Parsers using the old key must be updated |
| Option/state value rename | Old readable write handle changes; stored ID remains | Enum symbol may change | Store and route by option/state ID where durability matters |
| Option/state title change | data unchanged; display_name changes where a display template uses the attribute | Identifiers unchanged; enum value descriptions and display_name change | Records are not updated; refresh cached labels |
| Add requiredness | New writes must provide a value | Output remains nullable for historical safety | Backfill and update all writers first |
| Add uniqueness | Becomes a durable business-key contract | Field type is unchanged | Existing duplicates must be resolved; uniqueness cannot later be toggled off |
| Single/multiple change | Select 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 shapes | Coordinate all writers and generated clients |
| Delete owned attribute | Stored values are removed | Field and filters disappear | Webhook consumers and imports must stop using it first |
| Delete owner relationship | Edges and managed reverse disappear | Both traversal fields disappear | Target-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_versionis 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.