JSON Schema Plug-In

Introduction

The JSON Schema Plug-In allows you to centrally manage JSON schemas in OPC Router and use them in your connections. The plug-in enables you to formally define data structures and ensure that incoming and outgoing JSON data conforms to a predefined schema. This reduces integration errors—for example, incoming JSON messages can be validated before processing, or outgoing JSON payloads can be created according to a fixed structure. The JSON Schema Plug-In is intended for use cases in the IIoT and integration environment where JSON serves as the exchange format and a consistent data structure (e.g., according to the JSON Schema standard) must be ensured.

Schema management

The JSON Schema Plug-In is configured via schema management. Here, you can either store schemas embedded in the OPC Router project or link a schema folder. In schema management, you also have the option of generating JSON schemas from existing JSON documents or displaying sample data for a schema. Embedded: In this mode, schema files are stored directly in the OPC Router project. You can add new schemas using the editor or import existing ones. Embedded schemas are saved when the project is exported, making them available on other systems without separate file exchange. Linked Folder: In this mode, the plug-in references an external folder in the file system that contains JSON schema files. All .json and supported .yaml files in this folder (and any subfolders) are loaded automatically. Changes to the files affect the OPC Router project (after reloading/restarting). This mode is useful if schemas are to be used by multiple projects or versioned externally. Note that when exporting a project, only the path is saved, not the files themselves. AsyncAPI/OpenAPI YAML support: In addition to pure JSON schema files, the JSON Schema plug-in can also load schema definitions in YAML format, such as those used in AsyncAPI or OpenAPI specifications. This means you can include an AsyncAPI or OpenAPI definition (.yaml/.yml); the plug-in extracts the JSON Schema structures (e.g., defined message payloads) and treats them like regular schemas. This makes it easier to reuse existing API definitions to validate incoming JSON messages or format outgoing messages accordingly. Schema management in the JSON Schema Plug-In: Choose between embedded schemas and linked folders, with loaded sample schemas. In the plug-in's schema editor, you can edit schemas manually or use convenient functions: “Create schema from JSON” automatically generates a schema proposal from a sample JSON. Conversely, you can use “Show sample JSON” to generate a valid JSON document based on the current schema—useful for illustrating or testing the structure. The editor supports the current draft versions of the JSON Schema standard (e.g., Draft 7 to Draft 2020-12) and validates the schema syntax so that errors are detected early on during editing. Editing a JSON schema: In the schema editor, you can assign names, import or generate schemas, and validate the structure live.

Use in connections (transfer object)

The JSON Schema plug-in provides a transfer object that can be used to read, write, and validate structured JSON data based on a selected schema. The schema is selected from the schema management. Either the latest version is used automatically or a specific version is set manually. The transfer object uses JsonPointer internally to address individual fields within the JSON document. This allows values to be read, written, or modified via patch. For complex structures, such as arrays with objects, the JsonPointer may need to be supplemented manually, as dynamic indexing is not supported.

Note: If a pointer points directly to an array or object, it is output completely as a JSON string. Dynamic indexing with JsonPointer (e.g., [0], [i]) is not possible. Pointers may need to be set manually. Depending on the schema and data context, these features may only be validated to a limited extent or in a simplified manner. For reliable results, complex constructs should be checked separately. The transfer object can:

• Generate JSON data based on the schema
• Validate incoming JSON data
• Return a structured error list or abort the transfer in case of errors Optionally, a format culture can be set, which is used to convert between JSON schema types and .NET data types.

Supported JSON Schema Features

JSON Schema Feature	Supported
type (object, array, ...)	✔️
properties, required	✔️
enum, const, default	✔️
pattern, format	🔶 (partially)¹
items (same schema)	✔️
anyOf, oneOf, allOf	🔶 (partially)²
if / then / else	🔶 (partially)²
Array of Value (String, Number, ...)	✔️
Array of Object	🔶 (partially)³
$ref local	✔️
$ref external (HTTP)	❌
patternProperties	❌

Use manual pointers if necessary.

Notes:

¹ format: Only common formats such as date-time, email, etc. are taken into account. No strict validation of complex formats.

² anyOf, oneOf, allOf, and if / then / else: Validation is simplified. Combinations with nested conditions or optional types may lead to unexpected behavior.

³ Array of Object: JsonPointer cannot process dynamic addressing such as ArrayProp/*/ItemProp. If necessary, use manual pointers with direct assignment such as ArrayProp/0/ItemProp, ArrayProp/1/ItemProp, ...

It is recommended to use $ref to define a separate schema for the object in the array and to project two individual transfer objects. The JSON is processed in two stages (e.g., the outer object creates the array structure, the inner object processes the objects individually).

Example Schemas & Samples

The installation provides sample schemas under Samples/, grouped into folders such as asset, event, measurement, production, and refs-demo. The latter show referencing between schemas with $ref. These templates serve as an aid to project planning and simplify project planning tests. They are not intended as production-ready examples, but rather to show what is fundamentally possible with JSON Schema in OPC Router. Example:

• equipment.schema.json
• location.schema.json
• machine_state_change.schema.json
• telemetry-packet.schema.json In addition, “ready-made” specifications are provided, e.g.:

• OPC UA WebAPI specification from the OPC Foundation
• Siemens Industrial Edge Common Payload Format
• Portainer REST API These templates serve as an aid to project planning. However, we do not assume any liability or warranty for their completeness or timeliness. It cannot be guaranteed that all functions of these specifications are fully supported or correctly interpreted.

Best Practices

• Embedded schemas for portable projects
• Linked schemas for external versioning (e.g., Git)
• Clear naming (including version), e.g., order-v1.schema.json
• Use of $ref for reusability
• Regularly test validity with sample data

Note / Disclaimer

Attention: JSON Schema is a dynamic, evolving standard. The OPC Router plug-in deliberately supports only a subset of it. Complex features such as patternProperties, tuple arrays, or external $ref references are not implemented.

The samples provided show which features are supported.