Структуру сообщения или документа почти всегда нужно описать формально: чтобы проверять данные, генерировать код и не спорить о том, что значит «поле необязательное». Для 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 / XML | JSON 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 Schema | XSD |
|---|---|---|
| поле обязательно | имя в required | minOccurs="1" (по умолчанию) |
| поле может отсутствовать | нет в required | minOccurs="0" |
| поле присутствует, но пустое | "type": ["string", "null"] | nillable="true" + xsi:nil |
| пустая строка запрещена | "minLength": 1 | restriction с 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».
