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. Дискретная матрица доступов.

Далее в статье мы ознакомимся сначала с теоретической составляющей текстового формата обмена данными 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», начиная с корня схемы документа и спускаясь к их дочерним элементам.

Некоторые «ключевые слова» являются чисто описательными, как например: «title», «description» и др., которые просто описывают предназначение схемы. Другие предназначены для идентификации документа: «$schema». Это ключевое слово используется для указания желаемой версии схемы. Значение этого ключевого слова должно быть строкой, представляющей URI, например: «$schema»: «json-schema.org/draft-04/schema#».

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

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

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

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

Здесь вы можете найти больше примеров использования ключевых слов.

Практика

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

Ниже приводится схема для справочника ролей.

Рисунок 9. Пример JSON Schema для справочника ролей

Как мы видим на рисунке, схема представляет собой JSON-объект и описывает наше сообщение для передачи справочника ролей в формате JSON, которое приводилось на рисунке 4. На текущем примере представлено как с помощью JSON схемы может быть описан объект массивов, состоящий из объектов.

Схемы двух других справочников (полномочий и ресурсов) по своей структуре идентичны со схемой для справочника ролей, поэтому не буду их здесь приводить, а приведу схему, объединяющую в себе все 3 справочника.

К сожалению, схема всего справочника при раскрытии не поместится на экране, поэтому рассмотрим ее часть.

Рисунок 10. Пример JSON Schema справочника, объединяющего в себе справочник ролей, полномочий и ресурсов

На рисунке мы видим, что часть объектов массива справочников подключена с использованием ключевого слова «anyOf».

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

Рассмотрим еще одну важную особенность нашей схемы:

Рисунок 11. Пример JSON Schema справочника, объединяющего в себе справочник ролей, полномочий и ресурсов в табличном представлении

Из рисунка мы видим, что объединяющий справочник не дублирует в себе код из ранее разработанных справочников ролей, полномочий и ресурсов, а использует ключевое слово «$ref».

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

На этом мой обзор JSON и JSON Schema я завершаю. Надеюсь, что приведенный здесь материал и рассмотренные примеры, окажутся полезными при изучении возможностей JSON Sсhema.

Вместо заключения

Думаю, пора подводить итоги. Так что же применение JSON Schema в итоге нам может дать?

1. Может упростить жизнь разработчикам и улучшить код по валидации JSON -сообщений.
   Иными словами, это упрощение поддержки и интеграции ПО.
2. Позволит разрабатывать сервисы, прорабатывая форматы и состав данных с «заделом» на будущее развитие системы.
3. Применить проверку документов в документо-ориентированных, объектно-ориентированных БД.
4. JSON-Schema может помочь сэкономить время на тестировании и документировании API.
5. Упрощение поддержки обратной совместимости API.
6. Позволит управлять потоками данных.
7. Гибкую валидацию при генерации JSON Schema в run-time со значениями в «enum», получаемыми на этапе выполнения программы.
   Возможно применение для конечного автомата или workflow со статусами в «enum» (пример применения от NtsDK и VolCh).
8. JSON Schema может быть применена при реализации DTO
   (пример использования от amarkevich)

Каждый из нас сам решает, «Быть или не быть JSON Schema» в наших IT -проектах. Выше я привела список того, что я считаю ключевым преимуществом применения схем, и ради чего уже стоит задуматься о ее применении в проектах.

Возможно, читатели захотят помочь мне продолжить этот список?

Я буду признательна 🙂

Также приведу список ссылок, на мой взгляд, полезных для работы с JSON и JSON Schema

1. Официальный источник с примерами использования ключевых слов схемы.
2. Источник с большим числом примеров использования ключевых слов схемы.
3. Официальная страница стандарта (драфта).
4. Список релизов (полезно для понимания динамики развития стандарта).
5. Онлайн-валидатор с возможностью выбрать нужную версию драфта JSON-Schema.
6. Открытый репозиторий JSON Schema
7. JSON Schema для создания динамических интерфейсов, который может создаваться самим заказчиком (по рекомендации от alemiks), а также аналоги из мира angular ngx-schema-form, AJSF (по рекомендации от anotherpit).

