schema_breaking_change

HTTP 409 · code: "schema_breaking_change" · type: https://docs.formfeed.dev/errors/schema-breaking-change

Das Veröffentlichen einer Version, das Verschieben eines Release Channels, das Promoten seines Canary oder das Zurückrollen würde eine Version live schalten, deren gespeichertes Datenschema Daten ablehnt, die die aktuelle Version annimmt. Die Anfrage hat nichts geändert.

Beispiel

{
  "type": "https://docs.formfeed.dev/errors/schema-breaking-change",
  "title": "Schema change breaks callers",
  "status": 409,
  "detail": "Publishing version 8 would break callers of the current version: \"customer.email\" is now required (and 1 more). Pass allow_breaking to go ahead",
  "code": "schema_breaking_change",
  "breaking": [
    {
      "path": "customer.email",
      "pointer": "/properties/customer/properties/email",
      "kind": "field-became-required",
      "breaking": true,
      "message": "\"customer.email\" is now required"
    },
    {
      "path": "status",
      "pointer": "/properties/status",
      "kind": "enum-values-removed",
      "breaking": true,
      "message": "\"status\" no longer accepts \"draft\""
    }
  ],
  "safe": [],
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Feld	Bedeutung
breaking	Jede brechende Änderung, mit dem Feld-path, einem JSON-pointer in das Schema, ihrer Art (kind) und einer lesbaren message
safe	Die Änderungen, die Aufrufer nicht brechen, für das vollständige Bild

Häufige Ursachen

• POST /templates/{id}/versions/{number}/publish für eine Version, deren Schema ein Pflichtfeld hinzufügt, ein Feld zur Pflicht macht, einen Typ einengt oder einen Enum-Wert entfernt.
• POST /templates/{id}/versions mit "publish": true und einem solchen Schema.
• PUT /templates/{id}/channels/{name} mit einer solchen Haupt- oder Canary-Version, sowie promote oder rollback auf eine.
• formfeed templates push --publish oder --channel und formfeed channels set|promote|rollback; die CLI gibt die Änderungen aus und endet mit Exit-Code 1.

Die Prüfung lehnt nur ab, wenn beide Versionen ein Datenschema speichern. Ist auf einer Seite das Schema abgeleitet, stehen die Änderungen als Warnung in schema_check. Was als brechend gilt listet alle Regeln.

So beheben Sie es

• Wenn Aufrufer wirklich brechen würden: Ändern Sie das Schema so, dass das neue Feld optional ist, oder behalten Sie den alten Typ oder Enum-Wert, und legen Sie eine neue Version an.
• Wenn jeder Aufrufer schon sendet, was das neue Schema verlangt: Wiederholen Sie die Anfrage mit "allow_breaking": true (--allow-breaking in der CLI, Trotzdem veröffentlichen im Editor, allowBreaking / allow_breaking in den SDKs).
• Erzeugen Sie danach Ihre Typen mit formfeed types neu, damit Ihr Code das neue Schema sieht. Siehe Typisierte Vorlagendaten.

Wiederholen?

Nein. Dieselbe Anfrage liefert bei einer Wiederholung dieselbe Antwort; ändern Sie zuerst das Schema oder senden Sie allow_breaking. Senden Sie mit dem POST einen Idempotency-Key, verwenden Sie einen neuen: Eine 4xx-Antwort wird 24 Stunden unter ihrem Schlüssel gespeichert.