Общая структура документа USDS

Если в теле документа есть словарь, то обязательно должен присутствовать заголовок.

Бинарная структура документа:

Заголовок

Заголовок USDS 1.0 начинается с сигнатуры '$S' в кодировке ASCII, что соответствует кодам 0x24 0x53. Размер заголовка 10 байт, после сигнатуры следуют:

• старшая и минорная версии стандарта, для USDS 1.0 это всегда числа 1 и 0;
• уникальный идентификатор словаря (на схеме 888): целое число 4 байта, Little-endian, значения от 0 до 2147483647;
• старшая и минорная версии словаря (на схеме 1 и 0): числа от 0 до 255.
  

Словарь

Словарь начинается с сигнатуры 'D' в кодировке ASCII, что соответствует коду 0x44. Следом за сигнатурой следует:

• размер зловаря в байтах (Dictionary size), используется тип данных unsigned varint. В размере не учитывается сигнатура (1 байт) и ячейка с самим размером (1+ байт);
• код кодировки для наименований тегов и комментариев в словаре (Encode): одна из поддерживаемых в USDS кодировок. Используется тип данных varint, полный список кодировок в USDS представлен ниже.
• описание тегов (Tags description): спиок описаний тегов и комментарии. Описание каждого типа для тегов приведено в нижеследующих разделах.
  

Общее описание объявления тега:

На рисунке показано:

• сигнатура тега (Signature), возможны два значения:
• символ 't' в кодировке ASCII, что соответствует коду 0x74: объявление не корневого тега;
• символ 'r' в кодировке ASCII, что соответствует коду 0x72: объявление корневого тега (root в текстовом словаре);
• идентификатор тега (Tag ID): соответствует значению в словаре, от 1 до 2147483647, используется тип данных unsigned varint (1+ байт);
• размер имени тега в байтах (Name size), используется тип данных unsigned varint (1+ байт);
• имя тега (Tag name), кодировка указывается при объявлении словаря;
• тип тега (Tag type): числовой идентификатор одного из типов данных USDS, полный перечень приведен ниже. Используется тип данных unsigned varint (1+ байт);
• дополнительное описание типа данных (Type description): приведено для каждого типа отдельно в нижеследующих разделах.
  

Тело документа

Тело документа начинается с сигнатуры 'B' в кодировке ASCII, что соответствует коду 0x42. Следом за сигнатурой следует:

• сериализованные данные (Serialized Data): каждый блок данных начинается с идентификатора тега за которым следуют сериализованные данные, подробнее смотрите в нижеследующих разделах;
  
• признак окончания тела документа - 0. Идентификатор тега не может быть задан в словаре как ноль.
  

Типы данных

Перечень типов данных USDS:

Перечень поддерживаемых текстовых кодировок для типа данных string и словаря:

Простые типы данных

Теги с простыми типами данных записываются в словарь следующим образом:

На схеме указано:

• Тип тега (Tag type) - число от 1 до 25, в соответствии с таблицей типов выше.
• Ограничения (Restrictions): в версии USDS 1.0 для простых типов не поддерживаются, всегда записывается 'n' в кодировке ASCII, что соответствует коду 0x6E.

В тело документа простые теги записываются в следующем виде:

Типы данных varint и unsigned varint соответствуют спецификации Little Endian Base 128.

Структуры

Теги-структуры записываются в словарь следующим образом:

• тип тега (Tag type) указан как "26", что соответствует идентификатору типа struct;
• количество полей (Number of fields) в структуре, используется тип данных unsigned varint (1+ байт). В структуре может быть от 1 до 2147483647 полей;
• идентификаторы полей (Field_N ID): значения от 1 до 2147483647, используется тип данных unsigned varint (1+ байт). Поля следуют в порядке возрастания значения Field ID;
  
• размер имени поля (Name size): в байтах, используется тип данных unsigned varint (1+ байт);
• имена полей (Field_N name): кодировка текста задается при объявлении словаря;
• типы данных для полей (Field_N type): один из типов USDS, кроме struct. Если в качестве типа необходимо указать другой тег, то устанавливается в 0, и следующим байтом задается идентификатор любого другого тега. Если в качетсве ID тега указан ID самой структуры, то данное поле должно быть опциональным. Используется тип данных unsigned varint (1+ байт);
• ограничения для полей:
  
• признак обязательного поля: символ 'r' в кодировке ASCII, что соответствует коду 0x72. В текстовой версии словаря нет ключевого слова "default";
  
• признак опционального поля: символ 'o' в кодировке ASCII, что соответствует коду 0x6F. В текстовом словаре объявляется как "default NULL". Опциональным может быть любое поле, в том числе все поля структуры;
• признак поля со значением по умолчанию: символ 'd' в кодировке ASCII, что соответствует коду 0x64. В текстовом словаре объявляется как "default _значение_". Значение по умолчанию может быть только у простых типов и у строк. Само значение по умолчанию (Default value) заносится сразу после признака.

В тело документа структуры записываются следующим образом:

