Ein Mitgliedsname ist noch kein Pfad
Stellen Sie sich ein JSON-Objekt mit dem Schlüssel draft/a~b vor. Sein Wert enthält ein weiteres Objekt mit state. Der Schrägstrich gehört zum Schlüssel und erzeugt keine zusätzliche Ebene. Ein JSON Pointer bezeichnet dagegen einen Wert über durch Schrägstriche getrennte Referenzabschnitte. /orders/0/item könnte ein Element innerhalb eines Arrays adressieren; 0 ist dort ein Index. Wer einen rohen Namen ungeprüft in einen Pointer kopiert, trifft möglicherweise einen anderen Wert oder erhält einen Fehler.
RFC 6901 definiert zwei Maskierungen innerhalb jedes Abschnitts: Eine Tilde wird zu ~0 und ein Schrägstrich zu ~1. Vor jedem Abschnitt des vollständigen Pointers steht außerdem ein Schrägstrich; der leere Pointer bezeichnet das gesamte Dokument. Diese Schreibweise betrifft die Zeichen des Pfades und verändert weder den Zielwert noch das JSON-Objekt. Nutzen Sie das Werkzeug für Tokens, wenn Sie einen Pfad aus einem Datensatz oder einem fremden Mitgliedsnamen zusammensetzen.
Das Beispiel Abschnitt für Abschnitt aufbauen
Für draft/a~b ersetzen Sie zuerst die Tilde durch ~0 und danach den Schrägstrich durch ~1. Das maskierte Token lautet draft~1a~0b. Mit führendem Schrägstrich und dem getrennten Mitglied state entsteht /draft~1a~0b/state. Der eingebettete Umwandler erledigt genau den Tokenschritt. Er ergänzt absichtlich keinen führenden Schrägstrich, weil das Token auch an anderer Stelle in einem längeren Pointer stehen könnte. Vergleichen Sie sein Ergebnis mit den drei Stufen der Abbildung.
Das Gegenwerkzeug ersetzt ~1 durch Schrägstrich, bevor es ~0 durch Tilde ersetzt. Die Reihenfolge ist wichtig: Würde ~01 zunächst zu ~1 und dann erneut zu einem Schrägstrich, änderte sich der ursprüngliche Name. Ein Pointer-Token ist außerdem keine URL-Prozentkodierung. Steht der Pointer in einem URL-Fragment, gelten für diese äußere Ebene weitere Kodierungsregeln. Halten Sie Pointer-Syntax und URL-Syntax bei der Fehlersuche in Links oder APIs auseinander.
- Rohschlüssel: draft/a~b
- Maskiertes Token: draft~1a~0b
- Ganzer Pfad: /draft~1a~0b/state
Was das Abflachen tatsächlich liefert
Das Werkzeug zum Abflachen durchläuft ein JSON-Objekt und schreibt Endwerte unter Schlüssel, die wie vollständige JSON Pointer aussehen. Liegt state unter draft/a~b, entsteht ein flacher Eintrag /draft~1a~0b/state mit demselben Endwert. Das vereinfacht Vergleiche, Listen und Exporte verschachtelter Daten. Das Gegenwerkzeug liest die Pfadschlüssel und baut das Objekt wieder auf, sofern die Pfade einander nicht widersprechen. Ein flacher Eintrag bleibt aber ein JSON-Objektmitglied und ist keine automatische Abfrage.
Diese Implementierung behandelt Arrays als Endwerte; sie erzeugt keine einzelnen Einträge für /0 und /1. Leere Objekte sind ebenfalls Endwerte. Ein allgemeiner JSON Pointer kann zwar einen Arrayindex ansprechen, die flache Ansicht hier zählt ihn nur nicht auf. Falls /a einen einfachen Wert festlegt und /a/b zugleich ein Unterobjekt verlangt, muss die Rekonstruktion den Konflikt ablehnen. Bewahren Sie das Ausgangs-JSON auf, bevor Sie Pfadschlüssel von Hand bearbeiten.
Ein verlässlicher Ablauf mit Pfaddaten
Beginnen Sie mit gültigem JSON und entscheiden Sie, ob Sie eine einzelne Adresse oder eine vollständige flache Ansicht brauchen. Für eine Adresse zerlegen Sie die beabsichtigte Route in tatsächliche Mitgliedsnamen, maskieren jeden Namen einzeln und verbinden die Tokens mit führenden Schrägstrichen. Maskieren Sie nicht den gesamten Pointer auf einmal: Dann würden auch seine Trennzeichen zum Schlüsseltext. Für viele Endwerte können Sie das Objekt abflachen und die erzeugten Schlüssel vor der Weitergabe prüfen.
Beim Wiederherstellen muss jeder flache Schlüssel mit einem Schrägstrich beginnen und gültige ~-Sequenzen besitzen. Achten Sie auf doppelte oder widersprüchliche Zuweisungen, Arrays als Endwerte und wörtliche Namen mit Punkten oder Schrägstrichen. Testen Sie den Rückweg an einem kleinen Objekt mit beiden Sonderzeichen und vergleichen Sie die geparsten JSON-Strukturen statt der Einrückung. Der Standard beschreibt Pointer; die konkrete Strategie des Abflachens ist eine Eigenschaft dieses lokalen Werkzeugs.