Skip to main content
Version: 5.5

JSON Schema Transfer Object

Purpose and Function​

The JSON Schema Transfer Object is used for structured processing of JSON data based on a previously selected JSON schema. It can read, write, patch, and validate JSON data against the assigned schema. The object is integrated into a connection in OPC Router on the project side and uses a schema from the central schema management.

Schema Selection​

When configuring the transfer object, select a schema from the management. The following options are available:

  • Use latest version: The transfer object always uses the highest available version of this schema (e.g., for planned migration).
  • Use fixed version: A defined version is permanently assigned to ensure stable processing.

Access with JsonPointer​

The standard JsonPointer (RFC 6901) is used to address individual fields within the JSON document. This allows you to address specific fields and read, overwrite, or patch their values. Example:

{
  “equipment”: {
    “id”: “EQ-01”,
    “status”: ‘active’
  }
}

JsonPointer equipment/status addresses the field “active”.

Note: If a pointer points directly to an array or object, it is output in its entirety as a JSON string.

Restrictions on arrays​

JsonPointer does not allow dynamic addressing of elements in arrays (e.g., array/*/property). If necessary, you must either:

  • work directly with fixed indexes (e.g., array/0/property), or
  • recommended: schematize the object in the array separately and process it with its own transfer object.

Operations​

Reading​

The transfer object extracts values from JSON data using the configured pointers and makes them available as data fields.

Writing​

At runtime, data values are taken from other objects and written to a new JSON document according to the schema.

Patching​

Existing JSON data is updated at specific points without regenerating the entire document.

Validation​

The transfer object can check incoming or generated JSON data against the assigned schema. The behavior in the event of a schema violation can be configured as follows:

  • Generate error list: Validation errors are collected and provided as a list of items.
  • Abort on error: The transfer is stopped and an error message is generated when the first violation occurs.

Format culture and type conversion​

A format culture can be selected in the transfer object for type conversions between .NET types (such as DateTime, int, double) and JSON schema data types (such as string, number). This determines, among other things:

  • Date and time formatting (e.g., dd.MM.yyyy vs. ISO format)
  • Decimal separator (e.g., comma vs. period)
  • Language-dependent format conventions

Manual JsonPointer extension​

In cases where automatic assignment of JsonPointer entries is not possible (e.g., for complex or nested structures), additional pointers can be added manually. This applies in particular to:

  • Arrays with multiple objects of the same type
  • Referenced sub-schemas via $ref

Notes​

  • The transfer object only works with valid, fully loaded schemas.
  • All pointers used must point uniquely to a data field in the JSON schema.
  • Optionally defined fields can remain empty, but mandatory fields (according to required) must be filled in at runtime.

Example usage​

A transfer object reads a temperature message that is validated against the schema temperature.schema.json. Fields such as value, unit, and timestamp are then extracted and passed on to an SQL connection. Alternatively, another transfer object generates a machine status message according to machine_state_change.schema.json, in which all required fields are filled with data and optional fields are added.