Основы XML, JSON, YAML

XML, JSON и YAML — три формата структурированных данных, с которыми системный аналитик работает в спецификациях API, конфигурациях, логах и обмене сообщениями. Заметка даёт минимум для чтения, извлечения полей, преобразования между форматами и валидации — без ухода в проектирование контрактов или DevOps. Практика вызова API — в 07.02 Работа с API (практика); OpenAPI и AsyncAPI — в 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf).

1. Суть темы

Структурированные текстовые форматы (structured data formats) описывают иерархию объектов: заказ, клиент, позиции, атрибуты. На проекте один и тот же бизнес-объект может встретиться как XML в SOAP-конверте, как JSON в REST-ответе и как YAML в docker-compose.yml или OpenAPI-файле. Источник формата часто не «выбор архитектора», а выгрузка или legacy-документ — см. 02.02.03 Наблюдение и анализ документов.

Тело на проводе и описание контракта — разные вещи. REST и Kafka чаще передают JSON в HTTP/брокере; gRPC на проводе несёт бинарный Protobuf, но .proto и OpenAPI/JSON Schema описывают структуру для людей и инструментов. YAML в репозитории (openapi.yaml) — формат файла спецификации, а не payload клиента.

Граница темы:

Единая модель на примере заказа помогает сравнивать форматы. В XML атрибут currency на элементе <price>; в JSON и YAML это отдельное поле — при конвертации именно здесь чаще всего «ломается» модель.

2. Ключевые понятия

XML (eXtensible Markup Language)

XML — расширяемый язык разметки (W3C). Используется в SOAP, SAML, документообороте, legacy-интеграциях и там, где нужна строгая схема.

<?xml version="1.0" encoding="UTF-8"?>
<order id="1001" date="2025-03-15">
  <customer>
    <name>Иванов Иван</name>
    <email>ivanov@example.com</email>
  </customer>
  <items>
    <item productId="P001" quantity="2">
      <name>Клавиатура</name>
      <price currency="RUB">2500</price>
    </item>
  </items>
</order>

Well-formed XML — документ, который парсер принимает без ошибки синтаксиса: один корневой элемент, все теги закрыты, вложенность без пересечений, значения атрибутов в кавычках. Спецсимволы экранируются сущностями: <, >, &, ', ".

Пространства имён (namespaces) связывают префикс с URI-идентификатором (не обязательно открываемым в браузере). Без умения читать namespaces не разобрать SOAP-конверт:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ord="http://example.com/order">
  <soap:Body>
    <ord:GetOrderStatus>
      <ord:orderId>1001</ord:orderId>
    </ord:GetOrderStatus>
  </soap:Body>
</soap:Envelope>

XSD (XML Schema Definition) описывает допустимую структуру: элементы, атрибуты, типы, обязательность, перечисления. Аналитику достаточно читать XSD, чтобы понять контракт. Фрагмент для того же заказа:

<xs:element name="order">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="customer" type="CustomerType"/>
      <xs:element name="items">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="item" maxOccurs="unbounded" type="ItemType"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="id" type="xs:integer" use="required"/>
    <xs:attribute name="date" type="xs:date" use="required"/>
  </xs:complexType>
</xs:element>

Здесь видно: id и date — атрибуты корня (не дочерние элементы), item повторяется, типы заданы явно. В legacy встречается DTD (Document Type Definition) — более старый механизм; логика для вас та же: «схема задаёт допустимую форму документа». Шаблон SOAP — 10.01.05 Шаблон спецификации SOAP API.

XPath — язык выражений для навигации по XML. Нужен при разборе логов, проверке ответов интеграции и формулировке тест-кейсов «извлечь поле X».

В SOAP-путях с namespaces используйте namespace-aware XPath (префиксы или local-name()), иначе выражение не найдёт узел:

JSON (JavaScript Object Notation)

JSON — компактный формат обмена данными (RFC 8259). De facto стандарт тел REST API, логов и JSON-сообщений в очередях.

