Ruoska Encoding

The principal entity of RSK document is frame. Two main classes of frames exist. Meta Frames to define structure and Data Frames to hold actual payload data. All frames start with Leading Byte which defines frame type and some type depended instructions. Some meta frames and all data frames can be tagged with an identifier. Identifier type is defined in Leading Byte. If identifier exists it is placed right after the Leading Byte. In Data Frames payload comes after identifier. Meta Frames may also have payload or special fields or both. Data type of the payload is defined by frame type and type depended instructions. All frame types are explained in . RSK document is structured as finite tree. The tree is rooted to Begin Frame. After the rooting Begin Frame follows data frames as leafs and Begin – End Frame pairs as branches. Branches may contain data frames as leafs and again Begin – End Frame pairs as sub branches. Null and Array Frames are considered as data frames here. RSK document always ends with End Frame. Use of End Frame is two fold. It is used to return from branch to parent level and terminate the document. So document must always start with Begin Frame and end with End Frame. Root nesting level 0 must not contain any other than rooting Begin and terminating End Frames. Between root Begin and terminating End Frame is nesting level 1. Nesting level 1 may contain data frames or branches or both.

Big-endian networking byte order is used. Endianness applies to all integer and floating point numbers. This includes payload of any data frames like Integer, Float, and Timestamp and 16-bits wide integer identifier values and also meta data fields like length of payload. Canonical network byte order is fully described in RFC791, Appendix B.

All strings are UTF-8 encoded. This applies to string identifiers and payload of String, Date, DateTime and DateTimeMillis Frames. Implementations using any of frame types above or String Identifier or both must be able to validate UTF-8 encoding. On writing phase UTF-8 encoding violation must be handled as error condition. If UTF-8 encoding fails on reading phase warning must be raised and let user decide to continue reading or not. More information about UTF-8 see RFC 3629.

As mentioned earlier the principal entity of RSK is frame. This section explains all frame types and type dependent special instructions in detail.

All frames start with Leading Byte. Leading Byte determines frame type and type dependent instructions. The most significant bit is reserved for Extended Frames which may be introduced in later versions. See for details. Leading Byte is presented as bit array where left-most bit is the most significant bit. MSB 0 bit numbering scheme is used with two exceptions. Left-most bit is reserved for Extended Frame and thus marked as 'X' for all Leading Byte definitions. Also some bits are marked with 'R' meaning that they are reserved for later use and must not be set in this version. Leading Byte is followed by frame type dependent fields like Identifier or Payload or both. These fields are presented as labeled byte blocks with possible lengths in bytes, kilobytes like 64k, or gigabytes like 4G.

Example of possible frame type dependent byte field. 4 or 8 means that field can be 4 or 8 bytes long. Actual length can be determined by frame type, instruction bits, or some other field. Example of possible frame type dependent payload field. 0 - 64k means that field can be from 0 to 65535 bytes long. Actual length can be determined by frame type, instruction bits, or some other field. These bits determine type dependent instructions. See specific frame type sections for details. For most frame types these are used to define identifier type. This bit field determines frame type. Values are defined in . Extended frame bit. See for details.

Meta Frames define document structure.

Null Frame can be tagged with an identifier but does not contain any payload data.

See for details. See .

Document and branches start with Begin Frame. Begin Frame may have an identifier. More details about tree structure see .

See for details. See .

End Frame is used to return from branch to parent level in tree structure and also used to terminate a document. More details about tree structure see .

See .

Array column in Frame Type Table in defines frame types which can be enclosed into a array. Array itself and each item may have identifiers. Array identifier is defined in Leading Byte. All items have identifier of same type and all items are same frame type. Frame and identifier type for all items are defined by CLB (Common Leading Byte). Array capacity is defined by selecting corresponding Array Frame type. See for details.

Array identifier. See for details. Common Leading Byte determines type of items and type of item identifiers. 8, 16, or 32-bits wide unsigned integer telling item count. Width of Count field depends on array type, see for details. Array of items. See . Array items are stored right after Count field. Items may have Identifier.

Data Frames are collection of widely used data types. There are frames for boolean, integer and floating point numbers, UTF-8 encoded strings, dates, and timestamps. There is also frame for raw binary data. All data frames can be tagged with an identifier.

Boolean value (False/True) is defined by choosing corresponding Boolean Frame type. See .

See for details. See .

Wide range of integer types are supported. Integer width and signedness are defined by choosing corresponding Integer Frame type. Signed integers are presented in two's complement notation. Integer payload is always stored in big-endian format. See for details.

See for details. Payload integer value. See .

Floating point number precision is defined by choosing corresponding Float Frame type. See for frame types. Floats are presented in IEEE754 standard format and endianness is big-endian. See for details.

See for details. Payload float value. See .

String Frame can hold UTF-8 encoded string. If implementation supports String Frame it must be able to validate UTF-8 encoding. See for details. Frame capacity is defined by selecting corresponding String Frame type. See for details.

See for details. 8, 16, or 32-bits wide unsigned integer telling length of string in bytes. Depends on String Frame type, see for details. UTF-8 encoded string. See .

