Описание параметров схемы JSON-Editor
Список страниц по JSON-editor
- Введение в веб-конфигурирование wb-rules с помощью JSON-editor
- Процесс разработки конфигуратора с JSON-editor
- Описание работы с JSON-editor
Описание
Страница описывает опции, типы и форматы параметров JSON-editor, а также особенности реализации JSON-editor в Wiren Board.
Полезные ссылки
Соответствий форматов определенным типам параметров (array, string, bool ...) огромное множество и сложно описать их все в одном документе.
Изучение и разработку с помощью json-editor можно упростить используя несколько полезных инструментов.
Интерактивный редактор
Тут можно экспериментировать со схемами и внешними видами в интерактивном режиме онлайн:
- json-editor.github.io: Online editor
На странице есть несколько областей:
- вверху находится результат генерации формы;
- редактор кода схемы находится внизу страницы, в разделе Schema;
- обратите внимание, что вверху справа есть окно текста с генерируемым конфигом, который сохраняется в результате работы формы.
Meta - доступные возможности разных типов
Для того чтобы понять что можно использовать для определенного типа, можно подсмотреть в этот файл на гит:
- github.com: meta-schema.html
Так же можно посмотреть данный файл в интерактивном режиме онлайн:
- json-editor.github.io: Meta schema
Важно: В этих списках могут быть неточности, например:
- для типа object можно применить _format равный categories, но в списке форматов на этой странице только grid;
- для массива сказано что можно применить categories, но это не так.
Например тут можно понять какие отображения применимы к массивам:
- Выберите интересующий вас тип параметра в выпадающем списке, вверху, справа от слов JSON Schema.
- Нажмите properties, внизу списка выберите format.
- Cнизу появится выпадающий список форматов применяемых к данному типу параметра.
Для массива (Array) будет следующий список форматов:
- array;
- table;
- tabs;
- tabs-top;
- checkbox;
- select;
- categories.
Type - тип параметра
Важно: эти типы не связаны с типами которые используются в MQTT топиках. Это другие типы, но они частично пересекаются.
При создании файла схемы JSON-editor можно использовать все типы которые есть в json-schema, а именно:
- string;
- number;
- integer;
- object;
- array;
- boolean;
- null.
Подробнее о каждом типе можно узнать в документации:
- json-schema.org: Type-specific keywords
Список типов так же описан в этой схеме в исходниках:
- github.com: meta_schema.json
Format - вид отображения параметра
Параметр format позволяет изменять отображение элемента схемы в WEBUI.
Каждый элемент созданный в схеме может отображаться по разному. Например, boolean параметр, по умолчанию, отображается выпадающим списком, но его отображение можно поменять на чекбокс.
Ниже приведены примеры описание форматов элементов в WEBUI.
Важно: при использовании на контроллерах WB, для стабильной работы всегда нужно использовать написание с подчеркиванием в начале _format, а не стандартный format который есть в json-editor. Это нужно, так как у WB есть собственный форк с доработками.
Сheckbox
Сheckbox позволяет отмечать галочками нужные параметры в интерфейсе.
Пример описания в коде:
"properties": {
"boolStatusParameter": {
"type": "boolean",
"title": "Bool status parameter",
"_format": "checkbox",
"default": false,
"propertyOrder": 1
},
"arrayStatusParameter": {
"type": "array",
"title": "Array status parameter",
"_format": "checkbox",
"uniqueItems": true,
"items": {
"type": "string",
"enum": ["Status1","Status2"]
}
}
},
При выборе обоих вариантов в массиве с помощью зажатой клавиши CTRL или SHIFT сгенерируется следующий конфиг:
{
"arrayStatusParameter": [
"Status1",
"Status2"
],
"boolStatusParameter": false
}
Select
Это либо выпадающий список, либо список с возможностью множественного выбора, например по умолчанию:
- для массива (array) - будет использоваться multiple (множественный) выбор из списка;
- для логического типа (boolean) будет использоваться выпадающее меню.
Пример описания в коде:
"properties": {
"boolStatusParameter": {
"type": "boolean",
"title": "Bool status parameter",
"_format": "select",
"default": false,
"propertyOrder": 1
},
"arrayStatusParameter": {
"type": "array",
"title": "Array status parameter",
"_format": "select",
"uniqueItems": true,
"items": {
"type": "string",
"enum": ["Status1","Status2"]
}
}
}
При выборе обоих вариантов в массиве с помощью зажатой клавиши CTRL или SHIFT сгенерируется следующий конфиг:
{
"arrayStatusParameter": [
"Status1",
"Status2"
],
"boolStatusParameter": false
}
Table
Таблица может быть применена только к массиву.
Пример кода:
"properties": {
"persons": {
"type": "array",
"_format": "table",
"title": "Roles",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Person",
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"role": {
"type": "string",
"title": "Role",
"enum": [
"student",
"engineer",
"guest",
"teacher",
"other"
],
"default": "student"
}
}
}
}
},
Генерируемый конфиг:
{
"persons": [
{
"role": "student",
"name": "Walter"
},
{
"role": "guest",
"name": "Tom"
}
]
}
Tabs
Вкладки могут быть применены только к массиву.
Пример кода:
"properties": {
"persons": {
"type": "array",
"_format": "tabs",
"title": "Roles",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Person",
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"role": {
"type": "string",
"title": "Role",
"enum": [
"student",
"engineer",
"guest",
"teacher",
"other"
],
"default": "student"
}
}
}
}
},
Генерируемый конфиг:
{
"persons": [
{
"role": "student",
"name": "Walter"
},
{
"role": "guest",
"name": "Tom"
}
]
}
Так же можно реализовывать подобие древовидной структуры - вложив друг в друга массивы с отображением в виде вкладок.
Пример где массив верхнего уровня представляет комнаты, а внутри комнат можно добавлять девайсы разного типа
"rooms": {
"type": "array",
"format": "tabs",
"title": "Rooms",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Room",
"properties": {
"address": {
"type": "string",
"title": "Room name"
},
"devices": {
"type": "array",
"format": "tabs",
"title": "Devices",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Device",
"properties": {
"devType": {
"type": "string",
"enum": [
"tv",
"switch",
"light"
],
"default": "switch"
},
"name": {
"type": "string"
}
}
},
"default": [
{
"devType": "switch",
"name": "Wall switch"
}
]
}
}
}
}
Tabs-top
Вертикальные вкладки могут быть применены только к массиву.
Пример кода:
"properties": {
"persons": {
"type": "array",
"_format": "tabs-top",
"title": "Roles",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Person",
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"role": {
"type": "string",
"title": "Role",
"enum": [
"student",
"engineer",
"guest",
"teacher",
"other"
],
"default": "student"
}
}
}
}
},
Генерируемый конфиг:
{
"persons": [
{
"role": "student",
"name": "Walter"
},
{
"role": "guest",
"name": "Tom"
}
]
}
Tabs + Tabs-top
Разные типы вкладок можно комбинировать между собой для отображения сложных структур данных
Например если нам нужно отобразить комнаты и девайсы внутри этих комнат, то два вертикальных списка слева могут занимать слишком много места слева, тем более что комнат много не будет, а две-три комнаты слева займут полноценную широкую полосу для списка.
Эту задачу немного лучше можно решить отобразив комнаты не вертикальным списком слева, а горизонтальными вкладками сверху.
Пример такого отображения:
"rooms": {
"type": "array",
"format": "tabs-top",
"title": "Rooms",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Room",
"properties": {
"address": {
"type": "string",
"title": "Room name"
},
"devices": {
"type": "array",
"format": "tabs",
"title": "Devices",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Device",
"properties": {
"devType": {
"type": "string",
"enum": [
"tv",
"switch",
"light"
],
"default": "switch"
},
"name": {
"type": "string"
}
}
},
"default": [
{
"devType": "switch",
"name": "Wall switch"
}
]
}
}
}
},
Grid
Сетка (Grid) может быть применена только к объекту, так же Grid является стандартным отображением при создании объектов.
Элементы входящие в объект будут добавляться в ширину по условной сетке, значение которой равно 12.
Изменение ширины элемента с помошью grid не принудительное и примеряется, только если рядом тоже есть grid элементы которые имеют ширину подходящую чтобы оба элемента встали в одной строке.
Пример когда в одной строке только один элемент с шириной 3, но отображается на всю строку
{
"title": "Person",
"type": "object",
"format": "grid",
"properties": {
"text1": {
"type": "string",
"default": "Text1",
"options": {
"grid_columns": 3
}
}
}
}
Если при создании объекта не указать явно "format": "grid", то на одной строке может быть только один элемент. Чтобы в одной строке было несколько элементов, можно указать параметр grid_columns внутри options.
Пример указания grid_columns в опциях
"options": {
"grid_columns": 12
},
Если указать объекту формат сетки, но не указывать ширину в опциях элементов - то каждый элемент будет занимать минимальную ширину для данного типа. Например для текста это - 4, а для цифры - 2. Таким образом в ширину 12 помещаются 6 цифр или 3 текстовых поля.
Пример отображения множества параметров без указания ширины
{
"title": "Person",
"type": "object",
"format": "grid",
"properties": {
"text1": {
"type": "string",
"default": "Text1"
},
"text2": {
"type": "string",
"default": "Text2"
},
"text3": {
"type": "string",
"default": "Text3"
},
"digit1": {
"type": "integer",
"default": 1
},
"digit2": {
"type": "integer",
"default": 2
},
"digit3": {
"type": "integer",
"default": 3
},
"text4": {
"type": "string",
"default": "Text4"
},
"digit4": {
"type": "integer",
"default": 4
},
"digit5": {
"type": "integer",
"default": 5
},
"digit6": {
"type": "integer",
"default": 6
},
"digit7": {
"type": "integer",
"default": 7
},
"digit8": {
"type": "integer",
"default": 8
},
"digit9": {
"type": "integer",
"default": 9
},
"digit10": {
"type": "integer",
"default": 10
}
}
}
Categories
Может применяться только к объектам.
Если tabs-top позволяет видеть создаваемые элементы массива в виде горизонтальных вкладок, то Categories нужна чтобы структурировать список заполняемых полей одного объекта по горизонтальным вкладкам.
Если у вашего объекта Person имеется несколько блоков заполняемых данных: адрес, данные о работе и др., то вместо длинного списка на одной странице вы можете разбить заполнение этих полей по вкладкам.
Имя вкладки с полями из корня объекта будет указано как Basic. Для изменения имени корневой вкладки - нужно использовать basicCategoryTitle.
{
"type": "object",
"_format": "categories",
"properties": {
"name": { "type": "string" }
},
"basicCategoryTitle": "Main"
}
Пример ниже показывает применение формата к типу объекта:
"properties": {
"settings_name": {
"propertyOrder": 1,
"type": "string",
"title": "Settings name"
},
"sensors": {
"type": "array",
"_format": "tabs-top",
"title": "Sensors",
"uniqueItems": true,
"items": {
"type": "object",
"title": "Sensor",
"properties": {
"sensor_name": {
"propertyOrder": 1,
"type": "string",
"title": "Name"
},
"read_period_ms": {
"propertyOrder": 2,
"type": "integer",
"_format": "edWb",
"title": "Read period (ms)",
"description" : "read_period_description",
"minimum": 10,
"options": {
"enum_values": [ 100, 200 ],
"inputAttributes": {
"placeholder": "in queue order"
}
}
}
}
}
}
},
Вид сохраняемого конфига:
{
"settings_name": "Main room",
"sensors": [
{
"sensor_name": "Temperature",
"read_period_ms": 100
},
{
"sensor_name": "Humidity",
"read_period_ms": 200
}
]
}
Options - изменение поведения
Опции позволяют изменять поведение элементов и указываются в параметре "options": {...}. Можно перемещать кнопки управления, скрывать некоторые кнопки и др.
Для каждого типа элементов существуют определенные варианты опций.
Например для массива можно указать несколько опций следующим образом:
"properties": {
"pets": {
"type": "array",
"title": "Pets",
"options": {
"disable_collapse": true,
"disable_array_reorder": true,
"disable_array_delete_last_row": true,
"enable_array_copy": true
},
"items": {
...Описание элементов...
}
}
}
Подробнее с опциями можно ознакомиться в документации:
- github.com: json-editor:options
disable_properties
Отключает кнопку Свойства (Properties) вверху каждого объекта (применимо только к объектам).
Пример в коде:
"options": {
"disable_properties": true
},
patternmessage
patternmessage - позволяет изменить сообщение об ошибке паттерна.
Код паттерна проверки значения поля:
"id_prefix": {
"title": "id_prefix_title",
"type": "string",
"description": "id_prefix_description",
"_pattern_comment": "Запрещает пробелы, /, +, и #, а также ограничивает строку использованием только цифр, нижнего подчеркивания и английских букв",
"pattern": "^[0-9a-zA-Z_]+$",
"default": "devices_control",
"minLength": 1,
"maxLength": 120,
"propertyOrder": 3,
"options": {
"grid_columns": 12,
"patternmessage": "error_regexp_patternmessage"
}
}
По умолчанию, будет сформирована ошибка следующего рода:
Можно изменить описание ошибки, для этого измените значение параметра patternmessage.
Пример со значением "patternmessage": "Значение должно быть корректным":
Сообщение об ошибке паттерна нельзя отключить.
display_required_only
Выключает добавление необязательных полей в схему и как следствие их отображение в WEBUI.
Обратите внимание: в отличие от использования "hidden": true, в этом случае необязательные поля будут отключены и физически удалены из итогового конфига, то есть они не скрываются только из отображения в WEBUI, а именно удаляются из схемы и полностью пропадают из конфига - у них будет значение = undefined.
При нажатии на кнопку options у объекта - такие поля будут отображаться с выключеной галочкой:
Пример использования:
"options": {
"display_required_only": true
}
Выключить по дефолту при открытии конфигуратор отображение только части из необязательных параметров нельзя, данный функционал отсутствует. Можно либо показать все необзятельные параметры (поведение по умолчанию), либо скрыть все необязательные параметры при использовании display_required_only.
input_width
Явно и принудительно задает ширину поля ввода. Напомним, что изменение ширины с помошью grid не применяется принудительно, напимер если у вас только один элемент на строке.
"hysteresis": {
"type": "number",
"title": "thermostatHysteresisTitle",
"description": "thermostatHysteresisDescription",
"default": 1,
"propertyOrder": 6,
"options": {
"input_width": "100px"
}
},
Отображение такого элемента
placeholder
Вместо description который показывается снизу от поля - можно использовать placeholder показывающийся внутри самого поля до того как в нем что то написали
Пример использования placeholder:
"temperatureSensor": {
"type": "string",
"_format": "wb-autocomplete",
"title": "thermostatTemperatureSensorTitle",
"pattern": "^[^/+#]+/[^/+#]+$",
"propertyOrder": 7,
"options": {
"grid_columns": 12,
"inputAttributes": {
"placeholder": "В формате: Устройство/Контрол"
},
"wb": {
"data": "devices"
}
},
"minLength": 1
},
"actuator": {
"type": "string",
"_format": "wb-autocomplete",
"title": "thermostatActuatorTitle",
"pattern": "^[^/+#]+/[^/+#]+$",
"propertyOrder": 9,
"options": {
"grid_columns": 12,
"inputAttributes": {
"placeholder": "В формате: Устройство/Контрол"
},
"wb": {
"data": "devices"
}
},
"minLength": 1
}
Отображение такого элемента
dependencies
patternmessage может быть использован как внутри options, так и снаружи и имеет несколько применений. По причине сложности - данный элемент вынесен в отдельную секцию ниже
Особенности реализации wirenboard
В дополнение к стандартным _format и options командой WB были реализованы дополнительные параметры JSON-Editor.
Подробно ознакомиться с особенностями реализации можно на отдельной странице:
dependencies
Данный инструмент можно использовать для нескольких целей:
- Условное отображение элемента
Условное отображение элемента
Условное отображение элемента можно сделать через добавление зависимостей (dependencies) в опции вашего параметра.
Пример синтаксиса и структуры:
"options": {
"dependencies": {
"sensorDataType": ["valueMotSensor"]
}
}
Пример параметра с зависимостями в options. Здесь поле в столбце «Пороговый уровень движения» показывается для элемента у которого установлен "sensorDataType" = "valueMotSensor":
"motionSensors": {
"type": "array",
"title": "darkroomMotionSensorsArrTitle",
"_title_note": "When options-> compact: true - this title not shown",
"description": "darkroomMotionSensorsArrDescription",
"propertyOrder": 6,
"_format": "table",
"options": {
"disable_collapse": true,
"grid_columns": 12,
"array_controls_top": true,
"disable_array_delete_last_row": true,
"disable_array_reorder": true,
"wb": {
"disable_panel": true
}
},
"items": {
"type": "object",
"title": "darkroomMotionSensorsObjTitle",
"properties": {
"control": {
"type": "string",
"propertyOrder": 1,
"title": "darkroomMotionSensorsObjControlTitle",
"description": "generalControlDescription",
"pattern": "^[^/+#]+/[^/+#]+$",
"_format": "wb-autocomplete",
"options": {
"patternmessage": "error_regexp_patternmessage",
"wb": {
"data": "devices"
}
},
"_minLength_note": "Device name (1) + slash (1) + topic name (1)",
"minLength": 3
},
"sensorDataType": {
"type": "string",
"title": "Sensor Data Type",
"enum": [
"valueMotSensor",
"boolMotSensor",
"stringMotSensor"],
"default": "value",
"propertyOrder": 2,
"options": {
"enum_titles": [
"Value",
"Bool",
"String: 'true', 'false'"
]
}
},
"thresholdMotionLevel": {
"type": "number",
"title": "darkroomMotionSensorsObjThresholdTitle",
"default": 170,
"propertyOrder": 3,
"options": {
"dependencies": {
"sensorDataType": ["valueMotSensor"]
}
}
}
},
"required": [
"control",
"thresholdMotionLevel"
]
}
},
Условная валидация
В данном примере при выборе не корректной комбинации type1 + status3 будет выведена ошибка.
Это будет выглядеть следующим образом
Пример схемы:
"statusVsType": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"type1",
"type2"
]
},
"status": {
"type": "string",
"enum": [
"status1",
"status2",
"status3"
],
"options": {
"hidden": false
}
}
},
"dependencies": {
"type": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"type1"
]
},
"status": {
"enum": [
"status1",
"status2"
]
}
}
},
{
"properties": {
"type": {
"enum": [
"type2"
]
},
"status": {
"enum": [
"status3"
]
}
}
}
]
}
}
}
}
}
}
enum
Чтобы с enum работали переводы используйте параметр title.
Ниже примеры работы enum переводов с двумя разными структурами - string и array
enum - string
В случае реализации с "type": "string" - элемент будет отображаться в виде выпадающего списка
Обратите внимание - вот так переводы не сработают, тут нет options.enum_titles.[]:
"eventType": {
"type": "string",
"propertyOrder": 2,
"title": "Event Type",
"enum": [
"When Change",
"When Disabled (switch)",
"When Enable (switch)"
],
"default": "When Change"
}
Вот так заработает:
"eventType": {
"type": "string",
"propertyOrder": 2,
"title": "Event Type",
"enum": [
"whenChange",
"whenDisabled",
"whenEnabled"
],
"default": "whenChange",
"options": {
"enum_titles": [
"When Change",
"When Disabled (switch)",
"When Enabled (switch)"
]
}
}
В переводах уже:
"When Change": "Когда изменится",
"When Disabled (switch)": "Когда отключено (для переключателей)",
"When Enabled (switch)": "Когда включено (для переключателей)",
Пример реализации можно посмотреть в схеме сценариев, в сценаии "devicesControl", в элементе "inControls"
enum - array
"weekDays": {
"title": "scheduleWeekDaysTitle",
"type": "array",
"_format": "checkbox",
"uniqueItems": true,
"propertyOrder": 5,
"options": {
"grid_columns": 12
},
"items": {
"type": "string",
"enum": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"options": {
"enum_titles": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday",
"Sunday"
]
}
}
},
В переводах внизу схемы уже вносим правки. Функционал перводов в array был реализован только в начале декабря 2025г - до этого работали переводы только в enum string.
"translations": {
"en": {
...ничего не пишем...
},
"ru": {
"Monday": "Понедельник",
"Tuesday": "Вторник",
"Wednesday": "Среда",
"Thursday": "Четверг",
"Friday": "Пятница",
"Saturday": "Суббота",
"Sunday": "Воскресенье",
}
}
Отображение такого элемента
Пример реализации можно посмотреть в схеме сценариев, в сценаии "schedule"
If else
В этом примере структура в then и else полностью повторяет структуру определения свойств объекта, что позволяет корректно изменить свойство hidden объекта bar. Такой подход гарантирует, что изменения применяются точечно к нужному свойству.
Результат будет выглядеть следующим образом:
- Стандартно выбрано "no_bar" и поле bar отсутстувует ("hidden": true)
- Если выбрать "with_bar" - то поле bar появится ("hidden": false)
Пример схемы:
{
"type": "object",
"properties": {
"foo": {
"type": "string",
"enum": [
"no_bar",
"with_bar"
]
},
"bar": {
"type": "string"
}
},
"if": {
"properties": {
"foo": {
"enum": [
"no_bar"
]
}
}
},
"then": {
"properties": {
"bar": {
"options": {
"hidden": true
}
}
}
},
"else": {
"properties": {
"bar": {
"options": {
"hidden": false
}
}
}
}
}
Обратите внимание, что запись через точку не заработает:
"then": {
"properties.bar.options.hidden": true
},
"else": {
"properties.bar.options.hidden": false
}
Пример с элементами массива
{
"type": "object",
"properties": {
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"actionType": {
"type": "string",
"enum": [
"enable",
"disable",
"notify"
]
},
"message": {
"type": "string"
}
},
"if": {
"properties": {
"actionType": {
"const": "notify"
}
}
},
"then": {
"properties": {
"message": {
"type": "string",
"minLength": 1
}
}
},
"else": {
"properties": {
"message": {
"type": "string",
"options": {
"hidden": true
}
}
}
}
}
}
}
}
Навигация
← Назад: Описание работы с JSON-editor
Страница (5 из 7): Описание параметров схемы JSON-Editor
Вперед →: Особенности реализации JSON-editor в Wirenboard