JSON Schema Plug-In

Einleitung

Mit dem JSON Schema Plug-In können Sie JSON-Schemata zentral im OPC Router verwalten und in Ihren Verbindungen nutzen. Das Plug-In ermöglicht es, Datenstrukturen formal zu definieren und sicherzustellen, dass ein- und ausgehende JSON-Daten einem vordefinierten Schema entsprechen. Dadurch werden Integrationsfehler reduziert – beispielsweise können eingehende JSON-Nachrichten vor der Verarbeitung validiert oder ausgehende JSON-Payloads gemäß einer festen Struktur erstellt werden. Das JSON Schema Plug-In richtet sich an Anwendungsfälle im IIoT- und Integrationsumfeld, in denen JSON als Austauschformat dient und eine konsistente Datenstruktur (etwa nach JSON Schema Standard) gewährleistet werden soll.

Schema-Verwaltung

Die Konfiguration des JSON Schema Plug-Ins erfolgt über die Schema-Verwaltung. Hier können Sie Schemata entweder eingebettet in das OPC Router Projekt hinterlegen oder einen Schema-Ordner verknüpfen. In der Schema-Verwaltung haben Sie zudem die Möglichkeit, JSON-Schemata aus bestehenden JSON-Dokumenten zu erzeugen oder Beispieldaten zu einem Schema anzeigen zu lassen.

Embedded (eingebettet): In diesem Modus werden Schemadateien direkt im OPC Router Projekt gespeichert. Sie können neue Schemata über den Editor hinzufügen oder bestehende importieren. Eingebettete Schemata werden beim Projekt-Export mitgesichert, sodass sie auf anderen Systemen ohne separaten Dateiaustausch verfügbar sind.

Linked Folder (verknüpfter Ordner): In diesem Modus verweist das Plug-In auf einen externen Ordner im Dateisystem, der JSON-Schemadateien enthält. Alle .json- und unterstützten .yaml-Dateien in diesem Ordner (und ggf. Unterordnern) werden automatisch geladen. Änderungen an den Dateien wirken sich (nach Neuladen/Neustart) auf das OPC Router Projekt aus. Dieser Modus ist praktisch, wenn Schemata von mehreren Projekten genutzt oder extern versioniert werden sollen. Beachten Sie, dass bei einem Projekt-Export nur der Pfad, nicht die Dateien selbst, gesichert wird.

AsyncAPI/OpenAPI YAML-Unterstützung: Das JSON Schema Plug-In kann neben reinen JSON-Schema-Dateien auch Schema-Definitionen im YAML-Format laden, wie sie z. B. in AsyncAPI- oder OpenAPI-Spezifikationen verwendet werden. Sie können also eine AsyncAPI- oder OpenAPI-Definition (.yaml/.yml) einbinden; das Plug-In extrahiert daraus die JSON Schema-Strukturen (z. B. definierte Message-Payloads) und behandelt sie wie reguläre Schemata. Dies erleichtert die Wiederverwendung bestehender API-Definitionen, um eintreffende JSON-Nachrichten zu validieren oder ausgehende Nachrichten entsprechend zu formatieren.

Schema-Verwaltung im JSON Schema Plug-In: Auswahl zwischen eingebetteten Schemata und verknüpftem Ordner, mit geladenen Beispielschemata.

Im Schema-Editor des Plug-Ins können Sie Schemata manuell bearbeiten oder komfortable Funktionen nutzen: Über „Schema aus JSON erstellen“ wird aus einem Beispiel-JSON automatisch ein Schema-Vorschlag generiert. Umgekehrt können Sie mit „Beispiel-JSON anzeigen“ ein gültiges JSON-Dokument auf Basis des aktuellen Schemas erzeugen – hilfreich, um die Struktur zu veranschaulichen oder zu testen. Der Editor unterstützt die gängigen Draft-Versionen des JSON Schema Standards (z. B. Draft 7 bis Draft 2020-12) und validiert die Schema-Syntax, sodass Fehler beim Bearbeiten frühzeitig erkannt werden.

Bearbeiten eines JSON-Schemas: Im Schema-Editor können Namen vergeben, Schemata importiert oder generiert und die Struktur live validiert werden.

Verwendung in Verbindungen (Transferobjekt)

Das JSON Schema Plug-In stellt ein Transferobjekt zur Verfügung, mit dem strukturierte JSON-Daten basierend auf einem ausgewählten Schema gelesen, geschrieben und validiert werden können. Das Schema wird dabei aus der Schema-Verwaltung ausgewählt. Entweder wird die neueste Version automatisch verwendet oder eine bestimmte Version manuell festgelegt.

