Json схема что это
Перейти к содержимому

Json схема что это

  • автор:

JSON Schema

В данном примере применяется разный формат даты у объектов. Кроме того, один объект использует born (указывает, когда родился исполнитель), в то время как другие используют formed (когда образовалась группа/исполнитель).

В JSON нет правил, согласно которым некоторые объекты должны использовать определённый тип данных или даже содержать одинаковые поля. Им даже не нужно содержать одинаковое количество полей. Например, мы можем добавить поле favoritecolor к одному объекту, не добавляя его к другим.

Кроме того, нет правила, согласно которому данные должны быть в заданном формате. Например, поле born может быть представлено любым из следующих способов.

"born" : "1956" "born" : 1956 "born" : "Июль 15, 1956" "born" : "1956-07-15" "born" : "07/15/1956" "born" : "15/07/1956" "born" : "Я люблю апельсины!" "born" : [ < "albumname" : "Flying in a Blue Dream", "year" : "1989", "genre" : "Инструментальный рок" >, < "albumname" : "The Extremist", "year" : "1992", "genre" : "Инструментальный рок" >, < "albumname" : "Shockwave Supernova", "year" : "2015", "genre" : "Инструментальный рок" >] "born" : "Упс. "

Да, верно — «Упс. ». Вы можете вставить туда что угодно.

Эта гибкость — одна из вещей, которая делает JSON таким простым в использовании. Но она же одновременно может вызвать проблемы, показанные выше. Многие приложения, которые читают JSON-файлы, требуют, чтобы данные были в стандартном формате. Но даже если приложения это прочитают, людям будет трудно понять, какой именно датой является «Я люблю апельсины!».

Поэтому при работе с JSON часто требуется задать ограничения для типов данных, которые могут попадать в файл. Например, чтобы все даты вводились в определённом формате, скажем, ГГГГ-ММ-ДД. Или убедиться, что пользователи вводят только число в поле возраста.

Создание схемы

Вы можете применять правила для своих JSON-файлов, создав схему, которая позволяет указать, какой тип данных может добавляться в ваши файлы. Также схема может использоваться для проверки JSON-файла, чтобы убедиться, что он содержит только правильный тип данных.

Например, вы можете использовать следующий код, чтобы ограничиться только строкой.

Вот пример базовой схемы JSON Schema (взят с json-schema.org).

< "title": "Example Schema", "type": "object", "properties": < "firstName": < "type": "string" >, "lastName": < "type": "string" >, "age": < "description": "Age in years", "type": "integer", "minimum": 0 >>, "required": ["firstName", "lastName"] >

Можете использовать эту схему для проверки правильности ввода пользователем имени и возраста.

Как видите, JSON Schema на деле является тем же JSON. Так что не всегда легко определить что перед вами: JSON Schema или обычный JSON-документ.

Тем не менее, хорошей практикой считается размещение описания в верхней части схемы. Тогда описание объявляет, что перед нами схема JSON и оно поможет распознать, JSON Schema это или просто обычный JSON-документ.

Чтобы объявить JSON Schema, используйте ключевое слово $schema .

В данном примере объявляется JSON Schema, написанная для текущей версии спецификации.

Вы также можете указать явно, какую версию спецификации используете. В следующем примере объявляется JSON Schema, написанная для JSON Schema, черновая версия 4.

Для создания JSON Schema ознакомьтесь с JSONSchema.net. Это онлайн-инструмент, который автоматически генерирует JSON Schema из любого введённого вами JSON.

JSON Schema. Быть или не быть?

Ни для кого давно уже не секрет, что для любого web-сервиса на протоколе SOAP с сообщениями в формате XML верным и проверенным временем решением является предварительная разработка XML Schema (xsd-схемы), описывающей типы данных и структуру XML сообщений. При этом подходе у разработчиков существует явное преимущество: у них есть строгие стандартизированные правила по структуре сообщений, которые заданы в схеме, число правил конечно, и они позволяют автоматизировать проверку любого нового сообщения в формате XML.

