Поддерживаемый JSON Schema

Схема типизатора — документ JSON Schema draft 2020-12, ограниченный подмножеством, которое понимает Typizer: корень обязан быть "type": "object", а дальше — только перечисленные ниже ключевые слова. Рабочие примеры схем для счетов и УПД — в «Счета и УПД»; что означают статусы полей ok/warn/missing — в «Проверки полей».

Поддерживаемые типыСкопировать ссылку

type — одно из семи базовых значений JSON Schema:

Поддерживаемые ключевые словаСкопировать ссылку

Любое ключевое слово вне этого списка — ошибка unsupported_schema_feature (см. ниже).

Поле pattern компилируется движком RE2 (через RE2JS), а не встроенным RegExp: часть синтаксиса (обратные ссылки, просмотр вперёд/назад) RE2 не умеет в принципе — такой pattern будет отклонён как invalid_schema, а не просто не сработает в рантайме.

Имена полейСкопировать ссылку

Имя свойства в properties (и имя записи в $defs) — юникодная буква или _, затем до 63 ещё букв, десятичных цифр, _ или - (значит, кириллица допустима наравне с латиницей: поставщик — рабочее имя поля). Имя не может быть __proto__, constructor или prototype. Это то же самое имя, что становится элементом в XML-выводе — см. «Форматы результата».

x-typizer-check: проверка реквизитаСкопировать ссылку

x-typizer-check на строковом (или числовом, для sum_of) поле включает проверку значения при извлечении. Допустимые значения:

• inn — ИНН;
• kpp — КПП;
• ogrn — ОГРН/ОГРНИП;
• bik — БИК;
• account — расчётный счёт (сверяется с соседним полем БИК, если оно есть в схеме);
• snils — СНИЛС;
• sum_of — сходимость суммы.

Для полей inn, kpp, ogrn, bik и snils Typizer проверяет их и без явного x-typizer-check, если имя самого поля — inn, kpp, ogrn/ogrnip (в оба раза — ogrn), bik или snils (без учёта регистра); account и sum_of включаются только явным x-typizer-check. Что означают результаты (ok/warn и причина, missing) и как считается каждая проверка — в «Проверки полей».

sum_of особый: он ставится на числовое поле ("type": "number") вместе с соседним ключевым словом x-typizer-sum-of, в котором — путь к полям-слагаемым относительно объекта, держащего это числовое поле; [] в пути значит «каждый элемент массива», например:

{
  "total": {
    "type": "number",
    "x-typizer-check": "sum_of",
    "x-typizer-sum-of": "items[].amount"
  }
}

Без x-typizer-sum-of (или если type поля — не number) схема со x-typizer-check: "sum_of" отклоняется как invalid_schema.

$defs и $ref: без цикловСкопировать ссылку

$defs — только в корне схемы, объект с именованными под-схемами. $ref — строка вида #/$defs/<имя> и ничего больше (внешние ссылки, ссылки на под-пути и JSON Pointer-выражения не поддерживаются); рядом с $ref разрешены только description и title, любое другое соседнее ключевое слово — unsupported_schema_feature. Каждая запись $defs проверяется сразу при валидации схемы, даже если на неё нет ни одной ссылки — так неработающее, но неиспользуемое определение не может «спрятаться». Ссылка на саму себя или на определение, которое (прямо или через цепочку $ref) ссылается обратно на неё, — ошибка invalid_schema: циклы не поддерживаются.

Что будет при неподдерживаемом ключевом словеСкопировать ссылку

Два разных кода ошибки, оба со статусом 422 и param в виде JSON Pointer на место проблемы (schema#/properties/…):

• unsupported_schema_feature — ключевое слово, тип, формат или проверка существуют в JSON Schema (или в x-typizer-*), но Typizer их не поддерживает: ключевое слово вне списка выше (oneOf, anyOf, allOf, if, patternProperties и т. д.), неподдерживаемый type или format, additionalProperties, отличный от false, $defs не в корне, неизвестный x-typizer-check;
• invalid_schema — само значение ключевого слова некорректно: pattern, который не компилируется или длиннее 200 символов, нечисловые или нечисловые minimum/maximum, пустой или с повторами enum, сломанный или циклический $ref, схема без properties, недопустимое имя поля, превышение одного из лимитов ниже.

Лимит числа полей и другие ограниченияСкопировать ссылку

Схема — не больше 200 полей (MAX_SCHEMA_FIELDS): считается каждая запись properties на любом уровне, и каждое использование $ref учитывает поля своей цели заново (раскрытия не дедуплицируются). Другие ограничения, за которыми Typizer тоже следит:

Схема, нарушающая любое из них, отклоняется как invalid_schema (или, для общего размера — отдельным кодом на уровне запроса) ещё до начала обработки документа.

Что дальшеСкопировать ссылку

• «Счета и УПД» — готовые рабочие схемы.
• «Проверки полей» — что значат статусы ok/warn/missing.
• «Форматы результата» — как схема превращается в JSON, XML, CSV и XLSX.
• «Лимиты» — лимиты файла, страниц и запросов.