Skip to content

ADR-007-data-and-raw-fields.adoc

Latest commit

 

History

History
46 lines (33 loc) · 2.54 KB

ADR-007-data-and-raw-fields.adoc

File metadata and controls

46 lines (33 loc) · 2.54 KB

ADR-007: Renaming Payload to Data and Adding Raw Field

Kontext

Im Zuge der Definition des neuen JSON-Output-Schemas (siehe ADR-006) wurde Feedback gesammelt, das zwei wesentliche Verbesserungen vorschlägt:

  1. Ambiguität des Feldes payload: Der Begriff payload wird in MQTT- und Messaging-Kontexten häufig für den gesamten Nachrichteninhalt verwendet. Die Verwendung von payload für die spezifischen, decodierten Hex-Daten kann daher zu Verwirrung führen.

  2. Bedarf an Rohdaten: Für Debugging-Zwecke und fortgeschrittene Analysen ist es notwendig, Zugriff auf die ursprüngliche, unveränderte Nachricht zu haben, wie sie vom Signalduino-Gerät empfangen wurde (z.B. der komplette MU;…​- oder MC;…​-String), bevor irgendeine Verarbeitung oder Parsing stattgefunden hat.

Entscheidung

Wir passen das in ADR-006 definierte Schema wie folgt an:

  1. Umbenennung payload zu data: Das Feld, das bisher payload hieß und die bereinigten Hex- oder Binärdaten (ohne Preamble) enthielt, wird in data umbenannt.

  2. Einführung des Feldes raw: Es wird ein neues Feld raw auf der obersten Ebene des JSON-Objekts eingeführt. Dieses Feld enthält den ursprünglichen Nachrichten-String, der an den Parser übergeben wurde.

Aktualisierte Datenstruktur

Konsequenzen

Positive Konsequenzen

  • Klarere Semantik: data ist ein neutralerer Begriff für den Dateninhalt und vermeidet die Überladung des Begriffs payload.

  • Verbesserte Debugging-Möglichkeiten: Durch das raw-Feld können Entwickler und User jederzeit nachvollziehen, was genau vom Gerät empfangen wurde, und Parser-Fehler leichter diagnostizieren.

  • Vollständigkeit: Keine Information geht verloren; sowohl die Rohdaten als auch die interpretierten Daten stehen zur Verfügung.

Negative Konsequenzen

  • Breaking Change: Dies ändert das gerade in ADR-006 vorgeschlagene Schema. Da ADR-006 jedoch noch neu ist, sollte der Anpassungsaufwand gering sein. Code, der bereits payload verwendet, muss auf data umgestellt werden.

Alternativen

  • Beibehaltung von payload: Wurde verworfen, um die Ambiguität aufzulösen.

  • raw als Objekt: Es wurde erwogen, raw strukturierter zu gestalten, aber für die einfache Nachvollziehbarkeit ist der originale String am wertvollsten.