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:

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 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).

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 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 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.

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