Zum Hauptinhalt springen

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:

RessourceStabile IdentitätAktueller Bezeichner
WorkspaceWorkspace-/MandantenidentitätDomain und Anzeigename
Objektobject.idobject.slug
Attributattribute.idattribute.slug
Select-Optionoption.idoption.value
Statusstate.idstate.value
Datensatzrecord.id innerhalb von Workspace und ObjektOptionaler 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​

KlasseBeispieleErwarteter Rollout
AdditivOptionales Attribut, neue Option, Beschreibung, ÜbersetzungMeist ein Deployment; schemaabhängige Clients bei Bedarf neu generieren
VertragsänderndSlug-/Wertumbenennung, Pflichtfeld, Kardinalität, Einheit, BewertungsmaximumKoordinierter Rollout von Produzenten und Verbrauchern
DestruktivLöschen von Attribut, Option, Status, Beziehung oder ObjektDatenmigration, 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​

ÄnderungREST-AuswirkungGraphQL-AuswirkungWebhook-/Integrationsauswirkung
Lokalisierter Name oder BeschreibungDatensatz-JSON unverändertBezeichner unverändert; Beschreibungen können sich ändernReine Anzeigeverbraucher können sich ändern
Objekt-Slug umbenennenAlter Slug adressiert das Objekt nicht mehr; UUID bleibt gültigRoot-Feld und generierte Typfamilie ändern sichDatensatzereignis-type nutzt neuen Slug; ID-basiertes Abonnement bleibt verknüpft
Attribut-Slug umbenennenSchlüssel in data ändert sich; Attribut-UUID bleibt gültigFeld, Filter, Sortierung und gegebenenfalls Enum-Typname ändern sichParser für den alten Schlüssel müssen angepasst werden
Options-/Statuswert umbenennenAlter lesbarer Schreibbezeichner ändert sich; gespeicherte ID bleibtEnum-Symbol kann sich ändernFür dauerhaftes Routing Options-/Status-ID speichern
Options-/Statustitel änderndata unverändert; display_name ändert sich, wo eine Anzeigevorlage das Attribut verwendetBezeichner unverändert; Beschreibungen der Enum-Werte und display_name ändern sichDatensätze werden nicht aktualisiert; zwischengespeicherte Beschriftungen neu laden
Pflichtfeld hinzufügenNeue Schreibzugriffe müssen einen Wert liefernAusgabe bleibt zum Schutz historischer Daten nullableZuerst Bestand befüllen und alle Schreiber anpassen
Eindeutigkeit hinzufügenWird dauerhafter fachlicher SchlüsselvertragFeldtyp unverändertBestehende Duplikate bereinigen; Eindeutigkeit kann später nicht abgeschaltet werden
Einzel-/Mehrfachwert ändernSelect-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 wechselnAlle Schreiber und generierten Clients koordinieren
Eigenes Attribut löschenGespeicherte Werte werden entferntFeld und Filter verschwindenWebhook-Verbraucher und Imports müssen es vorher abstellen
Besitzende Beziehung löschenKanten und verwaltete Rückbeziehung verschwindenBeide Traversierungsfelder verschwindenLeser 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_version wird 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.