И ссылку на git-репозиторий, где можно ознакомиться с исходными файлами, приводимыми для ознакомления в данной статье: репозиторий с исходными файлами примеров.

Системный архитектор,
© Ирина Блажина

JSON Schema | WebReference

Рассмотрим следующий JSON-документ.

{
  "artists" : [
    { 
      "artistname" : "Deep Purple",
      "formed" : "1968"
    },
    { 
      "artistname" : "Joe Satriani",
      "born" : "1956-07-15" 
    },
    { 
      "artistname" : "Maroon 5",
      "formed" : "1994" 
    }
  ]
}

В данном примере применяется разный формат даты у объектов. Кроме того, один объект использует 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-файла, чтобы убедиться, что он содержит только правильный тип данных.

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

{ "type": "string" }

Вот пример базовой схемы 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.

{ "$schema": "http://json-schema.org/schema#" }

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

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

{ "$schema": "http://json-schema.org/draft-04/schema#" }

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

Автор и редакторы

Автор: Йен Диксон

Последнее изменение: 11.10.2019

Редакторы: Влад Мержевич

Типы данных JSON
Ctrl+←

JSON и XML
Ctrl+→

Схема JSON | Дом JSON Schema

JSON Schema — это словарь, который позволяет вам аннотировать и проверять документов JSON.

Преимущества #

• Описывает существующие форматы данных.
• Обеспечивает четкую документацию, удобочитаемую человеком и машиной.
• Проверяет данные, которые полезны для:
  • Автоматизированное тестирование.
  • Обеспечение качества предоставляемых клиентом данных.

Объявления и запрос обратной связи: процесс спецификации #

• Типы носителей JSON Schema ( application/schema+json и application/schema-instance+json ) будут опубликованы как IETF RFC, который уже принят рабочей группой HTTP API.
• Будучи проектом OpenJS Foundation со статусом инкубации, мы продолжаем работать над нашим списком задач управления, чтобы перейти к статусу At-Large или Impact.
• Основная часть нашей спецификации будет опубликована в рамках нового процесса, который сейчас находится на стадии публичного обсуждения. Всем предлагается оставить отзыв! Наши цели в этом процессе включают в себя:
  • В следующем выпуске предоставьте гарантии стабильности для давно стабильных аспектов схемы JSON.
  • Дайте ясность относительно того, какие другие аспекты близки к стабильной форме, а какие являются более экспериментальными.
  • Опубликуйте наши спецификации так же, как OpenAPI и AsyncAPI, которые также являются частью Linux Foundation (более крупного зонтика, под которым существует OpenJS Foundation).
• Мы работаем над тем, чтобы найти правильный путь для стандартизации относительного указателя JSON в ближайшем будущем. RFC IETF в настоящее время остается наиболее вероятным путем, хотя некоторые детали все еще прорабатываются.

Что теперь? #

Учитесь, получайте помощь, формируйте сообщество, общайтесь в чате с командой JSON Schema и сообществом!

👋 Начало работы Open JSON Schema Slack💬 Обсуждения сообщества

Регулярные занятия #

Мы еженедельно проводим рабочие часы и два раза в месяц открытые рабочие собрания сообщества.

🧑‍💻 Часы работы
👷 Открытые рабочие собрания сообщества

Часы работы — каждый первый вторник месяца в 15:00 BST и по предварительной записи.

Открытые рабочие собрания сообщества проводятся каждый понедельник в 14:00 по тихоокеанскому времени.

Если какой-либо из них будет отменен или перенесен по какой-либо причине, мы постараемся объявить об этом через канал объявлений Slack и Twitter.
Смотрите наш календарь сообщества (и не забудьте проверить часовой пояс).

Нужно больше? #

У нас есть другие учебные ресурсы, включая документацию Understanding JSON Schema.

У нас активное и растущее сообщество. Все желающие могут стать частью нашего сообщества, помочь сформировать его или просто понаблюдать.

Мы хотим, чтобы наше сообщество было приветливым и инклюзивным, поэтому, пожалуйста, ознакомьтесь с нашим Кодексом корпоративной этики JSON Schema. (Это комбинация Contributor Covenant и IETF BCP 54.)