{
  "orderId": 1001,
  "date": "2025-03-15",
  "customer": {
    "name": "Иванов Иван",
    "email": "ivanov@example.com"
  },
  "items": [
    {
      "productId": "P001",
      "quantity": 2,
      "name": "Клавиатура",
      "price": 2500,
      "currency": "RUB"
    }
  ],
  "isPriority": false,
  "discountCode": null
}

Типы значений: объект {}, массив [], строка (в двойных кавычках), число, true/false, null. Комментарии стандартом не поддерживаются. Trailing comma после последнего элемента — синтаксическая ошибка.

JSON Schema — описание структуры JSON: типы, required, enum, форматы (date-time, email). В OpenAPI 3.x схемы тел запросов и ответов — JSON Schema; детали нотации — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf). Минимум для чтения контракта:

{
  "type": "object",
  "required": ["orderId", "date", "customer", "items"],
  "properties": {
    "orderId": { "type": "integer" },
    "date": { "type": "string", "format": "date" },
    "customer": {
      "type": "object",
      "required": ["name", "email"],
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["productId", "quantity", "price", "currency"],
        "properties": {
          "productId": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 },
          "price": { "type": "number" },
          "currency": { "type": "string", "enum": ["RUB", "USD", "EUR"] }
        }
      }
    }
  }
}

Сопоставьте с XML: currency здесь отдельное поле объекта, а не атрибут <price>.

JSON Pointer (RFC 6901) и JSON Reference — стандартные способы адресовать фрагмент документа, например #/components/schemas/Order. Это не аналог XML ID/IDREF и не замена JSONPath для «вытащить значение из ответа API» — это путь внутри одного JSON/YAML-документа. В OpenAPI $ref опирается именно на JSON Pointer.

JSONPath — de facto синтаксис для извлечения значений из JSON (аналог XPath). Полезен в тест-кейсах и при разборе логов. Диалекты различаются: Goessner (классический), Jayway (Java/Spring), Postman — фильтры, индексы и «deep scan» ($..field) могут вести себя по-разному. В AC указывайте инструмент проверки или эталонное выражение, которое воспроизводит QA.

NDJSON (newline-delimited JSON) — по одному JSON-объекту на строку; часто в стримах и выгрузках. Это не один JSON-массив: файл нельзя обернуть в [ ] и проверить одним JSONLint.

YAML (YAML Ain't Markup Language)

YAML ориентирован на читаемость человеком. Конфиги Ansible, Docker Compose, Kubernetes, GitLab CI — YAML; спецификации OpenAPI часто тоже пишут в YAML, хотя формат файла ≠ формат тела HTTP-запроса (Content-Type: application/json).

orderId: 1001
date: 2025-03-15
customer:
  name: Иванов Иван
  email: ivanov@example.com
items:
  - productId: P001
    quantity: 2
    name: Клавиатура
    price: 2500
    currency: RUB
isPriority: false
discountCode: null

Правила: вложенность через пробелы (не табуляция), списки через - , комментарии #.

Якоря и ссылки (&, *, <<:) — механизм шаблонов YAML, не поля доменной модели. В K8s и CI ими переиспользуют блоки:

defaults: &base
  replicas: 1
  image: registry.example/app:1.0
 
service-a:
  <<: *base
  name: orders

При чтении конфига достаточно понять: *base подставляет содержимое якоря &base.

YAML и типы: парсер может интерпретировать yes/no, незакавыченные даты и числа иначе, чем вы ожидаете. Для контрактных полей в спецификациях безопаснее явные строки в кавычках.

YAML и JSON Schema: валидация через JSON Schema применима, когда YAML представляет JSON-структуру — OpenAPI, Kubernetes-манифесты с CRD-схемой. Сырой docker-compose.yml или Ansible-playbook не валидируют «просто JSON Schema» без отдельной модели; там lint по синтаксису YAML и правила конкретного инструмента.

Кодировки, экранирование, даты и числа

Согласование типов полей — часть 03.03.02 Логическая и физическая модель данных и 03.03.03 Словарь данных (описание).

Content-Type: application/json и application/xml относятся к телу HTTP-сообщения. Файл openapi.yaml — YAML-спецификация контракта; клиент при этом шлёт JSON. Путаница «в спеке YAML — значит API на YAML» ломает примеры в Confluence.

Сравнительная таблица

3. Как применяется в работе аналитика

Чтение и примеры в спецификации

• Составляйте пары запрос/ответ в JSON или XML по 10.01.04 Шаблон спецификации REST API и 10.01.05 Шаблон спецификации SOAP API.
• Иллюстрируйте словарь данных фрагментами JSON/XML — 03.03.03 Словарь данных (описание).
• Для асинхронных сообщений описывайте JSON payload события (структура полей в теле сообщения) — 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ), 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ); обёртки и бинарные форматы — 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events).

