The JSON DataEncodingwas developed to allow OPC UA applications to interoperate with web and enterprise software that use this format. The OPC UA JSON DataEncodingdefines standard JSON representations for all OPC UA Built-In types.

The JSON format is defined in RFC 8259. It is partially self-describing because each field has a name encoded in addition to the value, however, JSON has no mechanism to qualify names with namespaces.

The JSON format does not have a published standard for a schema that can be used to describe the contents of a JSON document. However, the schema mechanisms defined in this document can be used to describe JSON documents. Specifically, the DataTypeDescriptionstructure defined in OPC 10000-3can define any JSON document that conforms to the rules described below.

Serversthat support the JSON DataEncodingshall add DataTypeEncoding Nodescalled “Default JSON” to all DataTypeswhich can be serialized with the JSON encoding. The NodeIdsof these Nodesare defined by the information model which defines the DataType. These NodeIdsare used in ExtensionObjectsas described in 5.4.2.16.

There are two important use cases for the JSON encoding: Cloud applications which consume PubSubmessages and JavaScript Clients(JSON is the preferred serialization format for JavaScript). For theCloud application use case, the PubSubmessage needs to be self-contained which implies it cannot contain numeric references to an externally defined namespace table. Cloud applications also often rely on scripting languages to process the incoming messages so artefacts in the DataEncodingthat exist to ensure fidelity during decoding are not necessary. For this reason, this DataEncodingdefines a ‘non-reversible’ form which is designed to meet the needs of Cloud applications. Applications, such as JavaScript Clients, which use the DataEncodingfor communication with other OPC UA applications use the normal or ‘reversible’ form. The differences, if any, between the reversible and non-reversible forms are described for each type.

Any value for a Built-In type that is NULL shall be encoded as the JSON literal ‘null’ if the value is an element of an array. If the NULL value is for a field within a Structureor Union, the field shall not be encoded.

A Booleanvalue shall be encoded as the JSON literal ‘true’ or ‘false’.

Integer values other than Int64and UInt64shall be encoded as a JSON number.

Int64and UInt64values shall be formatted as a decimal number encoded as a JSON string

(See the XML encoding of 64-bit values described in 5.3.1.3).

Normal Floatand Doublevalues shall be encoded as a JSON number.

Special floating-point numbers such as positive infinity (INF), negative infinity (-INF) and not-a-number (NaN) shall be represented by the values “Infinity”, “-Infinity” and “NaN” encoded as a JSON string. See 5.2.2.3for more information on the different types of special floating-point numbers.

Stringvalues shall be encoded as JSON strings.

Any characters which are not allowed in JSON strings are escaped using the rules defined in RFC 8259.

Stringswith embedded nulls (‘\u0000’) are not guaranteed to be interoperable because not all DevelopmentPlatformscan handle Stringswith embedded nulls. For this reason, embedded nulls are not recommended. Encoders may encode Stringswith embedded nulls. Decoders shall read all bytes in String; however, decoders may truncate the Stringat the first embedded null before passing it on to the application.

DateTimevalues shall be formatted as specified by ISO 8601-1and encoded as a JSON string.

DateTimevalues which exceed the minimum or maximum values supported on a platform shall be encoded as “0001-01-01T00:00:00Z” or “9999-12-31T23:59:59Z” respectively. During decoding, these values shall be converted to the minimum or maximum values supported on the platform.

ISO 8601-1 DateTypevalues may specify an arbitrary number of decimal places representing fractions of seconds. Encoders shall support as many decimal places needed to represent the full range of the DateTimetype on their DevelopmentPlatform. Decoders may truncate decimal places that exceed the range supported by the DateTimetype on their DevelopmentPlatform.

DateTimevalues equal to “0001-01-01T00:00:00Z” are considered to be NULL values.

Guidvalues shall be formatted as described in 5.1.3and encoded as a JSON string.

ByteStringvalues shall be formatted as a Base64text and encoded as a JSON string.

Any characters which are not allowed in JSON strings are escaped using the rules defined in RFC 8259.

XmlElementvalue shall be encoded as a String as described in 5.4.2.5.

NodeIdvalues shall be encoded as a JSON object with the fields defined in Table 28.

The abstract NodeId structure is defined in OPC 10000-3and has three fields Identifier, IdentifierTypeand NamespaceIndex. The representation these abstract fields are described in the table.

Table 28– JSON Object Definition for a NodeId