Но также известно, что язык XML потеснился языком разметки JSON (JavaScript Object Notation) в виду его большей тяжеловесности (тяжеловесности XML), а также в виду распространения архитектурного стиля REST (REpresentational State Transfer) разработки программного обеспечения для распределенных систем. Хотя сам REST-стиль не требует использования JSON (он вообще, можно сказать, ничего не требует, а «рекомендует»), но как показывает практика, чаще при разработке REST API все-таки используется JSON для описания тела сообщений.

Так вот, практика разработки REST API с JSON–сообщениями прочно вошла в жизнь ИТ в России (и не только у нас), хотя опыт при этом по описанию структуры сообщений в виде XML Schema, значительно упростивший жизнь разработчиков web-служб в свое время, упорно игнорируется в случае c JSON–сообщениями. Но не всеми, что не может не радовать.

Когда разработчики, знакомые с XML Schema, столкнулись с необходимостью каждый раз заново изобретать велосипед с разбором документов и переизобретать логику валидации, сформировался аналогичный драфт JSON Schema. Он доступен по адресу json-schema.org, а также ряд документов по истории изменений и примеров использования. И несмотря на то что он публикуется в статусе «draft», его давно уже поддерживают все популярные платформы разработки и библиотеки на разных языках.

Сама JSON Schema предоставляет меньше возможностей по структуризации сообщений, чем XML Schema. То, что легко можно описать через XML Schema, не всегда будет тривиальной задачей повторить с помощью JSON Schema, если вообще это будет возможно. Но здесь же я бы данный факт стала рассматривать и как преимущество. Почему?

Известно, что чем проще и линейнее алгоритм работы системы, тем она и надежнее, что чем проще структура документа, тем легче он для восприятия и т.д.

Не могу удержаться, чтобы не процитировать: «Всё гениальное просто, и всё простое гениально». И если не удается с помощью схемы описать сложную структуру документа и множество допустимых вариантов, то, возможно, стоит посмотреть в сторону упрощения самой структуры и логики формирования этого документа?

Предисловие

Итак, о чем же эта статья?

Я бы хотела привлечь больше внимания к преимуществам описания передаваемых JSON сообщений схемой JSON Schema. Несмотря на то, что «на входе» разработка REST API без какой-либо JSON-схемы всегда проще и быстрее, но с ростом системы, ее отсутствие так или иначе приводит к удорожанию сопровождения и поддержки системы. Также любая предварительная проработка структуры сообщений способствует более качественной организации обмена сообщениями, без лишнего дублирования при обмене данными и общими правилами их обработки.

Также в целях распространения информации в русскоязычном сообществе о возможностях JSON Schema и правилах работы с ней я поделюсь своим некоторым опытом на конкретных примерах в рамках данной статьи.

Постановка задачи

Перед тем как приступить к изучению JSON и JSON Schema, опишу задачу, на которой мы будем рассматривать все примеры далее.

Рассмотрим ролевую модель управления в организации. Предполагаем, что справочную информацию по существующей ролевой модели мы должны будем передавать в зависимые системы в сообщениях в формате JSON посредством вызова REST-сервиса.

В организации есть сотрудники, им часто приходится работать одновременно в нескольких системах. При этом уровень доступа (полномочий) к тем или иным компонентам системы (ресурсам) для разных сотрудников в зависимости от их роли в организации может отличаться, и должен контролироваться при авторизации пользователя в системе.

Например, бухгалтер (роль) будет иметь доступ на чтение и редактирование (операции/полномочия) к расчетным листкам (ресурс) по заработной плате всех сотрудников, а у аналитика (роль), к примеру, будет доступ на чтение (операция/полномочия) только по своему расчетному листку (ресурс).

Необходимо спроектировать и описать ролевую модель управления в организации. Доступные роли, набор возможных полномочий и ресурсов в системе необходимо передавать другим системам по запросу.

Рисунок 1. Представление компонентов ролевой модели

Способы описания и реализации ролевой модели могут отличаться, но независимо от реализации чаще всего в ролевой модели в таком случае мы можем выделить следующие базовые составляющие:

  1. Роль (например, менеджер, бухгалтер и т.д.).
  2. Ресурс (например, документ, объект недвижимости и т.д.).
  3. Операция/полномочия (например, прочесть, распечатать, создать и т.д.).

Таблица 1. Дискретная матрица доступов.