Извлечение полей (XPath / JSONPath)

В AC и тест-кейсах фиксируйте путь к полю, инструмент и namespace-контекст для XML:

• «После POST /orders в теле ответа JSONPath $.orderId (Postman) — число > 0».
• «В SOAP-ответе XPath /soap:Envelope/soap:Body/ord:GetOrderStatusResponse/ord:orderId (namespace-aware; префиксы soap, ord как в WSDL) равен переданному id».

Плоский путь /Envelope/Body/... без namespaces — только если в спецификации явно оговорено «упрощённо, после strip NS» или в примере нет префиксов.

Онлайн-проверка выражений: JSONPath Online Evaluator, XPath — в DevTools браузера или IDE с плагином XML.

Преобразование форматов (parse → transform)

Когда аналитику нужна конвертация:

Конвертеры (convertjson.com) — для черновика; финальную модель сверяйте со схемой. Не загружайте в публичные lint/convert-сервисы примеры с prod PII — используйте обезличенные данные или корпоративные инструменты. Подробности миграции контрактов — 03.05.07 Управление версионированием API и жизненным циклом.

Валидация: рабочий цикл

Цикл перед merge спецификации или приёмкой интеграции — часть 02.04.01 Верификация и валидация (V&V):

flowchart LR
    A[Пример или файл] --> B[Well-formed / lint]
    B --> C[Validate against schema]
    C --> D[Сверка с AC / контрактом]
    D --> E[Фиксация в спецификации]

Критерий приёмки: «Тело ответа 200 на GET /orders/{id} валидируется по JSON Schema Order из OpenAPI» — проверяемо на стенде вместе с 07.02 Работа с API (практика).

YAML в конфигурациях и CI

Читайте фрагменты .gitlab-ci.yml, GitHub Actions, Helm values, чтобы понять этапы поставки — без превращения заметки в гайд по GitLab Actions. Контекст требований к пайплайну — 07.06 CICD и конвейеры — влияние на требования; YAML в репозитории — 07.05 Системы контроля версий (Git) для документации.

OpenAPI на YAML — только фрагмент

Спецификации контрактов, $ref, версии и AsyncAPI — в 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf). Здесь — минимум, чтобы узнать формат файла; шаг валидации OpenAPI YAML — в таблице цикла выше.

paths:
  /orders:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

$ref: '#/components/schemas/Order' — JSON Pointer внутри YAML-файла; тело HTTP при этом остаётся JSON.

4. Типовые ошибки и ограничения

Синтаксис и формат

• YAML: сбитый отступ на один пробел; таб вместо пробелов; key:value без пробела после :.
• JSON: trailing comma; одинарные кавычки; комментарии // (невалидны).
• XML: неэкранированный & в тексте; пересекающиеся теги; два корневых элемента.
• Путаница JSON и NDJSON.
• CSV выдан «как JSON» или смешан с иерархическим примером сообщения — CSV табличный, без вложенности; выгрузки из отчётов и ETL держите отдельно от XML/JSON payload.

Модель данных

• Дата как число в одном сервисе и строка в другом — явно фиксируйте в схеме и словаре данных.
• Атрибут XML «потерян» при конвертации в JSON без отдельного поля.
• $ref в OpenAPI: обязательность поля видна только в components/schemas, не в одном фрагменте paths.
• JSONPath из AC не воспроизводится в инструменте QA — не указан диалект или синтаксис.

Валидация и процесс

• Пример в Confluence не прогоняли через schema — на приёмке расхождение с production.
• «Well-formed» XML принят за «валидный по контракту» — нужна отдельная проверка XSD.
• OpenAPI YAML не открывали в Swagger Editor перед review.

