Версии и диалекты

JSON Schema развивается: за годы вышло несколько версий спецификации (их называют «черновиками», drafts). Версию схемы указывают в $schema.

$schema

$schema — URI метасхемы: схемы, которой должна соответствовать сама ваша схема. По нему валидатор понимает, по каким правилам проверять. Указывайте $schema в корне каждой схемы.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string"
}

Версия	URI $schema	Где встречается
2020-12	https://json-schema.org/draft/2020-12/schema	Актуальная версия; OpenAPI 3.1
2019-09	https://json-schema.org/draft/2019-09/schema	Переходная версия
draft-07	http://json-schema.org/draft-07/schema#	Очень распространена; многие библиотеки и конфигурации
draft-06	http://json-schema.org/draft-06/schema#	Устаревшая
draft-04	http://json-schema.org/draft-04/schema#	Устаревшая; близкие к ней схемы — в OpenAPI 3.0

Редактор «Помощника SA» проверяет схемы 2020-12 и 2019-09 по правилам 2020-12, остальные — по правилам draft-07.

Главные отличия 2020-12 от draft-07

draft-07	2020-12
definitions	$defs (старое имя работает как обычное свойство, на него можно сослаться)
items: [...] + additionalItems	prefixItems + items
dependencies	dependentRequired и dependentSchemas
Ключевые слова рядом с $ref игнорируются	Применяются вместе с $ref
Нет	unevaluatedProperties, unevaluatedItems, $anchor, $dynamicRef, minContains, maxContains

Словари

Начиная с 2019-09 ключевые слова сгруппированы в словари (vocabularies): ядро ($id, $ref, $defs), применители (allOf, properties, items), проверки (type, minimum), аннотации метаданных, форматы, содержимое. Метасхема перечисляет словари в $vocabulary: так можно создать свой диалект — например, добавить собственные ключевые слова или отключить ненужные. Для прикладных задач хватает стандартной метасхемы.

Неизвестные ключевые слова

Ключевые слова, которых нет в спецификации, валидатор игнорирует — их можно использовать как свои аннотации. Чтобы не пересечься с будущими версиями стандарта, давайте им префикс: x-internal, x-ui-widget.