Name	Description
IdType	The IdentifierTypeencoded as a JSON number. Allowed values are: 0 - UInt32 Identifierencoded as a JSON number. 1 - A StringIdentifier encoded as a JSON string. 2 - A Guid Identifierencoded as described in 5.4.2.7. 3 - A ByteString Identifierencoded as described in 5.4.2.8. This field is omitted for UInt32 identifiers.
Id	The Identifier. The value of the IdTypefield specifies the encoding of this field.
Namespace	The NamespaceIndexfor the NodeId. The field is encoded as a JSON number for the reversible encoding. The field is omitted if the NamespaceIndexequals 0. For the non-reversible encoding, the field is the NamespaceUriassociated with the NamespaceIndex,encoded as a JSON string. A NamespaceIndex of 1 is always encoded as a JSON number.

ExpandedNodeIdvalues shall be encoded as a JSON object with the fields defined in Table 29.

The abstract ExpandedNodeId structure is defined in OPC 10000-3and has five fields Identifier, IdentifierType, NamespaceIndex, NamespaceUri and ServerIndex. The representation of these abstract fields are described in the table.

Table 29– JSON Object Definition for an ExpandedNodeId

Name	Description
IdType	The IdentifierTypeencoded as a JSON number. Allowed values are: 0 - UInt32 Identifierencoded as a JSON number. 1 - A StringIdentifier encoded as a JSON string. 2 - A Guid Identifierencoded as described in 5.4.2.7. 3 - A ByteString Identifierencoded as described in 5.4.2.8. This field is omitted for UInt32 identifiers.
Id	The Identifier. The value of the IdTypefield specifies the encoding of this field.
Namespace	The NamespaceIndexor the NamespaceUrifor the ExpandedNodeId. If the NamespaceUriis not specified, the NamespaceIndexis encoded with these rules: The field is encoded as a JSON number for the reversible encoding. The field is omitted if the NamespaceIndexequals 0. For the non-reversible encoding the field is the NamespaceUriassociated with the NamespaceIndexencoded as a JSON string. A NamespaceIndex of 1 is always encoded as a JSON number. If the NamespaceUriis specified it is encoded as a JSON string in this field.
ServerUri	The ServerIndexfor the ExpandedNodeId. This field is encoded as a JSON number for the reversible encoding. This field is omitted if the ServerIndexequals 0. For the non-reversible encoding, this field is the ServerUriassociated with the ServerIndexportion of the ExpandedNodeId,encoded as a JSON string.

StatusCodevalues shall be encoded as a JSON number for the reversible encoding.

For the non-reversible form, StatusCodevalues shall be encoded as a JSON object with the fields defined in Table 30.

Table 30– JSON Object Definition for a StatusCode

Name	Description
Code	The numeric code encoded as a JSON number. The Codeis omitted if the numeric code is 0 (Good).
Symbol	The string literal associated with the numeric code encoded as JSON string. e.g. 0x80AB0000 has the associated literal “BadInvalidArgument”. The Symbolis omitted if the numeric code is 0 (Good).

A StatusCode of Good (0) is treated like a NULL and not encoded. If it is an element of an JSON array it is encoded as the JSON literal ‘null’.

DiagnosticInfovalues shall be encoded as a JSON object with the fields shown in Table 31.

Table 31– JSON Object Definition for a DiagnosticInfo

Name	Data Type	Description
SymbolicId	Int32	A symbolic name for the status code.
NamespaceUri	Int32	A namespace that qualifies the symbolic id.
Locale	Int32	The locale used for the localized text.
LocalizedText	Int32	A human readable summary of the status code.
AdditionalInfo	String	Detailed application specific diagnostic information.
InnerStatusCode	StatusCode	A status code provided by an underlying system.
InnerDiagnosticInfo	DiagnosticInfo	Diagnostic info associated with the inner status code.

Each field is encoded using the rules defined for the built-in type specified in the Data Type column.

The SymbolicId, NamespaceUri, Localeand LocalizedTextfields are encoded as JSON numbers which reference the StringTablecontained in the ResponseHeader.

QualifiedNamevalues shall be encoded as a JSON object with the fields shown in Table 32.

The abstract QualifiedName structure is defined in OPC 10000-3and has two fields Nameand NamespaceIndex. The NamespaceIndexis represented by the Urifield in the JSON object.

Table 32– JSON Object Definition for a QualifiedName

