Ein produktives Objektschema weiterentwickeln
Objektdefinitionen sind aktive API-Verträge. Eine Schemaänderung kann REST-Datensatzschlüssel, generierte GraphQL-Bezeichner, Filter, Webhook-Ereignisnamen, Beschriftungen und die von allen angebundenen Systemen akzeptierten Werte ändern. Behandeln Sie sie wie ein Anwendungs-Deployment und nicht wie das Bearbeiten einer Einstellung.
Identität und Namen erfüllen verschiedene Aufgaben
Tourfold trennt stabile Identität vom aktuellen lesbaren Bezeichner:
| Ressource | Stabile Identität | Aktueller Bezeichner |
|---|---|---|
| Workspace | Workspace-/Mandantenidentität | Domain und Anzeigename |
| Objekt | object.id | object.slug |
| Attribut | attribute.id | attribute.slug |
| Select-Option | option.id | option.value |
| Status | state.id | state.value |
| Datensatz | record.id innerhalb von Workspace und Objekt | Optionaler eindeutiger fachlicher Schlüssel |
Verwenden Sie Bezeichner in Logs und interaktiven Requests. Speichern Sie IDs zusammen mit der Workspace-Identität in Integrationsmetadaten. Eine ID ohne Workspace-Kontext ist keine globale mandantenübergreifende Referenz.
Beim Klonen eines Workspaces oder Templates entstehen neue IDs für Objekte, Attribute, Optionen und Statuswerte. Erstellen Sie beim Klonen oder Übertragen eine ausdrückliche Zuordnung von Quelle zu Ziel; leiten Sie keine Gleichheit aus kopierten UUIDs ab.
Änderung vor dem Schreiben klassifizieren
| Klasse | Beispiele | Erwarteter Rollout |
|---|---|---|
| Additiv | Optionales Attribut, neue Option, Beschreibung, Übersetzung | Meist ein Deployment; schemaabhängige Clients bei Bedarf neu generieren |
| Vertragsändernd | Slug-/Wertumbenennung, Pflichtfeld, Kardinalität, Einheit, Bewertungsmaximum | Koordinierter Rollout von Produzenten und Verbrauchern |
| Destruktiv | Löschen von Attribut, Option, Status, Beziehung oder Objekt | Datenmigration, ausdrückliche Freigabe, Wiederherstellungsplan |
„Der Schreibzugriff ist erfolgreich“ bedeutet nicht, dass jede Integration kompatibel bleibt. Der Server schützt die Schemakonsistenz; Ihr Rollout schützt die Verbraucher.
Auswirkungsmatrix
| Änderung | REST-Auswirkung | GraphQL-Auswirkung | Webhook-/Integrationsauswirkung |
|---|---|---|---|
| Lokalisierter Name oder Beschreibung | Datensatz-JSON unverändert | Bezeichner unverändert; Beschreibungen können sich ändern | Reine Anzeigeverbraucher können sich ändern |
| Objekt-Slug umbenennen | Alter Slug adressiert das Objekt nicht mehr; UUID bleibt gültig | Root-Feld und generierte Typfamilie ändern sich | Datensatzereignis-type nutzt neuen Slug; ID-basiertes Abonnement bleibt verknüpft |
| Attribut-Slug umbenennen | Schlüssel in data ändert sich; Attribut-UUID bleibt gültig | Feld, Filter, Sortierung und gegebenenfalls Enum-Typname ändern sich | Parser für den alten Schlüssel müssen angepasst werden |
| Options-/Statuswert umbenennen | Alter lesbarer Schreibbezeichner ändert sich; gespeicherte ID bleibt | Enum-Symbol kann sich ändern | Für dauerhaftes Routing Options-/Status-ID speichern |
| Options-/Statustitel ändern | data unverändert; display_name ändert sich, wo eine Anzeigevorlage das Attribut verwendet | Bezeichner unverändert; Beschreibungen der Enum-Werte und display_name ändern sich | Datensätze werden nicht aktualisiert; zwischengespeicherte Beschriftungen neu laden |
| Pflichtfeld hinzufügen | Neue Schreibzugriffe müssen einen Wert liefern | Ausgabe bleibt zum Schutz historischer Daten nullable | Zuerst Bestand befüllen und alle Schreiber anpassen |
| Eindeutigkeit hinzufügen | Wird dauerhafter fachlicher Schlüsselvertrag | Feldtyp unverändert | Bestehende Duplikate bereinigen; Eindeutigkeit kann später nicht abgeschaltet werden |
| Einzel-/Mehrfachwert ändern | Select-Werte können Arrays werden. Beziehungsschreibwerte wechseln zwischen einzelner UUID/Referenz und Arrays; Lesewerte zwischen einzelner Referenz oder null und {items, page} | Feld kann zwischen Skalar/Objekt und Liste/Connection wechseln | Alle Schreiber und generierten Clients koordinieren |
| Eigenes Attribut löschen | Gespeicherte Werte werden entfernt | Feld und Filter verschwinden | Webhook-Verbraucher und Imports müssen es vorher abstellen |
| Besitzende Beziehung löschen | Kanten und verwaltete Rückbeziehung verschwinden | Beide Traversierungsfelder verschwinden | Leser auf der Zielseite verlieren die Projektion |
Abonnements für Objektdatensatz-Webhooks werden gegen die unveränderliche Objekt-ID gespeichert, obwohl
zugestellte Ereignisnamen den aktuellen Slug enthalten. Routen Sie dauerhafte Logik über
data.object.object_id, nicht nur über type.
IDs in deklarativen Änderungen verwenden
PUT /definitions/objects/{definition_ref} ersetzt alle Attribute, die dieses Objekt besitzt. Senden Sie die aktuellen
IDs des Objekts und seiner Kinder zurück:
{
"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}
}
]
}
Die IDs zeigen Tourfold, dass asset_number ein umbenanntes vorhandenes Attribut und kein neues Feld
ist. Ein Kind ohne ID und mit demselben aktuellen Slug/Wert behält ebenfalls seine Identität;
ausdrückliche IDs beseitigen jedoch Mehrdeutigkeit in generierten Provisionierungsdokumenten.
Das Auslassen eines eigenen Attributs löscht es. Verwaltete Rückbeziehungen gehören nicht dem
Zielobjekt: Lassen Sie sie in dessen PUT aus und ändern Sie sie über das deklarierende
Beziehungsattribut. Eine mitgesendete verwaltete Rückbeziehung liefert 422, statt das Eigentum zu
übertragen.
Senden Sie immer die gelesene lock_version, wenn automatisierte Provisionierung mit einem Administrator
oder einem anderen Deployment konkurrieren kann. Rufen Sie bei 409 die aktuelle Definition ab, führen
Sie sie zusammen und erstellen Sie ein neues Ersatzdokument; senden Sie kein veraltetes erneut.
Sicherer Rollout
1. Verbraucher erfassen
Suchen Sie nach aktuellem Objekt-Slug, Attribut-Slug, Options-/Statuswert, GraphQL-Operation, Webhook-Route und generiertem Client-Symbol. Berücksichtigen Sie Exporte, Low-Code-Abläufe und kundenseitige Integrationen, nicht nur Ihre Hauptanwendung.
2. Aktuellen Vertrag festhalten
Speichern Sie:
- vollständige Objektdefinition und
lock_version; - unveränderliche IDs aller geänderten Kinder;
- GraphQL-Schema und
ETag; und - repräsentative Datensätze einschließlich fehlender und grenzwertiger Werte.
Dieser Snapshot ist Nachweis für die Prüfung und Basis einer Wiederherstellung. Er verspricht nicht, dass gelöschte Daten automatisch rekonstruierbar sind.
3. Möglichst additiv ändern
Fügen Sie bei einer semantischen Migration zuerst das neue optionale Attribut hinzu. Verteilen Sie Schreiber, die altes und neues Feld befüllen, migrieren Sie Bestandsdaten und schalten Sie danach die Leser um. Löschen Sie das alte Feld erst, wenn alle Verbraucher umgestellt sind.
Eine direkte Slug-Umbenennung ist sinnvoll, wenn Sie alle Verbraucher kontrollieren und gemeinsam ausrollen können. Sie ist nicht automatisch rückwärtskompatibel, nur weil die UUID erhalten bleibt.
4. Vor Verschärfung validieren
Prüfen Sie vor Pflichtfeld, Eindeutigkeit, kleinerem Maximum oder engerer Kardinalität sämtliche Bestandsdatensätze auf Verstöße. Korrigieren Sie die Daten und verteilen Sie kompatible Schreiber zuerst. Eine Schemaeinschränkung ist die abschließende Schranke, nicht der Migrationsmechanismus.
5. Schemaabhängige Clients aktualisieren
Validieren Sie GET /graphql/schema mit If-None-Match neu. Ein geändertes Schema liefert 200 mit
neuem ETag, ein unverändertes 304. Generieren und kompilieren Sie Clients gegen das zurückgegebene
SDL, bevor Sie sie ausrollen.
6. Beobachten und abgleichen
Überwachen Sie RFC-9457-Validierungsprobleme, GraphQL-Validierungsfehler, Webhook-Fehlschläge und unerwartete Nullwerte. Führen Sie nach destruktiven oder identitätsrelevanten Änderungen einen gezielten REST-Abgleich durch; At-least-once-Webhooks ersetzen keine Prüfung des aktuellen Zustands.
Rollback ist eine weitere Schemaänderung
Das Zurückbenennen eines Slugs kann den lesbaren Bezeichner bei erhaltener UUID wiederherstellen. Löschen und Neuanlegen eines Attributs, einer Option, eines Status oder Objekts erzeugt eine neue Identität und stellt entfernte Werte oder Verknüpfungen nicht wieder her.
Definieren Sie bei destruktiven Änderungen die Wiederherstellung vorab: Exportieren Sie betroffene Datensätze, halten Sie ID-Zuordnungen fest und klären Sie, welche Beziehungen und generierten Typen rekonstruiert werden müssen.
Prüfliste
- Änderung ist additiv, vertragsändernd oder destruktiv klassifiziert.
- Jede dauerhafte Integration speichert Workspace-Kontext und unveränderliche IDs.
- Ersatzdokument enthält alle eigenen Attribute und lässt verwaltete Rückbeziehungen aus.
- Aktuelle
lock_versionwird gesendet. - Bestandsdaten erfüllen neue Einschränkungen.
- REST-Schlüssel, GraphQL-Operationen/-Codegen und Webhook-Routing haben Rollout-Verantwortliche.
- Aktuelles Schema und ETag sind gespeichert.
- Abgleich und Rollback sind beschrieben.
Für Datensatzbewegungen während des Rollouts siehe Datensätze synchronisieren.