YQL-15992: Fix docs for parameters passing

YQL-15992: Fix docs for parameters passing

3 files changed, 135 insertions, 115 deletions

diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/declare/general.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/declare/general.md
index 01d78f93e3..f2d3fd7c93 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/declare/general.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/declare/general.md
@@ -33,3 +33,4 @@ DECLARE $z AS List<String>;
 SELECT $x, $y, $z;
 ```
 
+Примеры передачи параметров для DECLARE можно найти [здесь](../../../types/_includes/json.md).
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/types/_includes/json.md b/ydb/docs/ru/core/yql/reference/yql-core/types/_includes/json.md
index af7bc105f1..a9119e765d 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/types/_includes/json.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/types/_includes/json.md
@@ -1,173 +1,192 @@
-# Представление данных в формате JSON
+# Передача параметров и данных в формате JSON
 
-## Bool {#bool}
+YQL позволяет задавать параметры используя DECLARE выражение. Сами параметры передаются с помощью restricted JSON формата.
+Ниже дано описание формата передачи различных типов данных.
+Этот формат также используется для ответов из API.
+
+## Числовые типы
+
+### Bool {#bool}
 
 Логическое значение.
 
 * Тип в JSON — `bool`.
-* Пример значения {{ backend_name }} — `true`.
 * Пример значения JSON — `true`.
 
-## Int8, Int16, Int32, Int64 {#int}
+### Int, Uint, Float, Double, Decimal {#numbers}
 
-Целочисленные знаковые типы.
-
-* Тип в JSON — `number`.
-* Пример значения {{ backend_name }} — `123456`, `-123456`.
-* Пример значения JSON — `123456`, `-123456`.
+* Тип в JSON — `string`.
+* Числа передаются в строковом представлении.
+* Пример значения JSON — `"123456"`, `"-42"`, `"0.12345679"`, `"-320.789"`.
 
-## Uint8, Uint16, Uint32, Uint64 {#uint}
+## Строковые типы
 
-Целочисленные беззнаковые типы.
+### String {#string}
 
-* Тип в JSON — `number`.
-* Пример значения {{ backend_name }} — `123456`.
-* Пример значения JSON — `123456`.
+Бинарные строки.
 
-## Float {#float}
+* при наличии невалидных utf-8 символов, например, `\xFF`, строка кодируется в base64 и оборачивается в массив с одним элементом
+* если нет специальных символов, то передается как есть
+* Тип в JSON - `string` или `array`
+* Пример значения JSON - `"AB"`, `["qw6="]` (для строки `\xAB\xAC`)
 
-Вещественное 4-байтное число.
+### Utf8 {#utf}
 
-* Тип в JSON — `number`.
-* Пример значения {{ backend_name }} — `0.12345679`.
-* Пример значения JSON — `0.12345679`.
+Строковые типы в utf-8. Такие строки представляются в JSON строками с escaping'ом JSON-символов: `\\`, `\"`, `\n`, `\r`, `\t`, `\f`.
 
-## Double {#double}
+* Тип в JSON — `string`.
+* Пример значения JSON — `"Escaped characters: \\ \" \f \b \t \r\nNon-escaped characters: / ' < > & []() "`.
 
-Вещественное 8-байтное число.
+### Uuid {#uuid}
+
+Универсальный идентификатор UUID.
+
+* бинарный формат UUID кодируется с помощью base64 и оборачивается в лист
+* Тип в JSON - `array`
+* Пример значения JSON - `["AIQOVZvi1EGnFkRmVUQAAA=="]` для `550e8400-e29b-41d4-a716-446655440000`
+
+### Yson {#yson}
+
+* Тип в JSON - `object`.
+* YSON более богатый язык, чем JSON, поэтому есть необходимость предоставлять дополнительные атрибуты, поэтому задаются поля `$value`, `$type`, `$attributes`.
+* Строки, числа и логические значения заменяются на объект с двумя ключами: `$value` и `$type`. Типы могут быть: `boolean`, `int64`, `uint64`, `double`, `string`.
+* Каждый байт бинарной строки переводится в юникодный символ с соответствующим номером и кодируется в UTF-8 (такой же механизм использует YT при преобразовании Yson в Json).
+* Yson атрибуты добавляются в виде отдельного объекта c ключом `$attributes` и значениями атрибутов.
+* если какое имя начинается с `$`, то он экранируется с помощью удваивания `$$`.
+* Пример YSON:
+```
+{ "$a" = 2;
+  b = {
+    c = <attr1=val1;attr2=5>12.5;
+    d = [ "el"; # ]
+  }
+}
+```
+* Пример значения JSON:
+```
+{
+  "$$a" : { "$value": "2", "$type": "int64" },
+  "b" : {
+    "c": {
+          "$value" : "12.5",
+          "$type" : "double",
+          "$attributes" :
+            {
+              "attr1": { "$value": "b", "$type": "string" },
+              "attr2": { "$value": "5", "$type": "int64" }
+            }
+        },
+    "d": [ { "$value": "el", "$type": "string" }, null ]
+  }
+}
+```
+
+### Json {#json}
+
+* Тип в JSON - `object`.
+* Пример значения JSON - `{ "a" : 12.5, "c" : 25 }`.
+
+## Дата и время
+
+### Date {#date}
+
+Дата, внутреннее представление - Uint16, количество дней c unix epoch.
 
