Skip to main content

JSON Schema Transfer Object

Purpose and Function​

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

Schema Selection​

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

  • Use Latest Version: The transfer object always uses the highest available version of this schema (e.g., during a planned migration).
  • Use Fixed Version: A specific 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 specifically address fields and read, overwrite, or patch their values.

Example:

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

The JsonPointer equipment/status addresses the "active" field.

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

Limitations with Arrays​

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

  • either use fixed indices directly (e.g., array/0/property), or
  • recommended: schema the object in the array separately and process it using its own transfer object.

Operations​

Reading​

The transfer object extracts values from JSON data based on 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 validate 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 upon the first violation, and an error message is generated.

Format Culture and Type Conversion​

For type conversions between .NET types (such as DateTime, int, double) and JSON Schema data types (such as string, number), a format culture can be selected in the transfer object. 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 formatting conventions

Manual JsonPointer Extension​

In cases where automatic mapping 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 containing multiple objects of the same type
  • Referenced subschemas via $ref

Notes​

  • The transfer object only works with valid, fully loaded schemas.
  • All pointers used must uniquely point to a data field in the JSON schema.
  • Optionally defined fields may remain empty; required fields (as indicated by required) must be populated at runtime.

Example Usage​

A transfer object reads a temperature report, which is validated against the schema temperature.schema.json. Fields such as value, unit, and timestamp are then extracted and passed 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 populated with data and optional fields are filled in as needed.