Команда JSON Schema и сообщество готовы помочь!

В любой момент вы можете присоединиться к нашему серверу Slack.

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

Мы отслеживаем тег jsonschema на StackOverflow.

10.06.2022: Выпущен выпуск исправления Draft 2020-12 без функциональных изменений.

Новые идентификаторы документов IETF имеют вид draft-bhutton-*-01 .

01.02.2021: Опубликован проект 2020-12!

Идентификаторы документов IETF имеют форму draft-bhutton-*-00 .

Мы используем даты для метасхем, которые реализации должны использовать для определения поведения,
поэтому мы обычно будем ссылаться на 2020-12 (без слова «черновик») на этом веб-сайте.

Подробнее об именах и нумерации см. на странице «Технические характеристики».

Быстрый старт #

Проверяемый или описываемый документ JSON мы называем экземпляр , а документ, содержащий описание, называется схемой .

Самая простая схема — это пустой объект JSON, который ничего не ограничивает, ничего не разрешает и ничего не описывает:

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

 { «тип»: «строка» }
 

Схема JSON готова к гипермедиа и идеально подходит для аннотирования существующего HTTP API на основе JSON. Документы схемы JSON идентифицируются с помощью URI, которые можно использовать в заголовках ссылок HTTP и внутри документов схемы JSON, чтобы разрешить рекурсивные определения.

Гиперсхема JSON #

Гипер-схема JSON находится на паузе / в настоящее время не поддерживается с 2021 года.

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

Мы можем вернуться к гиперсхеме JSON позднее.

Заинтересованы? Отъезд:

• Понимание схемы JSON
• Спецификация
• Учебные ресурсы
• растущий список программного обеспечения JSON Schema

Мы рекомендуем по возможности обновляться до последней спецификации, то есть до версии 2020-12.

Вопросы? Чувствуете себя полезным? Присоединяйтесь:

• GitHub
• Обсуждения GitHub
• Группы Google
• Слабый
• Открытый коллектив

Пошаговое руководство по началу работы | Схема JSON

• Введение
• Запуск схемы
• Определение свойств
• Углубление свойств
• Вложенные структуры данных
• Ссылки вне схемы
• Просмотр данных для нашей определенной схемы JSON

Введение #

Следующий пример ни в коем случае не является окончательным для всех значений, которые может предоставить схема JSON. Для этого вам нужно будет углубиться в саму спецификацию — подробнее на https://json-schema.org/specification.html.

Давайте представим, что мы взаимодействуем с каталогом продуктов на основе JSON. В этом каталоге есть продукт, который имеет:

• Идентификатор: productId
• Название продукта: productName
• Стоимость продажи для потребителя: цена
• Дополнительный набор тегов: тегов .

Например:

 {
  "идентификатор продукта": 1,
  "productName": "Зеленая дверь",
  "цена": 12.50,
  "теги": [ "дом", "зеленый" ]
}
 

Несмотря на то, что этот пример в целом прост, некоторые вопросы остаются открытыми. Вот лишь некоторые из них:

• Что такое productId ?
• Требуется ли productName ?
• Может ли цена быть равной нулю (0)?
• Являются ли все тегов строковыми значениями ?

Когда вы говорите о формате данных, вы хотите иметь метаданные о том, что означают ключи, включая допустимые входные данные для этих ключей. JSON-схема — это предлагаемый стандарт IETF, как отвечать на эти вопросы для данных.

Запуск схемы #

Чтобы начать определение схемы, давайте начнем с базовой схемы JSON.

Мы начинаем с четырех свойств, называемых ключевыми словами , которые выражены в виде ключей JSON.

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

• Ключевое слово $schema указывает, что эта схема написана в соответствии с конкретным проектом стандарта и используется по разным причинам, в первую очередь для контроля версий.
• Ключевое слово $id определяет URI для схемы и базовый URI, по которому разрешаются другие ссылки URI в схеме.
• Ключевые слова заголовка и описания аннотации являются только описательными. Они не добавляют ограничений к проверяемым данным. Назначение схемы указывается с помощью этих двух ключевых слов.
• Ключевое слово проверки типа определяет первое ограничение для наших данных JSON, и в этом случае это должен быть объект JSON.

 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "название": "Товар",
  "description": "Товар в каталоге",
  "тип": "объект"
}
 

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

