Ruoska Encoding

The RSK is very suitable for fast prototyping and studying data exchange and storage solutions in environments with wide range of different kind of devices from small microcontrollers to mainframe computers. Only small subset of all features and data types are strictly required for every single implementation. This enables implementations for minimal systems like microcontrollers with modest computing capacity and memory. Minimal requirements are defined in . This version defines also mechanisms for later extensions. Actual structures and data types are not known but common structure for extended features is defined so they can be skipped by implementation versions which are not able interpret them. See for details.

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. Additional frame class is Extended Frame which enables forward compatibility with future versions. See for details. 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 . All implementations may not be able to handle all frame types but minimal requirements are defined 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. Nesting levels start from 0 and maximum level is artifially limited to 255 to keep implementations simple. 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 and DateTime Frames. Implementations using String Frame, String Identifier, or DateTime Frame must be able to validate UTF-8 encoding. See RFC 3629 for details.

As mentioned earlier the principal entity 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 and 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 or in kilobytes like 64k.

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. This bit field determines frame type. Extended frame bit. See for details.

Meta Frames define document structure. Some of the Meta Frames are optional for minimal implementations. See for details.

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

See for details. Begin Frame type: 0000

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 .

End Frame type: 0001

Modifier Frame is used to apply a modifier for example compression or encryption to same portions of document. RSK does not define any modifiers. When used they are defined in specifications based on RSK. Modified payload must consists of valid frames. On reading phase payload and meta data is passed to demodifier routine and then handled like ordinary frames. Modifier Frame is wrapper for other frames but not a sub branch for document tree structure. Payload may contain sub branches but branches must return to same nesting level as at beginning of payload. Meta field is intended to be used to store modifier specific data. For example original data length and padding byte count for a block compression. Meaning of Meta data must be defined in specifications based on RSK when Modifier Frame is used.

See for details. 16-bits wide unsigned integer telling length of meta data. MetLen must not exceed 4095 bytes! Custom meta data. 16-bits wide unsigned integer telling length of modified payload data. Modified payload data. Modifier Frame type: 0010

Fixed length Integer or Float frames with null or integer identifier can be enclosed into an array. This saves some resources when dealing with large number of items. This can be also used to make portions of encoded document random accessible. Array itself and each item may have identifiers. All items are same type. All items have identifier of same type. Frame and identifier type for all items are defined by CLB (Common Leading Byte).

Array identifier. See for details. Common Leading Byte for all Items. Determines type of Item and it's identifier. Frame type must be Integer or Float and identifier type must be Null, Uint8, or Uint32. 8 or 16-bits wide unsigned integer telling length of array items in bytes. Item Identifier. See for details. Item Payload. If bit is set then Length is 16-bits otherwise 8-bits wide unsigned integer. Array Frame type: 0011

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 frame can hold single True or False value.

See for details. If Boolean bit is set when boolean value is True otherwise False. 0100

Wide range of integer types are supported. Integer width is defined by choosing corresponding Integer Frame type. Integers can be defined as unsigned by setting Unsigned bit in Leading Byte otherwise they are signed. Negative values of signed integers are presented in two's complement notation. Integer payload is always stored in big-endian format. See for details.

See for details. If Unsigned bit is set when payload is unsigned otherwise signed integer. Payload integer value. Integer Frame types 8-bits wide integer. 16-bits wide integer. 32-bits wide integer. 64-bits wide integer.

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

See for details. Payload float value. Float Frame types 16-bits wide half precision float. 32-bits wide single precision float. 64-bits wide double precision float.

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.

See for details. 8 or 16-bits wide unsigned integer telling length of string in bytes. If bit is set then Length is 16-bits otherwise 8-bits wide unsigned integer. UTF-8 encoded string. String Frame type: 1100

Single Binary Frame can hold up to 65535 bytes and obviously a document may contain as many binary frames as needed. So the only issue with big binary masses is data fragmentation to multiple frames.

See for details. 8 or 16-bits wide unsigned integer telling length of payload in bytes. If bit is set then Length is 16-bits otherwise 8-bits wide unsigned integer. Binary payload. Binary Frame type: 1101

DateTime Frame holds date or date and time in UTC timescale as UTF-8 encoded string. Date is presented as ("YYYY-MM-DD") and DateTime is ("YYYY-MM-DDTHH:MM:SS.SSSZ"). String formats are compatible with RFC 3339. If implementation supports DateTime Frame it must be able to validate UTF-8 encoding. See for details.

See for details. Date or DateTime string. If bit is set then payload is DateTime otherwise Date. DateTime Frame type: 1110

Timestamp is very similar, with some exceptions, as NTP Date Format defined in RFC 5905. Differences to NTP Date Format NTP Date Format has 32-bits wide Era field. Here Era is only 8-bits wide. Intepretation 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. In NTP Date Format Fraction field always exists. Here it is optional. It exists only if Fraction bit is set in Leading Byte. NTP Date Format uses 64-bits wide Fraction field. Here fraction is only 32-bits wide and thus capable to 232 picosecond 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. 32-bit unsigned integer holding fractions of second. If Fraction bit is set then optional Fraction field exists. Timestamp Frame type: 1111

Extended Frame is concept to introduce new structures and data types to 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. Forward compatible implementations must be able to detect Extended Frames and interprete Length bit and Length field to get correct length of payload. Payload can be then skipped and processing continues with next frame. Extended Frame is not part of Minimal Requirements see .

8 or 16-bits wide unsigned integer telling length of payload in bytes. Payload can be skipped in this version. If bit is set then Length is 16-bits otherwise 8-bits wide unsigned integer. Extended Frame type and instruction bits will be defined in future Ruoska Encoding versions. These can be skipped in this version. If set frame must be handled as Extended Frame.

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 width. String identifier can take up to 256 bytes. See following sections for details. All identifier types are not required for minimal implementations. See 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 as all numbers in RSK. 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 255 bytes long at maximum. If implementation supports string identifiers it must be able to validate UTF-8 encoding. See for details.

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 many ways depending on environment and usage. Minimal Requirements define absolute minimum requirements for all implementations. All other feature can be left out to save resources in implementations for small devices. See for details.

Absolute minimal requirements for all implementations to be compatible with RSK are listed here. 8 bytes. 0 - 255 Begin and End Frames. Null and Integer identifiers. Boolean, Binary, and 8 and 16-bits wide Integer Frames. All other features like frame types Array, Modifier, Float, String, DateTime, and Timestamp are optional. String identifier is optional. Longer than 8 bytes payloads are optional. Support for Extended Frames is also optional.

An implementation may take advantage of Extended Frame concept to provide forward compatibility for later RSK versions. This is not required for all implementations and can be left out if not needed. See for Minimal Requirements and for Extended Frame.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

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. Modifier Frame enables encryption for selected portions of a document. RSK does not define any encryption methods but almost any kind of encryption cipher could be used. If needed encryption methods should be defined in specifications based on RSK.

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