XSD в JSON Schema: как перенести схему из XML в JSON

При переводе интеграции с SOAP или XML-файлов на REST схему данных приходится переписывать на JSON Schema. Автоматическое преобразование переносит структуру и ограничения, а неизбежные потери показывает списком.

Как преобразовать

1. Откройте схему в редакторе XSD (лучше — из проекта, если она подключает другие файлы).
2. Выберите Файл → Преобразовать в → JSON Schema.
3. Изучите замечания в окне и сохраните результат в проект или откройте в песочнице JSON Schema.

Как переносятся конструкции

• Именованные типы — определения в $defs, ссылки — $ref.
• Элементы — свойства объекта; minOccurs="0" — необязательное свойство; maxOccurs больше 1 — массив с minItems/maxItems.
• Атрибуты — свойства с префиксом @, текст элемента с атрибутами — #text (те же соглашения, что в конвертере XML в JSON).
• Простые типы: xs:integer → integer, xs:decimal → number, xs:date → string с форматом date и т. д.; фасеты minLength, maxLength, pattern, minInclusive и другие переносятся; xs:enumeration → enum.
• Наследование (xs:extension) — allOf из базового типа и собственных свойств.
• Корень — объект с одним свойством из глобальных элементов схемы.
• Документация (xs:documentation) — description.

Что передаётся неточно

• xs:choice становится набором необязательных свойств — правило «ровно одно из» не проверяется.
• Порядок элементов (xs:sequence) в JSON не значим.
• Пространства имён не переносятся; targetNamespace сохраняется в комментарии.
• Шаблоны XSD проверяют значение целиком, поэтому в JSON Schema они получают якоря ^…$.

Подключённые схемы

Файлы из xs:include и xs:import находятся по дереву папок проекта, их типы встраиваются в $defs. Окно перечисляет встроенные файлы и те, что найти не удалось.

Пример

<xs:simpleType name="Money">
  <xs:restriction base="xs:decimal"><xs:minInclusive value="0"/></xs:restriction>
</xs:simpleType>
<xs:element name="order">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="total" type="Money"/>
      <xs:element name="item" type="xs:string" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:int" use="required"/>
  </xs:complexType>
</xs:element>

В JSON Schema: $defs.Money — {"type": "number", "minimum": 0}; order — объект с обязательными total (ссылка на Money), item (массив строк) и @id (integer). Документ {"order": {"@id": 1, "total": 5, "item": ["a"]}} проходит проверку.

Вопросы и ответы

Можно ли получить схему без «@» и «#text»? Эти соглашения нужны, чтобы JSON однозначно соответствовал XML. Если API проектируется заново, переименуйте свойства в результате — схема станет описанием нового формата.

Что с xs:any? Объект допускает дополнительные свойства (нет additionalProperties: false).

Как вставить результат в OpenAPI? Скопируйте определения из $defs в components/schemas и замените ссылки #/$defs/ на #/components/schemas/.