← Все статьи

JSON Schema и XSD: как описывать структуры данных и где их разница бьёт по интеграции

· 8 мин чтения

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

Структуру сообщения или документа почти всегда нужно описать формально: чтобы проверять данные, генерировать код и не спорить о том, что значит «поле необязательное». Для XML стандартом де-факто является XSD, для JSON — JSON Schema. На первый взгляд они решают одну задачу, и многие инструменты, включая наш, умеют конвертировать одно в другое. Но модели данных за ними разные, и именно на стыке — в интеграциях, где одна сторона говорит на JSON, а другая на XML, — эти различия превращаются в ошибки. Разберём, в чём они состоят.

Коротко о каждом языке

XSD

XML Schema Definition (XSD) — стандарт W3C (версия 1.0 — 2001 год, 1.1 — 2012). Описывает элементы и атрибуты XML-документа, их типы, порядок и количество. Сама схема — тоже XML-документ. XSD лежит в основе WSDL и SOAP, большинства отраслевых стандартов (банковские ISO 20022, медицинский HL7 v3, многие государственные форматы обмена) и электронного документооборота.

<xs:complexType name="Customer">
  <xs:sequence>
    <xs:element name="name" type="xs:string"/>
    <xs:element name="birthDate" type="xs:date" minOccurs="0"/>
    <xs:element name="phone" type="xs:string" maxOccurs="3"/>
  </xs:sequence>
  <xs:attribute name="id" type="xs:long" use="required"/>
</xs:complexType>

JSON Schema

JSON Schema — спецификация, развиваемая сообществом в виде черновиков (draft-04, draft-07, 2019-09, 2020-12). Описывает JSON-документы и сама является JSON. На её диалекте построены схемы в OpenAPI 3.1 и AsyncAPI, её используют для проверки конфигураций, форм и сообщений.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "birthDate": { "type": "string", "format": "date" },
    "phone": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 3 }
  },
  "required": ["id", "name", "phone"]
}

Главное различие: модель данных

XML — это дерево именованных узлов с порядком, атрибутами, смешанным содержимым и пространствами имён. JSON — это объекты, массивы и примитивы. Отсюда вытекают почти все остальные различия.

АспектXSD / XMLJSON Schema / JSON
Подходграмматика: что разрешенонабор проверок: каким условиям должен удовлетворять документ
Порядок полейзначим (sequence)не значим в объекте
Атрибутыесть, отдельно от элементовнет, только свойства
Массивынет как понятия: повторяющийся элемент (maxOccurs)явный тип array
Типыбогатая система: около 45 встроенных типов (date, decimal, duration...)шесть основных: string, number, integer, boolean, object, array (+ null); даты — через format
Пространства имёнестьнет
Наследование типовextension, restrictionнет; композиция через allOf, anyOf, oneOf
Лишние полязапрещены по умолчаниюразрешены по умолчанию
Условные правилаограниченно (xs:assert в 1.1)if/then/else, dependentRequired

Где различия бьют по интеграции

1. Лишние поля: строгость по умолчанию противоположная

XSD запрещает всё, что не описано: появился новый элемент — документ невалиден. JSON Schema разрешает неописанные свойства, пока явно не указано "additionalProperties": false.

Последствия:

  • в XML-интеграции добавление нового необязательного поля ломает потребителей, которые валидируют входящие документы строго; для расширяемости в XSD заранее закладывают xs:any;
  • в JSON-интеграции, наоборот, опечатка в имени поля ("birthdate" вместо "birthDate") молча проходит проверку, а поле просто теряется.

Решение — явно договориться о политике: строгая проверка на входе (опечатки ловятся) или терпимая (новые поля не ломают). В JSON Schema это additionalProperties или unevaluatedProperties, в XSD — места расширения через xs:any.

2. Обязательность и пустые значения

Здесь больше всего недопонимания. В JSON у поля есть как минимум три состояния: отсутствует, равно null, имеет значение (включая пустую строку). В XML — свои: элемент отсутствует, присутствует пустым (<phone/>), присутствует с xsi:nil="true" или имеет значение.

СмыслJSON SchemaXSD
поле обязательноимя в requiredminOccurs="1" (по умолчанию)
поле может отсутствоватьнет в requiredminOccurs="0"
поле присутствует, но пустое"type": ["string", "null"]nillable="true" + xsi:nil
пустая строка запрещена"minLength": 1restriction с minLength value="1"

При преобразовании JSON → XML ответ на вопрос «во что превращается null» должен быть зафиксирован в маппинге: в отсутствие элемента, в пустой элемент или в xsi:nil. А при обновлении данных различие критично: «поле не передано» часто означает «не менять», а «передан null» — «стереть значение».

3. Массив из одного элемента

В XML нет массивов — есть повторяющиеся элементы. При автоматическом преобразовании XML в JSON без схемы конвертер не знает, массив перед ним или нет:

<phones><phone>111</phone></phones>          → {"phones": {"phone": "111"}}
<phones><phone>111</phone><phone>222</phone></phones> → {"phones": {"phone": ["111", "222"]}}

Структура JSON зависит от данных, и потребитель падает в тот день, когда у клиента впервые оказывается один телефон. Конвертация должна опираться на схему (maxOccurs > 1 → всегда массив), а не на содержимое документа.