Binary Frame holds arbitrary binary data. Frame capacity is defined by selecting corresponding Binary Frame type. See for details.

See for details. 8, 16, or 32-bits wide unsigned integer telling length of payload in bytes. Depends on Binary Frame type, see for details. Arbitrary binary data. See .

DateTime Frames hold date or date and time in UTC timescale as UTF-8 encoded string. String formats are compatible with RFC 3339. If implementation supports any of DateTime Frames it must be able to validate UTF-8 encoding. See for details. Besides string formats must be validated but date data validation is not part of RSK. On writing phase illegal string format must be handled as error. On reading phase string format violation can be handled by rising warning and let user decide continue reading or not. Date frame types and corresponding date string formats: YYYY-MM-DD YYYY-MM-DDTHH:MM:SSZ YYYY-MM-DDTHH:MM:SS.SSSZ

See for details. Date, DateTime, or DateTimeMillis string depends of date frame type. See .

NTP Short Frame holds NTP Short Format compatible timestamp. See RFC 5905 for details.

See for details. 16-bits unsigned integer telling seconds. 16-bits unsigned integer holding fractions of second. See .

NTP Timestamp Frame holds NTP Timestamp Format compatible timestamp. See RFC 5905 for details.

See for details. 32-bits unsigned integer telling seconds. 32-bits unsigned integer holding fractions of second. See .

NTP Date Frame holds NTP Date Format compatible date. See RFC 5905 for details.

See for details. 32-bits signed integer telling the era of timestamp. See RFC 5905 for era definitions. 32-bits unsigned integer holding number of seconds since beginning of the Era. 64-bits unsigned integer holding fractions of second. See .

RSK Date is optimized version of NTP Date Format defined in RFC 5905. Differences with NTP Date Format NTP Date Format has 32-bits wide Era field. Here Era is only 8-bits wide. Interpretation is same but with narrowed range. Epoch is same so Era 0 starts at 1900-01-01 00:00:00 UTC like in NTP Date Format. NTP Date Format uses 64-bits wide Fraction field. Here fraction is only 16-bits wide and thus capable to 16 microsecond resolution.

See for details. 8-bit signed integer telling the era of timestamp. See RFC 5905 for era definitions. 32-bit unsigned integer holding number of seconds since beginning of the Era. 16-bit unsigned integer holding fractions of second. See .

Extended Frame is concept to introduce new structures and data types in future versions of RSK. The most significant bit in Leading Byte is reserved for Extended Frames. In this version Extended bit must not be set when writing a RSK document. If Extended Frame is discovered on reading phase it must be handles as error in this version.

All data frames and some of the meta frames can be tagged with an identifier. Identifier can be defined as 8 or 16-bit wide unsigned integer or as length-prefixed UTF-8 encoded string. If identifier is not needed it can be set to Null. Frame's Leading Byte tells type of identifier. Identifier bytes are placed immediately after the Leading Byte. In case of integer identifier there is one or two bytes depending on selected integer identifier type. String identifier can take up to 256 bytes. See following sections for details.

Two least significant bits of Leading Byte are reserved for Id bits in all frame types which can be tagged with an identifier.

Id bits values and identifier types: Null Identifier. See . 8-bits wide Integer Identifier. See . 16-bits wide Integer Identifier. See . String Identifier. See

Some frames in a document may not need identifier so it can be left empty by setting it Null in Leading Byte.

Integer identifier types are 8 or 16-bits wide unsigned integers. Integer identifiers are presented in big-endian format. See for details.

String identifier is length-prefixed and UTF-8 encoded. Length is presented by one byte as 8-bits wide unsigned integer at the beginning of identifier field. String identifier itself can be 0 - 255 bytes long. If implementation supports string identifiers it must be able to validate UTF-8 encoding. See for details.

Frame Type Table columns: Name of frame type. See for detailed frame definitions. Hexadecimal value of Leading Byte with mask 0xFC. See for detailed description of Leading Byte. All marked with X has identifier field. See for details. All marked with X can be enclosed into a array. See for details. Payload length in bytes for data frames and item count for arrays.

RSK is designed so that implementations could have very small memory and other resource demands. Pay attention to memory usage and try to perform IO operations efficiently. Implementations must make sure that well formed documents are written. On reading phase any deformation in document or frame structure must be detected and handled as error condition. Implementations can vary depending on environment and usage. All implementations must support at least Begin and End Frames to be able to handle document structure. Other frame types may not be supported. Implementation may also support most or all frame types but not all identifier types. Some frame types can be also partially supported so that they can be detected and skipped on reading phase although their payload data is not interpreted.

RSK is data encoding format and does not include any executable commands. Implementations must make sure that any parts of encoded documents are not leaked into execution memory. Even malformed documents must be handled so that memory leaks are avoided. RSK does not include any means to validate payload data integrity. Protocols based on RSK or underlying mechanisms which are utilized by those protocols must take care of this. If data integrity is not checked can data get corrupted by malfunctioning devices, software, or malicious attackers.

The MIME media type for RSK documents is application/ruoska. application ruoska n/a n/a