Безопасность парсинга

При приёме данных из внешних систем учитывайте риски небезопасного разбора XML/YAML — требования к обработке фиксируйте в NFR. В спецификации и при review: не вставляйте prod PII и секреты в публичные валидаторы и конвертеры; для примеров — обезличенные данные. Детали угроз и мер — 08.07 Основы кибербезопасности для системного аналитика и 08.02 Нефункциональные требования (НФТ) — классификация и стандарты.

Производительность

Утверждение «XML всегда медленный» без контекста бесполезно для аналитика. Если объём сообщений критичен — отдельное NFR на размер payload и время обработки (08.02 Нефункциональные требования (НФТ) — классификация и стандарты).

Мини-чеклист перед передачей в разработку

1. Примеры well-formed (lint пройден).
2. Обязательные поля и типы согласованы со схемой (XSD / JSON Schema).
3. XPath или JSONPath для ключевых полей указаны в AC или таблице проверок (с инструментом для JSONPath; для SOAP — namespace-aware XPath или явная оговорка).
4. Кодировка UTF-8; кириллица в примерах отображается корректно.
5. Для YAML в репозитории — diff в Git, для OpenAPI — валидация в Swagger Editor.

Связи с другими разделами базы

• 07.02 Работа с API (практика) — вызов API и проверка тел запросов/ответов на стенде.
• 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf) — JSON Schema, OpenAPI на YAML, Protobuf как описание контракта.
• 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL) — JSON vs бинарный Protobuf на проводе.
• 07.02 Принципы работы HTTP, REST, SOAP — XML в SOAP, Content-Type, форматы тел.
• 02.02.03 Наблюдение и анализ документов — откуда в требованиях появляются XML/CSV-выгрузки и legacy-форматы.
• 10.01.04 Шаблон спецификации REST API — примеры JSON-тел REST.
• 10.01.05 Шаблон спецификации SOAP API — XML, namespaces, XSD в SOAP.
• 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ) — JSON-сообщения в очередях.
• 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ) — структура входящих сообщений.
• 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events) — JSON payload событий, Avro/Protobuf в брокерах.
• 03.03.03 Словарь данных (описание) — иллюстрация полей фрагментами JSON/XML.
• 03.03.02 Логическая и физическая модель данных — типы дат, чисел, строк в контракте.
• 02.04.01 Верификация и валидация (V&V) — проверка «ответ соответствует схеме».
• 07.06 CICD и конвейеры — влияние на требования — YAML в пайплайнах.
• 07.05 Системы контроля версий (Git) для документации — YAML-конфиги в репозитории.
• 08.02 Нефункциональные требования (НФТ) — классификация и стандарты — валидация, размер payload, требования к форматам.
• 08.07 Основы кибербезопасности для системного аналитика — безопасный парсинг XML/YAML.

Источники и дополнительные материалы

Спецификации и стандарты

• XML 1.0 (Fifth Edition), W3C: https://www.w3.org/TR/xml/
• XML Schema Part 0: Primer, W3C: https://www.w3.org/TR/xmlschema-0/
• XPath 3.1, W3C: https://www.w3.org/TR/xpath-31/
• JSON (RFC 8259): https://datatracker.ietf.org/doc/html/rfc8259
• JSON Pointer (RFC 6901): https://datatracker.ietf.org/doc/html/rfc6901
• JSON Schema: https://json-schema.org/
• YAML 1.2 Specification: https://yaml.org/spec/1.2.2/
• YAML — официальный сайт: https://yaml.org/

Статьи и справочники

• MDN: «Введение в XML»: https://developer.mozilla.org/ru/docs/Web/XML/XML_introduction
• MDN: «Работа с JSON»: https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON
• JSONPath (обзор синтаксиса, Stefan Goessner): https://goessner.net/articles/JsonPath/

Книги

• Эллиот Расти Гарольд, Скотт Минс. «XML. Справочник» — разбор XML и XPath.
• Дэвид Флэнаган. «JavaScript: полное руководство» — раздел по JSON (контекст типов и сериализации).

Инструменты