4. Типы данных

  • Числа. В JSON number обычно разбирается как число с плавающей точкой двойной точности, и большие целые (больше 253) или денежные суммы теряют точность в JavaScript. XSD различает xs:decimal (точное десятичное), xs:long, xs:double. Для денег и длинных идентификаторов в JSON надёжнее строка с шаблоном.
  • Даты. В XSD xs:date и xs:dateTime — настоящие типы, валидатор проверит формат. В JSON Schema "format": "date-time" по умолчанию лишь аннотация; проверяется, только если валидатор это поддерживает и включено.
  • Ведущие нули. Код 007, объявленный в XSD как xs:string, при небрежной конвертации в JSON может стать числом 7. ИНН, коды подразделений, номера счетов — всегда строки.
  • Логические значения. В XML допустимы true, false, 1, 0; в JSON — только true и false.

5. Атрибуты и текстовое содержимое

Атрибуту XML в JSON нечем соответствовать, поэтому конвертеры придумывают соглашения: префикс @ ("@id": "42"), поле #text или $ для текста элемента с атрибутами. Соглашений несколько, и разные инструменты используют разные. Если интеграция идёт через такой конвертер, соглашение должно быть зафиксировано в контракте.

6. Порядок

xs:sequence требует определённого порядка элементов. Объект JSON порядка не имеет. При сборке XML из JSON порядок задаёт маппинг или генератор по схеме — если собирать «как пришло», документ не пройдёт валидацию. Обратная проблема: если порядок в XML несёт смысл (шаги процедуры), в JSON его нужно выразить массивом, а не объектом.

7. Выбор одного из вариантов

xs:choice (ровно один из элементов) соответствует oneOf в JSON Schema, но oneOf проверяет, что документ подходит ровно под одну из подсхем. Если подсхемы пересекаются (например, обе разрешают лишние поля), документ может подойти под обе и не пройти проверку. Для надёжности варианты различают явным полем-дискриминатором ("type": "individual" / "legal").

8. Пространства имён

XML-элемент определяется парой «пространство имён + локальное имя». <a:order> и <b:order> — разные элементы. В JSON пространств имён нет, и при конвертации они либо теряются, либо попадают в имена полей. Если в одном документе встречаются одноимённые элементы из разных пространств, это нужно решить в маппинге явно.

Повторное использование и модульность

XSD: глобальные типы и элементы, xs:include (схемы одного пространства имён) и xs:import (другого), наследование через extension и restriction, группы элементов и атрибутов. Большие отраслевые стандарты состоят из десятков файлов, и разобраться в них помогает визуализатор.

JSON Schema: определения в $defs (в старых версиях — definitions), ссылки $ref на другие файлы по URI, композиция через allOf. Наследования нет: «расширение» типа — это allOf из базовой схемы и дополнительных свойств, и с additionalProperties: false это сочетается плохо (для этого в 2019-09 появилось unevaluatedProperties).

Версии и совместимость инструментов

У JSON Schema несколько несовместимых черновиков, и инструменты поддерживают разные:

  • OpenAPI 3.0 использует собственное подмножество, близкое к draft-04/05 (там nullable: true вместо типа null);
  • OpenAPI 3.1 полностью совместим с JSON Schema 2020-12;
  • многие генераторы кода и валидаторы до сих пор лучше всего поддерживают draft-07.

В контракте всегда указывайте $schema — версию, по которой схема написана. С XSD проще: почти везде используется 1.0, а возможности 1.1 (xs:assert, открытое содержимое) поддерживаются далеко не всеми библиотеками — например, стандартная Java (JAXP) поддерживает только 1.0.

Конвертация между схемами: что теряется

НаправлениеЧто переносится хорошоЧто теряется или требует решения
XSD → JSON Schemaструктура, типы, обязательность, перечисления, шаблоны, длиныатрибуты (соглашение об именах), порядок, пространства имён, наследование (разворачивается), смешанное содержимое
JSON Schema → XSDобъекты, массивы, примитивы, ограниченияnull (нужен nillable), условные правила if/then, anyOf с пересечениями, свободные словари (additionalProperties со схемой), выбор между элементом и атрибутом

Сгенерированная схема — хорошая отправная точка, но её нужно просмотреть глазами: проверить массивы, null, точность чисел и строгость к лишним полям.

Чек-лист для интеграции JSON — XML

  • какая схема первична и какая получена из неё;
  • версия JSON Schema ($schema) и XSD;
  • политика лишних полей с каждой стороны;
  • соответствие «отсутствует / null / пусто» в обе стороны;
  • поля, которые всегда массивы, даже из одного элемента;
  • типы для денег, больших чисел, кодов с ведущими нулями;
  • форматы дат, времени и часовых поясов;
  • соглашение для атрибутов и текстового содержимого;
  • порядок элементов при сборке XML;
  • обработка пространств имён;
  • набор тестовых документов на каждый граничный случай.

Итог

XSD и JSON Schema описывают структуры данных, но исходят из разных моделей: дерево с порядком и атрибутами против объектов и массивов. XSD по умолчанию строг, JSON Schema по умолчанию терпим. Различия в обязательности, null, массивах и типах — главные источники ошибок на стыке форматов. Их не решить автоматическим конвертером — только явными договорённостями в контракте и маппинге.

Схемы удобно редактировать и проверять в редакторе JSON Schema и редакторе XSD, а конвертировать — по гайдам «XSD в JSON Schema» и «JSON Schema в XSD». Как проверить документ по схеме — в гайдах «Проверка JSON по схеме» и «Проверка XML по XSD». О преобразовании самих документов — «XML в JSON» и «JSON в XML».