Name	Description
Name	The Name component of the QualifiedName.
Uri	The NamespaceIndexcomponent of the QualifiedNameencoded as a JSON number. The Urifield is omitted if the NamespaceIndex equals 0. For the non-reversible form, the NamespaceUriassociated with the NamespaceIndexportion of the QualifiedNameis encoded as JSON string unless the NamespaceIndexis 1 or if NamespaceUriis unknown. In these cases, the NamespaceIndexis encoded as a JSON number.

LocalizedTextvalues shall be encoded as a JSON object with the fields shown in Table 33.

The abstract LocalizedText structure is defined in OPC 10000-3and has two fields Textand Locale.

Table 33– JSON Object Definition for a LocalizedText

Name	Description
Locale	The Localeportion of LocalizedTextvalues shall be encoded as a JSON string
Text	The Textportion of LocalizedTextvalues shall be encoded as a JSON string.

For the non-reversible form, LocalizedTextvalue shall be encoded as a JSON string containing the Textcomponent.

ExtensionObjectvalues shall be encoded as a JSON object with the fields shown in Table 34.

Table 34– JSON Object Definition for an ExtensionObject

Name	Description
TypeId	The NodeIdof a DataTypeEncoding Nodeformatted using the rules in 5.4.2.10.
Encoding	The format of the Bodyfield encoded as a JSON number. This value is 0 if the body is Structureencoded as a JSON object (see 5.4.6). This value is 1 if the body is a ByteStringvalue encoded as a JSON string (see 5.4.2.8). This value is 2 if the body is a XmlElementvalue encoded as a JSON string (see 5.4.2.9). This field is omitted if the value is 0.
Body	Bodyof the ExtensionObject. The type of this field is specified by the Encodingfield. If the Body is empty, the ExtensionObjectis NULL and is omitted or encoded as a JSON null.

For the non-reversible form, ExtensionObjectvalues shall be encoded as a JSON object containing only the value of the Bodyfield. The TypeIdand Encodingfields are dropped.

Variantvalues shall be encoded as a JSON object with the fields shown in Table 35.

Table 35– JSON Object Definition for a Variant

Name	Description
Type	The Built-in type for the value contained in the Body(see Table 1) encoded as JSON number. If type is 0 (NULL) the Variantcontains a NULL value and the containing JSON object shall be omitted or replaced by the JSON literal ‘null’ (when an element of a JSON array).
Body	If the value is a scalar it is encoded using the rules for type specified for the Type. If the value is a one-dimensional array it is encoded as JSON array (see 5.4.5). Multi-dimensional arrays are encoded as a one-dimensional JSON array which is reconstructed using the value of the Dimensionsfield (see 5.2.2.16).
Dimensions	The dimensions of the array encoded as a JSON array of JSON numbers. The Dimensionsare omitted for scalar and one-dimensional array values.

For the non-reversible form, Variantvalues shall be encoded as a JSON object containing only the value of the Bodyfield. The Typeand Dimensionsfields are dropped. Multi-dimensional arrays are encoded as a multi dimensional JSON array as described in 5.4.5.

DataValuevalues shall be encoded as a JSON object with the fields shown in Table 36.

Table 36– JSON Object Definition for a DataValue

Name	Data Type	Description
Value	Variant	The value.
Status	StatusCode	The status associated with the value.
SourceTimestamp	DateTime	The source timestamp associated with the value.
SourcePicoSeconds	UInt16	The number of 10 picosecond intervals for the SourceTimestamp.
ServerTimestamp	DateTime	The Servertimestamp associated with the value.
ServerPicoSeconds	UInt16	The number of 10 picosecond intervals for the ServerTimestamp.

If a field has a null or DefaultValueit is omitted. Each field is encoded using the rules defined for the built-in type specified in the Data Type column.

Decimalvalues shall be encoded as a JSON object with the fields in Table 37.

Table 37– JSON Object Definition for a Decimal

Name	Description
Scale	A JSON number with the scale applied to the Value.
Value	A JSON string with the Value encoded as a base-10 signed integer. (See the XML encoding of Integer values described in 5.3.1.3).

See 5.1.8for a description of the Scaleand Valuefields.

Enumerationvalues shall be encoded as a JSON number for the reversible encoding.

For the non-reversible form, Enumerationvalues are encoded a literal with the value appended as a JSON string.

The format of the string literal is:

<name>_<value>

Where the name is the enumeration literal and the value is the numeric value.

