Konsistente Benennung und Schreibweise von JSON-Feldern

Worum es geht

JSON (RFC 8259, zitiert) schränkt nur die Syntax ein: Objekte sind Name-Wert-Paare, Namen sind Strings, und Namen innerhalb eines Objekts sollten eindeutig sein. Wie Namen aussehen, ist Konvention. Googles JSON Style Guide (zitiert) verlangt, dass Eigenschaftsnamen camel-case ASCII-Strings mit definierter Semantik sind, warnt vor willkürlicher Gruppierung von Daten, stellt Enum-Werte als Strings dar und formatiert Datumsangaben als RFC-3339-Strings. Das ProtoJSON-Mapping (zitiert) serialisiert Protobuf-Feldnamen als lowerCamelCase-Schlüssel, Enums über ihre Namen, und 64-Bit-Ganzzahlen als dezimale Strings, weil viele JSON-Konsumenten sie nicht exakt darstellen können. snake_case (created_at) ist ebenso verbreitet. Entscheidend ist, dass eine Konvention über jeden Endpunkt hinweg gilt, einschliesslich Fehler-Bodies und Webhook-Payloads.

Warum es wichtig ist

Uneinheitliche Namen sind ein sichtbares Zeichen einer API, die aus mehreren Teams zusammengesetzt wurde: Clients brauchen Mapping-Code je Endpunkt, generierte SDKs erzeugen unhandliche Bezeichner, und Agenten, die die Beschreibung lesen, können Feldnamen nicht aus Mustern ableiten.

So wird es angewendet

• Die Konvention mit Beispielen im API-Style-Guide festhalten: Schreibweise, Pluralnamen für Arrays (items), Boolean-Präfixe (isActive, hasChildren), Einheiten- oder Formatsuffixe (durationSeconds, sizeBytes), Kennungsfelder, die auf Id enden.
• Mechanisch durchsetzen: ein Linter über das OpenAPI-Dokument, oder Protobuf-Feldnamensregeln plus das ProtoJSON-Mapping.
• Nach Bedeutung benennen, nicht nach Speicherung: customerId, nicht cust_fk; nicht umbenennen, wenn sich die Datenbankspalte ändert.
• Wertformate einmalig festlegen: RFC-3339-Zeitstempel mit Offset, explizite Einheitensuffixe oder ISO-8601-Dauern, Enum-Strings statt Zahlen, Geldbeträge als Strings oder ganzzahlige Kleinsteinheiten.
• Denselben Namen für dasselbe Konzept über Ressourcen hinweg verwenden; owner bei der einen Ressource und ownerId bei einer anderen ist ein Mangel.
• Als Maps verwendete JSON-Objekte anders behandeln: Ihre Schlüssel sind Daten und folgen keiner Namensregel, und die Dokumentation muss angeben, welche Objekte Maps sind.

Stolpersteine

Ein Feld umzubenennen, um seine Schreibweise zu korrigieren, ist eine Breaking Change; den neuen Namen ergänzen und den alten für eine Übergangsfrist beibehalten. Implementierungsbezogene Bezeichner wie $type oder __typename undokumentiert in einen öffentlichen Vertrag durchsickern lassen. Abkürzungen, die nur das Ursprungsteam versteht. Duplikate mit unterschiedlicher Schreibweise (userId und userID), die überleben, weil niemand lintet.