Zum Hauptinhalt springen
Version: 5.6

JSON Schema Transferobjekt

Zweck und Funktion​

Das JSON Schema Transferobjekt dient zur strukturierten Verarbeitung von JSON-Daten anhand eines zuvor ausgewählten JSON-Schemas. Es kann JSON-Daten lesen, schreiben, patchen und gegen das zugewiesene Schema validieren. Das Objekt wird innerhalb einer Verbindung im OPC Router projektseitig eingebunden und nutzt ein Schema aus der zentralen Schema-Verwaltung.

Schema-Auswahl​

Beim Konfigurieren des Transferobjekts wählen Sie ein Schema aus der Verwaltung. Zur Verfügung stehen dabei:

  • Neueste Version verwenden: Das Transferobjekt verwendet immer die höchste verfügbare Version dieses Schemas (z. B. bei projektierter Migration).
  • Feste Version verwenden: Eine definierte Version wird fest zugewiesen, um stabile Verarbeitung zu gewährleisten.

Zugriff mit JsonPointer​

Zur Adressierung einzelner Felder innerhalb des JSON-Dokuments wird der Standard JsonPointer (RFC 6901) verwendet. Damit lassen sich gezielt Felder adressieren und deren Werte lesen, überschreiben oder patchen.

Beispiel:

{
  "equipment": {
    "id": "EQ-01",
    "status": "active"
  }
}

JsonPointer equipment/status adressiert das Feld "active".

Hinweis: Zeigt ein Pointer direkt auf ein Array oder Objekt, wird dieses vollständig als JSON-String ausgegeben.

Einschränkungen bei Arrays​

JsonPointer erlaubt keine dynamische Adressierung von Elementen in Arrays (z. B. array/*/property). Bei Bedarf muss:

  • entweder direkt mit festen Indizes gearbeitet werden (z. B. array/0/property), oder
  • empfohlen: das Objekt im Array separat schematisiert und mit einem eigenen Transferobjekt verarbeitet werden.

Operationen​

Lesen​

Das Transferobjekt extrahiert Werte aus JSON-Daten anhand der konfigurierten Pointer und stellt diese als Datenfelder zur Verfügung.

Schreiben​

Zur Laufzeit werden Datenwerte aus anderen Objekten übernommen und entsprechend dem Schema in ein neues JSON-Dokument geschrieben.

Patchen​

Bestehende JSON-Daten werden an bestimmten Stellen aktualisiert, ohne das gesamte Dokument neu zu erzeugen.

Validierung​

Das Transferobjekt kann eingehende oder erzeugte JSON-Daten gegen das zugewiesene Schema prüfen. Dabei kann das Verhalten bei einer Schema-Verletzung wie folgt konfiguriert werden:

  • Fehlerliste erzeugen: Validierungsfehler werden gesammelt und als Liste von Items bereitgestellt.
  • Abbruch bei Fehler: Bei der ersten Verletzung wird der Transfer gestoppt und eine Fehlermeldung erzeugt.

Formatkultur und Typkonvertierung​

Für Typumwandlungen zwischen .NET-Typen (wie DateTime, int, double) und den JSON Schema-Datentypen (wie string, number) kann im Transferobjekt eine Formatkultur ausgewählt werden. Diese bestimmt u. a.:

  • Datums- und Zeitformatierung (z. B. dd.MM.yyyy vs. ISO-Format)
  • Dezimaltrennzeichen (z. B. Komma vs. Punkt)
  • Sprachabhängige Formatkonventionen

Manuelle JsonPointer-Erweiterung​

In Fällen, bei denen die automatische Zuordnung von JsonPointer-Einträgen nicht möglich ist (z. B. bei komplexen oder verschachtelten Strukturen), können zusätzliche Pointer manuell ergänzt werden. Dies betrifft insbesondere:

  • Arrays mit mehreren gleichartigen Objekten
  • Referenzierte Subschemata via $ref

Hinweise​

  • Das Transferobjekt funktioniert nur mit gültigen, vollständig geladenen Schemata.
  • Alle verwendeten Pointer müssen eindeutig auf ein Datenfeld im JSON-Schema zeigen.
  • Optional definierte Felder können leer bleiben, Pflichtfelder (laut required) müssen zur Laufzeit belegt sein.

Beispielverwendung​

Ein Transferobjekt liest eine Temperaturmeldung ein, die gegen das Schema temperature.schema.json validiert wird. Anschließend werden Felder wie value, unit und timestamp extrahiert und an eine SQL-Verbindung weitergegeben.

Alternativ erzeugt ein anderes Transferobjekt eine Maschinenstatusmeldung gemäß machine_state_change.schema.json, bei dem alle erforderlichen Felder mit Daten belegt und optional weitere ergänzt werden.