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.