-* Тип в JSON — `number`.
-* Пример значения {{ backend_name }} — `0.12345678901234568`.
-* Пример значения JSON — `0.12345678901234568`.
+* Тип в JSON — `string`.
+* Пример значения JSON — `"19509"` для даты `2023-06-01`.
 
-## Decimal {#decimal}
+### Datetime {#datetime}
 
-Число с фиксированной точностью. Поддерживается только Decimal(22, 9).
+Дата и время, внутреннее представление - Uint32, количество секунд c unix epoch.
 
 * Тип в JSON — `string`.
-* Пример значения {{ backend_name }} — `-320.789`.
-* Пример значения JSON — `"-320.789"`.
+* Пример значения JSON — `"1686966302"`для даты `"2023-06-17T01:45:02Z"`.
 
-## String{% if audience != "external" %}, Yson{% endif %} {#string}
+### Timestamp {#timestamp}
 
-Бинарные строки. Алгоритм кодирования в зависимости от значения байта:
-
-* [0-31] — `\u00XX` (6 символов, обозначающих код символа юникода);
-* [32-126] — as is. Это читаемые однобайтовые символы, не требующие эскейпинга;
-* [127-255] — `\u00XX`.
-
-При декодировании происходит обратный процесс. Коды символов в `\u00XX` более 255 не допускаются.
+Дата и время, внутреннее представление - Uint64, количество микросекунд c unix epoch.
 
 * Тип в JSON — `string`.
-* Пример значения {{ backend_name }} — последовательность из 4 байт:
-  * 5 `0x05` - управляющий символ;
-  * 10 `0x0a` - перенос строки `\n`;
-  * 107 `0x6b` - символ `k`;
-  * 255 `0xff` - символ юникода `ÿ`.
-* Пример значения JSON — `"\u0005\nk\u00FF"`.
+* Пример значения JSON — `"1685577600000000"` для `2023-06-01T00:00:00.000000Z`.
 
-## Utf8, Json, Uuid {#utf}
+### Interval {#interval}
 
-Строковые типы в utf-8. Такие строки представляются в JSON строками с escaping'ом JSON-символов: `\\`, `\"`, `\n`, `\r`, `\t`, `\f`.
+Временной интервал, внутреннее представление - Int64, точность до микросекунд.
 
 * Тип в JSON — `string`.
-* Пример значения {{ backend_name }} — код на С++:
+* Пример значения JSON — `"12345678910"`.
 
-  ```c++
-  "Escaped characters: "
-  "\\ \" \f \b \t \r\n"
-  "Non-escaped characters: "
-  "/ ' < > & []() ".
-  ```
+### TzDate, TzDateTime, TzTimestamp {#tzdate}
 
-* Пример значения JSON — `"Escaped characters: \\ \" \f \b \t \r\nNon-escaped characters: / ' < > & []() "`.
+Временные типы с меткой временной зоны.
 
-## Date {#date}
+* Тип в JSON - `string`.
+* Значение представляется как строковое представление времени и временная зона через запятую.
+* Пример значения JSON - `"2023-06-29,Europe/Moscow"`, `""2023-06-29T17:14:11,Europe/Moscow""`, `""2023-06-29T17:15:36.645735,Europe/Moscow""` для TzDate, TzDateTime и TzTimestamp соответственно.
 
-Дата. Uint64, количество дней unix time.
+## Контейнеры
 
-* Тип в JSON — `string`.
-* Пример значения {{ backend_name }} — `18367`.
-* Пример значения JSON — `"2020-04-15"`.
-
-## Datetime {#datetime}
+В контейнерах все элементы кодируются согласно их типу.
 
-Дата и время. Uint64, количество секунд unix time.
+### List {#list}
 
-* Тип в JSON — `string`.
-* Пример значения {{ backend_name }} — `1586966302`.
-* Пример значения JSON — `"2020-04-15T15:58:22Z"`.
+Список. Упорядоченный набор значений заданного типа, значения передаются как строки.
 
-## Timestamp {#timestamp}
-
-Дата и время. Uint64, количество микросекунд unix time.
+* Тип в JSON — `array`.
+* Пример значения JSON  для `List<Int32>` — `["1","10","100"]`.
 
-* Тип в JSON — `string`.
-* Пример значения {{ backend_name }} — `1586966302504185`.
-* Пример значения JSON — `"2020-04-15T15:58:22.504185Z"`.
+### Struct {#struct}
 
-## Interval {#interval}
+Структура. Неупорядоченный набор значений с заданными именами и типом.
 
-Временной интервал. Int64, точность до микросекунд, допустимы значения интервалов - не более 24 часов.
+* Тип в JSON — `object` или `array`.
+* Может передоваться как объект или как массив, где порядок элементов должен совпадать с соответствующими полями структуры.
+* Пример значения JSON `{"a": "-100", "b": "foo"}`, `{"a": "-100", "b": "foo", "c": null}` или `["-100", "foo", null]` для `Struct<a:Int32, b:String, c:Optional<String>>`.
 