Ресурс: documents Ресурс: objects
Роль: manager read, print read, create
Роль: accountant read, create read

Далее в статье мы ознакомимся сначала с теоретической составляющей текстового формата обмена данными JSON и правилами их структурирования с помощью JSON Schema, а в качестве примеров буду приводить описание сущностей-справочников для ролей, ресурсов и операций на языке JSON и их JSON–схем в рамках нашей поставленной задачи.

JavaScript Object Notation (JSON)

JSON (англ. JavaScript Object Notation) — текстовый формат обмена данными, основанный на JavaScript.

Теория

Язык разметки JSON задает ограниченный набор типов данных. Для пары для «ключа» всегда используют тип string, для «значения» применимы типы: string, number, object (тип JSON), array, boolean (true или false) и null.

Рисунок 2. Типы данных JSON

На рисунке приведены базовые типы и примеры их использования. Достаточно просто все, на мой взгляд.

Синтаксис JSON является подмножеством синтаксиса JavaScript, где:

  1. Данные записываются в виде пар .
  2. Данные разделяются запятыми.
  3. В фигурных скобках записываются объекты.
  4. В квадратных скобках записываются массивы.
  5. Наименования «ключей» регистрозависимы.

Рисунок 3. Синтаксис JSON

Практика

Рассмотрим пример справочника ролей, который мы будем передавать в сервисе:

Рисунок 4. Описание справочника ролей в формате json

Из примера видно, что даже несмотря на столь небольшое число базовых типов, при их комбинации мы можем создавать более сложные структуры сообщений при необходимости. Здесь, в частности, я описываю справочник ролей через объект массивов, содержащих другие объекты (на рисунке 4 выделены двумя прямоугольниками).

В табличном виде с помощью средств визуализации json-сообщений справочник может быть представлен следующим образом:

Рисунок 5. Визуализации справочника ролей в формате JSON

Справочник, условно говоря, представляет собой 3 «таблицы» для задания ролей в группе администраторов, бухгалтеров и рабочих. Состав «атрибутов» может быть расширен, при необходимости.

Визуальное представление, на мой взгляд, упрощает восприятие текстового описания. Аналогичную структуру зададим и для двух других справочников. Приведу ниже пример только табличного представления для справочника полномочий (операций) и ресурсов.

Рисунок 6. Визуализации справочника полномочий в формате JSON

Рисунок 7. Визуализации справочника ресурсов в формате JSON

Исходные сообщения в текстовом формате JSON для справочника ролей, ресурсов и полномочий можно скачать/просмотреть по ссылке.
Теперь перейдем к самому интересному: к изучению JSON Schema и созданию схемы под наши справочники!

JSON Schema

Теория

Поскольку схема json написана в формате JSON, она поддерживает все типы JSON плюс дополнение: тип integer, который является подтипом типа number. Сама схема является JSON-объектом и предназначена для описания данных в формате JSON. Ниже приводится схема типов данных, используемых при создании самой схемы:

Рисунок 8. Типы данных JSON Schema

Как видно из рисунка, для схемы используются все те же типы данных, а также все те же принципы синтаксиса, что и для обычного документа JSON, приведенные на рисунке 3.

Теперь рассмотрим самое важное — правила, используемые в схеме для задания ограничений и структурирования JSON-сообщений.

JSON Schema позволяет:

  1. Ограничить тип данных для элементов документа JSON.
  2. В зависимости от типа проверяемых данных, также могут быть применимы дополнительные правила — «keywords», начиная с корня схемы документа и спускаясь к их дочерним элементам.

Здесь очень важно обратить внимание, что не все версии могут поддерживаться вашим инструментом работы со схемой. Но 4-й драфт поддерживают практически все. О последних изменениях (JSON Schema 2019-09 Release Notes) для разных версий можно познакомиться по ссылке json-schema.org/draft/2019-09/release-notes.html.

Остальные ключевые слова используются непосредственно для проверки документа JSON. Их мы сейчас и рассмотрим.

Таблица 2. Анализ структуры JSON Schema. Ключевые слова и их примеры использования.

"$schema": http://json-schema.org/draft-04/schema#
"$id": "http://archi-blair.com/schemas/RolesDictionaryDef.json#"

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *