Структура и ссылки

Большие схемы разбивают на части: общие определения выносят в $defs, повторно используют через $ref, а схемы разных сущностей хранят в отдельных файлах.

$defs и $ref

$defs — место для вспомогательных схем. $ref подключает схему по ссылке: # — корень текущего документа, дальше — путь в формате JSON Pointer.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "billingAddress": { "$ref": "#/$defs/address" },
    "shippingAddress": { "$ref": "#/$defs/address" }
  },
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "street": { "type": "string" },
        "zip": { "type": "string", "pattern": "^\\d{6}$" }
      },
      "required": ["city", "street"]
    }
  }
}

{ "billingAddress": { "city": "Москва", "street": "Тверская, 1" } }

В JSON Pointer символ / в имени экранируется как ~1, а ~ — как ~0. В версии 2020-12 рядом с $ref можно писать другие ключевые слова — они применяются вместе со ссылкой. В draft-07 всё, кроме $ref, рядом с ним игнорируется.

$id и ссылки между файлами

$id задаёт схеме базовый URI. Относительные ссылки в $ref разрешаются от него, как ссылки на веб-странице:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/order.json",
  "type": "object",
  "properties": {
    "customer": { "$ref": "customer.json" },
    "items": {
      "type": "array",
      "items": { "$ref": "product.json#/$defs/line" }
    }
  }
}

Здесь customer.json означает https://example.com/schemas/customer.json. $id — это идентификатор, а не обязательно адрес для скачивания: валидатор ищет схемы среди загруженных.

В проектах «Помощника SA» внешние $ref разрешаются по дереву папок проекта: "$ref": "common/address.json" найдёт файл address.json в папке common рядом с текущей схемой, а Ctrl+клик по ссылке откроет его.

$anchor

$anchor даёт подсхеме короткое имя, на которое можно сослаться как #имя — без длинного пути JSON Pointer:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "phone": { "$ref": "#phone" }
  },
  "$defs": {
    "phoneNumber": {
      "$anchor": "phone",
      "type": "string",
      "pattern": "^\\+\\d{11}$"
    }
  }
}

Рекурсия

Схема может ссылаться сама на себя — так описывают деревья: категории с подкатегориями, комментарии с ответами.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "category": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/$defs/category" }
        }
      },
      "required": ["name"]
    }
  },
  "$ref": "#/$defs/category"
}

{ "name": "Техника", "children": [{ "name": "Кухня", "children": [{ "name": "Кофемолки" }] }] }

Упаковка схем

Многофайловую схему можно собрать в один файл: внешние схемы переносятся в $defs вместе со своими $id, и ссылки продолжают работать. Так удобно публиковать схему одним документом.

$dynamicRef

$dynamicRef и $dynamicAnchor (версия 2020-12) — ссылки, цель которых определяется во время проверки. Они нужны для расширяемых рекурсивных схем, например метасхем; в прикладных схемах обычно достаточно $ref.