• Ключевое слово схемы: $schema и $id .
• Аннотации схемы: заголовок и описание .
• Ключевое слово проверки: введите .

Определение свойств #

productId — числовое значение, которое однозначно идентифицирует продукт. Так как это канонический идентификатор товара, без него не имеет смысла иметь продукт, поэтому он обязателен.

В терминах схемы JSON мы обновляем нашу схему, добавляя:

• Ключевое слово проверки свойств .
• Ключ productId .
  • описание аннотация схемы и тип отмечено ключевое слово проверки — мы рассмотрели оба из них в предыдущем разделе.
• требуется ключевое слово проверки, перечисляющее productId .

 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "название": "Товар",
  "description": "Товар из каталога Acme",
  "тип": "объект",
  "характеристики": {
    "Код товара": {
      "description": "Уникальный идентификатор товара",
      "тип": "целое число"
    }
  },
  "требуется": [ "идентификатор продукта" ]
}
 

• productName — строковое значение, описывающее продукт. Так как в продукте мало что есть без имени, оно также необходимо.
• Поскольку обязательное ключевое слово проверки представляет собой массив строк, мы можем отметить несколько ключей по мере необходимости; Теперь мы включаем productName .
• На самом деле нет никакой разницы между productId и productName — мы включаем оба для полноты картины, поскольку компьютеры обычно обращают внимание на идентификаторы, а люди обычно обращают внимание на имена.

 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "название": "Товар",
  "description": "Товар из каталога Acme",
  "тип": "объект",
  "характеристики": {
    "Код товара": {
      "description": "Уникальный идентификатор товара",
      "тип": "целое число"
    },
    "наименование товара": {
      "description": "Название продукта",
      "тип": "строка"
    }
  },
  "требуется": [ "productId", "productName" ]
}
 

Углубляемся в свойства #

По словам владельца магазина бесплатных товаров нет. 😉

• Ключ цена добавляется с обычным описанием аннотацией схемы и типом ключевых слов проверки, рассмотренных ранее. Он также включен в массив ключей, определяемый ключевым словом required validation.
• Указываем значение цена должен быть чем-то отличным от нуля, используя ключевое слово проверки эксклюзивныйМинимум .
  • Если бы мы хотели включить ноль в качестве действительной цены, мы бы указали минимальное ключевое слово проверки .

 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "название": "Товар",
  "description": "Товар из каталога Acme",
  "тип": "объект",
  "характеристики": {
    "Код товара": {
      "description": "Уникальный идентификатор товара",
      "тип": "целое число"
    },
    "наименование товара": {
      "description": "Название продукта",
      "тип": "строка"
    },
    "цена": {
      "description": "Цена товара",
      "тип": "число",
      "эксклюзивный минимум": 0
    }
  },
  "обязательно": [ "productId", "productName", "price" ]
}
 

Далее мы подходим к тегам ключу.

Владелец магазина сказал следующее:

• Если есть бирки, то должна быть хотя бы одна бирка,
• Все теги должны быть уникальными; отсутствие дублирования в рамках одного продукта.
• Все теги должны быть текстовыми.

Теги

• хороши, но их наличие не обязательно.

Следовательно:

• Ключ tags добавляется с обычными аннотациями и ключевыми словами.
• На этот раз ключевое слово проверки type — array .
• Мы вводим ключевое слово проверки элементов , чтобы мы могли определить, что появляется в массиве. В этом случае: строк значений с помощью ключевого слова проверки типа .
• Ключевое слово проверки minItems используется, чтобы убедиться, что в массиве есть хотя бы один элемент.
• Ключевое слово проверки uniqueItems отмечает, что все элементы в массиве должны быть уникальными относительно друг друга.
• Мы не добавили этот ключ в требуемый массив ключевых слов проверки , поскольку он является необязательным.

 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "название": "Товар",
  "description": "Товар из каталога Acme",
  "тип": "объект",
  "характеристики": {
    "Код товара": {
      "description": "Уникальный идентификатор товара",
      "тип": "целое число"
    },
    "наименование товара": {
      "description": "Название продукта",
      "тип": "строка"
    },
    "цена": {
      "description": "Цена товара",
      "тип": "число",
      "эксклюзивный минимум": 0
    },
    "теги": {
      "description": "Теги товара",
      "тип": "массив",
      "Предметы": {
        "тип": "строка"
      },
      "минимумы": 1,
      "уникальные предметы": правда
    }
  },
  "обязательно": [ "productId", "productName", "price" ]
}
 