На схеме указано:

• блок данных начинается с идентификатора тега структуры (Tag ID);
• в первую очередь следуют значения обязательных полей (в текстовом словаре не указано "dafault"), они перечисляются в порядке возрастания идентификаторов полей (Field_N ID). Сам идентификатор не указывается для экономии места;
• далее следуют не обязательные поля (default value, default NULL), они следуют в порядке возрастания идентификаторов полей (Field_N ID). Указывается сам идентификатор поля, и за ним следует значение поля. Не обязательные поля не записываются в тело документа, если:
• поле объявлено как "default value", и его значение сейчас соответствует дефолтному (Field 3);
• поле объявлено как "default NULL" и оно сейчас отсутствует (Field 2 и 6);
• блок данных завершается байтом 0x00, но завершающий нулевой блок отсутствует, если:
• при объявлении структуры в словаре не указали ни одного опционального и дефолтного поля: в этом случае размер структуры известен и нет необходимости завершать блок данных нулем;
• в структуре (в теле документа) присутствует поле с максимальным значением идентификатора опционального поля (Field ID). Например, было объявлено, что поля с ID 2, 3, 4 и 6 опциональные или дефолтные. Если поле 6 было записано в тело документа, то очевидно, что это окончание структуры, и завершающий нулевой блок не требуется.

Массивы

Теги-массивы записываются в словарь следующим образом:

На схеме указано:

• тип тега (Tag type) указан как "27", что соответствует идентификатору типа array;
• размер массива (Array size): количество элементов в массиве. Если указано 0, то размер массива плавающий - записывается в теле документа. Используется тип данных unsigned varint (1+ байт);
• тип данных для элементов массива (Type for array) и соответствующие описания типов.
  

В тело документа массивы записываются следующим образом:

На схеме указано:

• иденитфикатор тега-массива (Tag ID);
• размер массива (Array size) - количество элементов массива. Указывается только если размер массива не зафиксиован в словаре. Используется тип данных unsigned varint (1+ байт);
• значения элементов массива.
  

Строки

Теги-строки записываются в словарь следующим образом:

На схеме указано:

• тип тега (Tag type) указан как "28", что соответствует идентификатору типа string;
• кодировка строки (Encode): идентификатор. Если указано 0, то кодировка записывается в теле документа для каждой строки. Используется тип данных unsigned varint (1+ байт);
• ограничения на размер строки (Restrictions):
• без ограничений: 'n' в кодировке ASCII, что соответствует коду 0x6E. В тело документа всегда записывается размре строки (количество символов);
• ограничен максимальный размер строки: 'm' в кодировке ASCII, что соответствует коду 0x6D. Далее следует количество символов, используется тип данных unsigned varint (1+ байт).  В тело документа всегда записывается размре строки (количество символов);
• размер строки фискирован: 'f' в кодировке ASCII, что соответствует коду 0x66. Далее следует количество символов, используется тип данных unsigned varint (1+ байт). В тело документа не записывается размре строки.

Списки

Теги-списки записываются в словарь следующим образом:

На схеме указано:

• тип тега (Tag type) указан как "29", что соответствует идентификатору типа list;
• ограничения (List restrictions): в версии USDS 1.0 для списков не поддерживаются, всегда записывается 'n' в кодировке ASCII, что соответствует коду 0x6E;
• тип данных для элементов списка (Type for list) и соответствующие описания типов.

В первую группу значений (values) входит не более 127 элементов списка, во вторую не более 16 256, в третью не более 2 080 768 и т.д.

Полное количество элемнетов списка определяется по обычным правилам преобразования unsigned varint.

Ассоциативные массивы (Map)

Теги-карты записываются в словарь следующим образом:

На схеме указано:

• тип тега (Tag type) указан как "30", что соответствует идентификатору типа map;
• ограничения (Map restrictions): в версии USDS 1.0 для карт не поддерживаются, всегда записывается 'n' в кодировке ASCII, что соответствует коду 0x6E;
• тип данных для ключей (Type for key) и соответствующие описания типов;
• тип данных для значений (Type for value) и соответствующие описания типов.

В первую группу значений (values) входит не более 127 элементов списка, во вторую не более 16 256, в третью не более 2 080 768 и т.д.

Полиморфы

Теги-полиморфы записываются в словарь следующим образом:

На схеме указано:

• тег-полиморф не может быть корневым;
  
• тип тега (Tag type) указан как "31", что соответствует идентификатору типа polymorph;
• количество элементов полиморфа (Number of elements): количество тегов. Используется тип данных unsigned varint (1+ байт);
• список тегов, в качестве которых может представляться полиморф, с любым типом данных, кроме других полиморфов. Спиоск должен быть уникальным, теги следуют в порядке нарастания Tag ID. Элементом полиморфа не может быть сам полиморф (рекурсия запрещена).

В качестве значения тега "Tag ID = 11"  в тело документа записывается не 10 тег (другой полиморф), а сразу итоговый тег 15.