Content Comparison

All transported messages must be valid JSON syntax and include NULL termination. Vendor specific extensions to OKMs must adhere to the specification rules.

Escape Sequences

JSON strings, which includes field names, must follow the JSON standard as it pertains to escaping special characters otherwise the resulting JSON message will not be valid. Field names should only use printable, non-control characters.

Except for normally escaped string characters, non-printable ASCII characters should be encoded as a JSON Unicode escape sequence \u00XX. This keeps the OpenKitchen JSON message human readable and minimizes the potential for extraneous control sequences to cause unexpected problems during message creation, transmission, and processing.

Unicode Character Sets

The current implementation of the CWL interprets strings as a set of 8-bit ASCII characters and does not natively handle Unicode character sets.

OKE that support Unicode character strings, and which intend to transfer those strings to and from the OKC will use the Base64 encode those strings, essentially treating them as binary data, when creating OKMs. The OKE data dictionary will specify which fields contain Unicode strings, the specific Unicode encoding (UTF-16, etc.) and that those strings are Base64 encoded within the OKM.

Field Ordering

Except for arrays, the order of fields within a JSON message must not confer information and must not be interpreted to convey information. For example, a source generating a JSON message cannot ensure the destination will process the fields of the message in a specific order.

The following two JSON messages contain the same information and destinations handling these messages may process either _cmd or _id first followed by the other:

{"_cmd":"wr","_id":5612}

{"_id":5612,"_cmd":"wr"}

However, the source can be certain that fields organized in a nested hierarchy are processed by the destination within the context of the hierarchy.

Use an array when the order of data and its processing matters.

Encoding Binary Data

Binary data, data containing mainly non-printable characters, shall be encoded either as an ASCII hexadecimal string or as a Base64 encoded string.

ASCII Hexadecimal String

Binary data should be encoded as an ASCII hexadecimal string when the data can be decoded into a meaningful value that is helpful for debugging. For example, a 2-byte bit-field value such as 0x6A05 should be encoded as the string 6A05 in the JSON message. A leading “0x” will not be prepended to the string. ASCII letters should be uppercase.

Multi-byte integer values should be encoded in big endian format.

Base64 encoding

Binary data should be encoded as a Base64 string when the data does not have an obvious meaningful value for debugging or when the amount of binary data is large. Base64 encoding increases the size to represent a binary string by about 1 1/3 of the original data, whereas an ASCII hexadecimal string would double the size. A typical use case for Base64 encoding would be to represent a portion of a file or firmware image.

The CWL substitutes the pipe character | for the standard forward slash character / when encoding and decoding Base64 strings. This is done to eliminate the required escaping of the forward slash within the JSON string. This makes the length of the Base64 encoded string more predictable and results in less memory consumption.

Whitespace

Although whitespace, including newlines and carriage returns, are allowed between JSON elements they do not add any meaning to the data being represented and will consume additional bandwidth and memory that is at a premium on many embedded devices and low bandwidth networks.

Therefore, it is strongly recommended that all whitespace characters whose sole purpose is to make the JSON format nicely, be removed before the message is transported between the OKE and the OKC.

Maximum Length

The maximum message length is 1000 bytes including NULL termination.

ConnectWare Library

https://sitesage.atlassian.net/wiki/x/Z4BFHQ

The CWL includes a memory efficient JSON parser and emitter that can be used by implementors for processing and generating CWMs.

Field Names

Standard Field Names

The names of all standard fields will be preceded by an underscore.

Custom Field Names

Vendor specific defined Custom field names shall not begin with an underscore character.

Vendor specific Custom defined field names shall not contain a period/dot character.

It is recommended that field names defined by OKE vendors be descriptive and short.

One of the benefits of using JSON is that a human can readily read and decode the message. So meaningful field names are essential. However, very long field names can unnecessarily waste bandwidth and memory. The recommendation is that field names are generally 3 to 5 characters in length.

Hierarchical Complexity

JSON syntax permits hierarchical nesting of elements that helps represent the logical organization of data.

However, this can greatly increase the memory and time requirements for parsing a message.

For incoming messages generated by the OKC and meant to be consumed by the OKE it is recommended to keep JSON data nesting to a minimum. Typically, a message would have no more than 3-4 levels of nesting at maximum.

For outgoing messages generated by the OKE and meant to be consumed by the OKC significant data nesting should still be avoided to keep processing overhead low. Typically, a message would have no more than 3-4 levels of nesting at maximum.