If the literal is not known to the encoder, the numeric value is encoded as a JSON string.

One dimensionalArraysshall be encoded as JSON arrays.

If an element is NULL, the element shall be encoded as the JSON literal ‘null’.

Otherwise, the element is encoded according to the rules defined for the type.

Multi-dimensional Arraysare encoded as nested JSON arrays. The outer array is the first dimension and the innermost array is the last dimension. For example, the following matrix

0 2 3

1 3 4

is encoded in JSON as

[ [0, 2, 3], [1, 3, 4] ]

Structuresshall be encoded as JSON objects.

Fields which are NULL or have a default value shall be encoded using the rules shown in Table 38.

Table 38– JSON Encoding Rules for Structures

Field Value	Reversible	Non-Reversible
NULL	Omitted	JSON null
Default Value	Omitted	Default Value

For example, instances of the structures:

struct Type2

{

Int32 A;

Int32 B;

Char* C;

};

struct Type1

{

Int32 X;

Int32 NoOfY;

Type2* Y;

Int32 Z;

};

The reversible encoding is represented in JSON as:

{

"X":1234,

"Y":[ { "A":1, "B":2, "C":"Hello" }, { "A":3, "B":4 } ],

"Z":5678

}

Where “C” is omitted from the second Type2 instance because it has a NULL value.

The non-reversible encoding is represented in JSON as:

{

"X":1234,

"Y":[ { "A":1, "B":2, "C":"Hello" }, { "A":3, "B":4, "C":null } ],

"Z":5678

}

Where “C” in the second Type2 instance has a JSON null value.

Structureswith optional fields shall be encoded as JSON objects as shown in Table 39.

Table 39– JSON Object Definition for a Structures with Optional Fields

Name	Description
EncodingMask	A bit mask indicating what fields are encoded in the structure (see 5.2.7) This mask is encoded as a JSON number. The bits are sequentially assigned to optional fields in the order that they are defined. This field is not encoded in the non-reversible form.
<FieldName>	The field in structure encoded according to the rules defined for their DataType. One entry may exist for each mandatory field and each optional field that is present.

Fields which are NULL or have a default value shall be encoded using the rules shown in Table 40.

Table 40– JSON Encoding Rules for Structures with Optional Fields

Field Value	Field Type	Reversible	Non-Reversible
NULL	Mandatory	Omitted	JSON null
Default Value	Mandatory	Omitted	Default Value
NULL	Optional (Present)	Omitted	JSON null
Default Value	Optional (Present)	Omitted	Default Value
NULL	Optional (Omitted)	Omitted	Omitted
Default Value	Optional (Omitted)	Omitted	Omitted

If a Structurewith optional fields is subtyped, the subtypes extend the EncodingMask defined for the parent.

The following is an example of a structure with optional fields using C++ syntax:

struct TypeA

{

Int32 X;

Int32* O1;

SByte Y;

Int32* O2;

};

O1 and O2 are optional fields where a NULL indicates that the field is not present.

Assume that O1 is not specified and the value of O2 is 0.

The reversible encoding would be:

{ "EncodingMask": 2 "X": 1, "Y": 2 }

Where decoders would assign the default value of 0 to O2 since the mask bit is set even though the field was omitted (this is the behaviour defined for the Int32 DataType). Decoders would mark O1 as ‘not specified’.

The non-reversible encoding would be:

{ "X": 1, "Y": 2, "O2": 0 }

Where the EncodingMask is omitted.

Unionsshall be encoded as JSON objects as shown in Table 41for the reversible encoding.

Table 41– JSON Object Definition for a Union

Name	Description
SwitchField	The identifier for the field in the Union which is encoded as a JSON number. The valid values for this field follow the conventions defined in 5.2.8. If the SwitchFieldvalue is its DefaultValueof 0, then the SwitchFieldand the Valuefield are not present.
Value	The value of the field encoded using the rules that apply to the data type.

For the non-reversible form, Unionvalues are encoded using the rule for the current value. If the SwitchFieldis 0 the Unionis encoded as a JSON null value.

For example, instances of the union:

struct Union1

{

Byte Selector;

{

Int32 A;

Double B;

Char* C;

}

Value;

};

would be represented in reversible form as:

{ "SwitchField":2, "Value":3.1415 }

In non-reversible form, it is represented as:

3.1415

Messagesare encoded ExtensionObjects(see 5.4.2.16).