Вложенные структуры данных #

До этого момента мы имели дело с очень плоской схемой — всего один уровень. В этом разделе демонстрируются вложенные структуры данных.

• Ключ размеры добавлен с использованием концепций, которые мы обнаружили ранее. Поскольку ключевое слово проверки типа является объектом , мы можем использовать ключевое слово проверки свойств для определения вложенной структуры данных.
  • Мы опустили описание ключевое слово аннотации для краткости в примере. Хотя обычно предпочтительнее подробно аннотировать, в этом случае структура и имена ключей хорошо знакомы большинству разработчиков.
• Вы заметите, что область необходимого ключевого слова проверки применима к ключу измерений и не выходит за его пределы.

 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "название": "Товар",
  "description": "Товар из каталога Acme",
  "тип": "объект",
  "характеристики": {
    "Код товара": {
      "description": "Уникальный идентификатор товара",
      "тип": "целое число"
    },
    "наименование товара": {
      "description": "Название продукта",
      "тип": "строка"
    },
    "цена": {
      "description": "Цена товара",
      "тип": "число",
      "эксклюзивный минимум": 0
    },
    "теги": {
      "description": "Теги товара",
      "тип": "массив",
      "Предметы": {
        "тип": "строка"
      },
      "минимумы": 1,
      "уникальные предметы": правда
    },
    "Габаритные размеры": {
      "тип": "объект",
      "характеристики": {
        "длина": {
          "тип": "число"
        },
        "ширина": {
          "тип": "число"
        },
        "высота": {
          "тип": "число"
        }
      },
      «требуется»: [ «длина», «ширина», «высота»]
    }
  },
  "обязательно": [ "productId", "productName", "price" ]
}
 

Ссылки вне схемы #

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

В этом примере мы вводим новый ресурс схемы JSON и для обоих свойств в нем:

• Мы используем ключевое слово проверки минимум , отмеченное ранее.
• Добавляем максимум ключевое слово проверки.
• В совокупности они дают нам диапазон для проверки.

 {
  "$id": "https://example.com/geographical-location.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Долгота и широта",
  "description": "Географическая координата на планете (чаще всего Земля).",
  «требуется»: [ «широта», «долгота» ],
  "тип": "объект",
  "характеристики": {
    "широта": {
      "тип": "число",
      "минимум": -90,
      "максимум": 90
    },
    "долгота": {
      "тип": "число",
      «минимум»: -180,
      "максимум": 180
    }
  }
}
 

Затем мы добавляем ссылку на эту новую схему, чтобы ее можно было включить.

 {
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "$id": "https://example.com/product.schema.json",
 "название": "Товар",
 "description": "Товар из каталога Acme",
 "тип": "объект",
 "характеристики": {
 "Код товара": {
 "description": "Уникальный идентификатор товара",
 "тип": "целое число"
 },
 "наименование товара": {
 "description": "Название продукта",
 "тип": "строка"
 },
 "цена": {
 "description": "Цена товара",
 "тип": "число",
 "эксклюзивный минимум": 0
 },
 "теги": {
 "description": "Теги товара",
 "тип": "массив",
 "Предметы": {
 "тип": "строка"
 },
 "минимумы": 1,
 "уникальные предметы": правда
 },
 "Габаритные размеры": {
 "тип": "объект",
 "характеристики": {
 "длина": {
 "тип": "число"
 },
 "ширина": {
 "тип": "число"
 },
 "высота": {
 "тип": "число"
 }
 },
 «требуется»: [ «длина», «ширина», «высота»]
 },
 "Местоположение склада": {
 "description": "Координаты склада, на котором находится товар.
This entry was posted in Популярное