Projects‎ > ‎USDS‎ > ‎USDS 1.0*‎ > ‎

Specification of USDS Binary

Main Description

The binary document USDS 1.0 consists of the following parts:

  • Head: contains USDS signature, an identifier and a version of the dictionary;
  • Dictionary: contains tag's description (names, types, relationship);
  • Body: contains serialized data.

These parts can be absent:

  • All parts are represented in a binary document: you can edit the data using USDS Editor, convert the data to XML and JSON using USDS Converter. Use this variant for configuration files and debugging;
  • The head and dictionary presented: use this for establishing a connection between client and server;
  • The Head only: use this for establishing a connection if client and server have dictionary already;
  • The head and body: transfer this objects if client and server have dictionary already and you don't need stable connection;
  • The body only: transfer this objects if connection established already.

If binary document includes dictionary then head mast be included too.

The main description of USDS binary document:

Head

The head of USDS 1.0 start from signature '$S' (ASCII, 0x24 0x53), it's size is 10 bytes. After signature are following:

  • Major and minor USDS version: numbers 1 and 0 for USDS 1.0;
  • Integer identifier of the dictionary: 4 bytes, little-endian, from 0 to 2147483647;
  • Major and minor dictionary version: numbers from 0 to 255.

Dictionary

The dictionary starts from signature 'D' (ASCII, 0x44). After signature are following:

  • The dictionary size in bytes, unsigned varint. The size includes all bytes after itself;
  • Encode for tag names and comments in the dictionary: unsigned varint, one of supported in USDS, the list represented below;
  • Tag's description: names, types, relationship.

The main description of a tag:

The scheme contains:

  • signature:
    • 't' (ASCII, 0x74): not root tag;
    • 'r' (ASCII, 0x72): root tag;
  • Tag identifier (from the text dictionary): unsigned varint, from 1 to 2147483647;
  • The size of tag name: the number of bytes, unsigned varint;
  • Tag name;
  • The integer identifier of tag's type: the list of all types represented below;
  • Type description: it's specific for every type.

Body

The body starts from signature 'B' (ASCII, 0x42). After signature are following:

  • Serialized data: every block of data starts from tag identifier, formats are represented below;
  • The signature of the end of the document: 0 (zero, Tag ID can't be zero).

Data types

The list of USDS data types:

The list of supported text encodes for the dictionary an strings:

Simple types

The main description of simple types:

The scheme contains:

  • The identifier of tag type (1-25), unsigned varint;
  • Type restrictions: not supported in USDS 1.0, always 'n' (ASCII, 0x6E).

Simple type in the body:

The type 1-23 have fixed size. The types varint and unsigned varint correspond to Little Endian Base 128.

Structure

The main description of structures:

The scheme contains:

  • Tag type: 26 for structures;
  • Number of fields: unsigned varint, from 1 to 2147483647;
  • Field identifiers: unsigned varint, from 1 to 2147483647;
  • The size of field name: in symbols, unsigned varint;
  • Field names;
  • Field type:
    • any USDS type instead "struct';
    • the name of the other tag with any type;
    • the name of this tag, but the field must be optional;
  • Field restrictions:
    • required field: 'r' (ASCII, 0x72);
    • optional filed: 'o' (ASCII, 0x6F), "default NULL" in text dictionary. Parser will return NULL, if the body doesn't contain this field;
    • fields with default value: 'd' (ASCII, 0x64), the body doesn't contain this field if it's equal to default value.
The structure in the body:

The scheme contains:

  • Tag identifier, unsigned varint;
  • All required fields in ascending order of filed ID (1 and 5);
  • All other fields in ascending order of filed ID, excepting:
    • the fields with default value, if it's equal default value (3);
    • optional fields, if it's equal NULL (2 and 6);
  • The structure ends with 0 (zero), but this final byte can be excepted if:
    • the structure has only required fields;
    • the last field (with maximum field ID) is in the body.

Arrays

The main description of arrays:

The scheme contains:

  • Tag type: 27 for arrays;
  • Array size: the number of elements, unsigned varint. The value 0 are used for unfixed size;
  • Type for array: simple types, strings or other tag name.

The array in the body:

The scheme contains:

  • Tag identifiers: unsigned varint;
  • Array size: amount of the elements, unsigned varint. It absents if size is set in dictionary;
  • Element values.

Strings

The main description of strings:

The scheme contains:

  • Tag type: 28 for strings;
  • Text encode: unsigned varint, one of supported in USDS, or 0 if unfixed;
  • Restrictions:
    • no restrictions: 'n' (ASCII, 0x6E);
    • limited size: 'm' (ASCII, 0x6D);
    • fixed size: 'f' (ASCII, 0x66).
The strings in the body:

List

The main description of lists:

The scheme contains:

  • Tag type: 29 for lists, unsigned varint;
  • List restrictions: not supported in USDS 1.0 - 'n' (ASCII, 0x6E);
  • Type for list elements: simple type, string or other tag name, unsigned varint.
The lists in the body:

The scheme contains:

  • Tag identifiers: unsigned varint;
  • List values;
  • List size: the number of elements, distributed unsigned varint:

Maps

The main description of maps:

The scheme contains:

  • Tag type: 30 for maps, unsigned varint;
  • Map restrictions: not supported in USDS 1.0 - 'n' (ASCII, 0x6E);
  • Type for keys: simple type, string or other tag name, unsigned varint;
  • Type for values: simple type, string or other tag name, unsigned varint.
The maps in the body:

The scheme contains:

  • Tag identifiers: unsigned varint;
  • Map keys and values;
  • Map size: the number of couples, distributed unsigned varint:

Polymorph

The main description of polymorph:

The scheme contains:

  • Polymorph tag can't be "root";
  • Tag type: 31 for polymorph, unsigned varint;
  • Number of elements: unsigned varint;
  • List of the tags: any tag types, unsigned varint.
The polymorph in the body:

There is no tag "10" in the polymorph "11", instead it used tag 15 directly.



2015.08.12, Andrey Abramov
CC BY 4.0

Comments

The gadget spec URL could not be found