-* Тип в JSON — `number`.
-* Пример значения {{ backend_name }} — `123456`, `-123456`.
-* Пример значения JSON — `123456`, `-123456`.
+### Tuple {#tuple}
 
-## Optional {#optional}
+Кортеж. Упорядоченный набор значений заданных типов.
 
-Означает, что значение может быть `null`. Если значение `null`, то в JSON также будет `null`. Если значение не `null`, то в JSON значение запишется так же, как если бы тип был не `Optional`.
+* Тип в JSON — `array`.
+* Пример значения JSON для типа Tuple<Int32, String, Float?> — `[-1,"Some string",null]`.
 
-* Тип в JSON — отсутствует.
-* Пример значения {{ backend_name }} — `null`.
-* Пример значения JSON — `null`.
+### Dict {#dict}
 
-## List {#list}
+Словарь. Неупорядоченный набор пар ключ-значение.
 
-Список. Упорядоченный набор значений заданного типа.
+* Тип в JSON — `object` или `array`. 
+* для ключей типа `String` и `Utf8` можно передавать объект, для остальных типов надо передавать массив массивов, состоящих из двух элементов (ключа и значения).
+* Пример значения JSON — `[["1","123"],["2","456"]]` для `Dict<Int32, Interval>`, `{ "foo": "123", "bar": "456" }` для `Dict<String, Int32>`.
 
-* Тип в JSON — `array`.
-* Пример значения {{ backend_name }}:
-  * тип — `List<Int32>`;
-  * значение — `1, 10, 100`.
-* Пример значения JSON — `[1,10,100]`.
+### Enum {#enum}
 
-## Stream {#stream}
+Перечисление.
 
-Поток. Однопроходной итератор по значениям одного типа.
+* Тип в JSON - `string`.
+* Пример значения JSON - `"b"` для `Enum<a,b>`.
 
-* Тип в JSON — `array`.
-* Пример значения {{ backend_name }}:
-  * тип — `Stream<Int32>`;
-  * значение — `1, 10, 100`.
-* Пример значения JSON — `[1,10,100]`.
+## Variant {#variant}
 
-## Struct {#struct}
+Кортеж или структура, про которые известно, что заполнен ровно один элемент.
 
-Структура. Неупорядоченный набор значений с заданными именами и типом.
+* Тип в JSON - `array`.
+* Первый способ передачи - массив из поля структуры, обернутый в массив, и значения. Способ подходит только для варианта над структурами.
+* Второй способ передачи - массив из индекса поля структуры/кортежа и само значение.
+* Пример значения JSON - `[["foo"], false]`, `[["bar"], "6"]` или `["0", false]`, `["1", "6"]` для `Variant<foo: Int32, bar: Bool>`.
 
-* Тип в JSON — `object`.
-* Пример значения {{ backend_name }}:
-  * тип — `Struct<'Id':Uint32,'Name':String,'Value':Int32,'Description':Utf8?>`;
-  * значение — `"Id":1,"Name":"Anna","Value":-100,"Description":null`.
-* Пример значения JSON — `{"Id":1,"Name":"Anna","Value":-100,"Description":null}`.
+## Специальные типы
 
-## Tuple {#tuple}
+## Optional {#optional}
 
-Кортеж. Упорядоченный набор значений заданных типов.
+Означает, что значение может быть `null`.
 
-* Тип в JSON — `array`.
-* Пример значения {{ backend_name }}:
-  * тип — `Tuple<Int32??,Int64???,String??,Utf8???>`;
-  * значение — `10,-1,null,"Some string"`.
-* Пример значения JSON — `[10,-1,null,"Some string"]`.
+* Тип в JSON — `array` или `null`.
+* Значения обертываются в массив, `null` значение представляется пустым массивом или `null`.
+* Пример значения JSON - `[["1"], ["2"], ["3"], []]` или `[["1"], ["2"], ["3"], null]` для `List<Optional<Int32>>`.
 
-## Dict {#dict}
+## Void {#void}
 
-Словарь. Неупорядоченный набор пар ключ-значение. И для ключа, и для значения задан тип. В json записывается в массив массивов, состоящих из двух элементов.
+Сингулярный тип данных с единственным возможным значением `null`.
 
-* Тип в JSON — `array`.
-* Пример значения {{ backend_name }}:
-  * тип — `Dict<Int64,String>`;
-  * значение — `1:"Value1",2:"Value2"`.
-* Пример значения JSON — `[[1,"Value1"],[2,"Value2"]]`.
+* Тип в JSON - `string`.
+* Значение JSON - `"Void"`.
\ No newline at end of file
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml b/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml
index 833b05bb4b..bfadb9fa38 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml
+++ b/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml
@@ -13,7 +13,7 @@ items:
   href: cast.md
 - name: Текстовое представление типов данных
   href: type_string.md
-- name: JSON
+- name: Передача параметров в формате JSON
   href: json.md
 - name: YSON
   hidden: true