Das Transferobjekt verwendet intern JsonPointer zur Adressierung einzelner Felder innerhalb des JSON-Dokuments. Damit lassen sich gezielt Werte lesen, schreiben oder per Patch verändern. Für komplexe Strukturen – z. B. Arrays mit Objekten – muss der JsonPointer ggf. manuell ergänzt werden, da dynamische Indexierung nicht unterstützt wird.

Hinweis: Zeigt ein Pointer direkt auf ein Array oder Objekt, wird dieses vollständig als JSON-String ausgegeben. Dynamische Indizierung mit JsonPointer (z. B. [0], [i]) ist nicht möglich. Pointer müssen ggf. manuell gesetzt werden., dass diese Features je nach Schema- und Datenkontext nur eingeschränkt oder vereinfacht validiert werden. Für zuverlässige Ergebnisse sollten komplexe Konstrukte separat geprüft werden.

Das Transferobjekt kann:

• JSON-Daten basierend auf dem Schema erzeugen
• Eingehende JSON-Daten validieren
• Bei Fehlern entweder eine strukturierte Fehlerliste zurückgeben oder den Transfer abbrechen

Optional kann eine Formatkultur gesetzt werden, die verwendet wird, um zwischen JSON Schema-Typen und .NET-Datentypen zu konvertieren.

Unterstützte JSON Schema Features

JSON Schema Feature	Unterstützt
type (object, array, ...)	✔️
properties, required	✔️
enum, const, default	✔️
pattern, format	🔶 (teilweise)¹
items (gleiches Schema)	✔️
anyOf, oneOf, allOf	🔶 (teilweise)²
if / then / else	🔶 (teilweise)²
Array of Value (String, Number, ...)	✔️
Array of Object	🔶 (teilweise)³
$ref lokal	✔️
$ref extern (HTTP)	❌
patternProperties	❌

Verwenden Sie bei Bedarf manuelle Pointer.

Hinweise:

¹ format: Nur gängige Formate wie date-time, email etc. werden berücksichtigt. Keine strikte Validierung komplexer Formate.

² anyOf, oneOf, allOf sowie if / then / else: Validierung erfolgt vereinfacht. Kombinationen mit verschachtelten Bedingungen oder optionalen Typen können zu unerwartetem Verhalten führen.

³ Array of Object: JsonPointer kann keine dynamische Adressierung wie ArrayProp/*/ItemProp verarbeiten. Verwenden Sie bei Bedarf manuelle Pointer mit direkter Zuweisung wie ArrayProp/0/ItemProp, ArrayProp/1/ItemProp, ...

Empfohlen wird, mithilfe von $ref ein Schema für das Objekt im Array separat zu definieren und zwei einzelne Transferobjekte zu projektieren. Das JSON wird dabei zweistufig verarbeitet (z. B. äußeres Objekt erzeugt Arraystruktur, inneres verarbeitet die Objekte einzeln).

Beispiel-Schemata & Samples

Die Installation liefert Beispielschemata unter Samples/, gruppiert in Ordner wie asset, event, measurement, production und refs-demo. Letztere zeigen Referenzierung zwischen Schemas mit $ref. Diese Vorlagen dienen als Hilfe zur Projektierung und einfacheren Projektierungstests. Sie sind nicht als produktionsfertige Beispiele gedacht, sondern sollen zeigen, was mit JSON Schema im OPC Router grundsätzlich möglich ist.

Beispiel:

• equipment.schema.json
• location.schema.json
• machine_state_change.schema.json
• telemetry-packet.schema.json

Zusätzlich werden "fertige" Spezifikationen mitgeliefert, z. B.:

• OPC UA WebAPI Spezifikation der OPC Foundation
• Siemens Industrial Edge Common Payload Format
• Portainer REST API

Diese Vorlagen dienen als Hilfe zur Projektierung. Wir übernehmen jedoch keine Haftung oder Gewährleistung für deren Vollständigkeit oder Aktualität. Es kann nicht garantiert werden, dass sämtliche Funktionen dieser Spezifikationen vollständig unterstützt oder korrekt interpretiert werden.

Best Practices

• Eingebettete Schemata für portable Projekte
• Verknüpfte Schemata bei externer Versionierung (z. B. Git)
• Klare Namensgebung (inkl. Version) z. B. order-v1.schema.json
• Nutzung von $ref für Wiederverwendbarkeit
• Gültigkeit regelmäßig mit Beispieldaten testen

Hinweis / Disclaimer

Achtung: JSON Schema ist ein dynamischer, sich entwickelnder Standard. Das OPC Router Plug-In unterstützt bewusst nur eine Teilmenge davon. Komplexe Features wie patternProperties, Tupel-Arrays oder externe $ref-Verweise sind nicht implementiert.

Die mitgelieferten Samples zeigen, welche Features unterstützt werden.