YSON

В данном разделе собрана информация про YSON — JSON-подобный формат данных.

К основным отличиям YSON от JSON относится:

1. Поддержка бинарного представления скалярных типов (чисел, строк и булевого типа);
2. Атрибуты: произвольный словарь, который можно установить дополнительно на литерал любого — даже скалярного — типа.

Кроме того, существуют синтаксические отличия:

1. Вместо запятой в качестве разделителя используется точка с запятой;
2. В словарях ключ от значения отделяется не двоеточием, а знаком равенства: =;
3. Строковые литералы не обязательно всегда заключать в кавычки — только если возникает неоднозначность при парсинге;

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

1. Строки (string);
2. Знаковые и беззнаковые 64-битные целые числа (int64 и uint64 );
3. Числа с плавающей точкой двойной точности (double);
4. Булев (логический) тип (boolean);
5. Специальный тип entity, имеющий всего один литерал (#).

Скалярные типы обычно имеют как текстовое, так и бинарное представление.

Есть два композитных типа:

1. Список (list);
2. Словарь (map).

Скалярные типы

Строки

Токены строк бывают трёх видов:

1. Идентификаторы задаются регулярным выражением [A-Za-z_][A-Za-z0-9_.\-]*, расширенные C-идентификаторы, отличие в символах -,.. Идентификатор задает строку с идентичным ему содержимым и используется в первую очередь для краткости (не нужно ставить кавычки).

   Примеры:

   • abc123;
   • _;
   • a-b.

2. Текстовые строки — C-escaped строки в двойных кавычках.

   Примеры

   • "abc123";
   • "";
   • "quotation-mark: \", backslash: \\, tab: \t, unicode: \xEA".

3. Бинарные строки: \x01 + length (protobuf sint32 wire format) + data (<length> bytes).

Знаковые 64-битные целые числа (int64)

Два способа записи:

1. Текстовый (0, 123, -123, +123);
2. Бинарный: \x02 + value (protobuf sint64 wire format).

Беззнаковые 64-битные целые числа (uint64)

Два способа записи:

1. Текстовый (10000000000000, 123u);
2. Бинарный: \x06 + value (protobuf uint64 wire format).

Числа с плавающей точкой (double)

Два способа записи:

1. Текстовый: 0.0, -1.0, 1e-9, 1.5E+9, 32E1;
2. Бинарный: \x03 + protobuf double wire format.

Булевы литералы (boolean)

Два способа записи:

1. Текстовый (%false, %true);
2. Бинарный (\x04, \x05).

Entity (entity)

Entity представляет собой атомарное скалярное значение, не имеющее собственного содержимого. Сценарии, в которых данный тип может быть полезен, разнообразны. Например, часто entity обозначает null. Также при запросе get на поддерево Кипариса файлы и таблицы возвращаются в виде entities (полезные данные при этом хранятся в атрибутах данного узла).

Лексически entity кодируется символом диеза: #.

Выделенные литералы

Специальные токены:
;, =, #, [, ], {, }, <, >, ), /, @, !, +, ^, :, ,, ~.
Не все эти символы используются в YSON, некоторые используются в YPath.

Композитные типы

Список (list)

Задаётся следующим образом: [value; ...; value], где value — литералы произвольных скалярных или композитных типов.

Пример: [1; "hello"; {a=1; b=2}].

Словарь (map)

Задаётся следующим образом: {key = value; ...; key = value}. Здесь *key* — литералы строкового типа, а value — литералы произвольных скалярных или композитных типов.

Пример: {a = "hello"; "38 parrots" = [38]}.

Атрибуты

На любой литерал в YSON можно установить атрибуты. Формат записи: <key = value; ...; key = value> value. Внутри угловых скобок синтаксис аналогичен словарю. Например, <a = 10; b = [7,7,8]>"some-string" или <"44" = 44>44. Но чаще всего атрибуты можно встретить на литералах типа entity, например, <id="aaad6921-b5704588-17990259-7b88bad3">#.

Работа с YSON из кода

Обычно пользователям не приходится работать напрямую с YSON. При использовании одного из официальных YTsaurus-клиентов YSON-структуры будут выражаться в одном из перечисленных ниже видов:

1. C++: TNode — класс, обеспечивающий динамическое DOM-подобное представление YSON-документа;
2. Python: YsonType — YSON-типы мимикрируют под Python типы. YSON-атрибуты объекта x можно получить так: x.attributes, это Python словарь;
3. Java: YTreeNode — интерфейс, обеспечивающий динамическое DOM-подобное представление YSON-документа.