YAML → JSON: сохраняем строки, числа и null при конвертации

В YAML многие значения выглядят как обычный текст без кавычек. При разборе часть из них становится числами, boolean или null. Если получатель ожидает строковый код 007, неожиданное число 7 уже не равно исходному идентификатору. Конвертацию стоит проверять по типам и значениям, а не только по красивому результату.

Правила разрешения scalar зависят от схемы и реализации YAML. Спецификация YAML 1.2.2 описывает, в частности, разные схемы разрешения типов; нельзя переносить поведение одного парсера на все остальные. YAML 1.2.2, раздел 10.

Пять значений с явными намерениями

Синтетический YAML для конвертера Neraviko:

code: "007"
word: "true"
ready: true
count: 7
empty: null

Выберите pretty=false, trailing_newline=false. Результат текущей операции, воспроизведённый локально на установленном парсере:

{"code":"007","word":"true","ready":true,"count":7,"empty":null}

У code сохранились ведущие нули, потому что вход обозначает строку. word содержит четыре текстовых буквы, а ready — логическое значение. count остаётся числом, empty — null. В данном примере статус операции success, предупреждений нет.

Если значение используется как идентификатор, версия или обозначение, кавычки помогают явно передать строковый тип. Это не настройка конвертера «сделать всё текстом»: в Neraviko такого переключателя не заявлено. Тип нужно выразить в исходном документе и согласовать с потребителем.

Проверка результата по контракту

Следующий Python-код проверяет именно показанный JSON-результат, а не реализует YAML-парсер:

import json

source = '{"code":"007","word":"true","ready":true,"count":7,"empty":null}'
data = json.loads(source)
assert data["code"] == "007" and isinstance(data["code"], str)
assert data["word"] == "true" and isinstance(data["word"], str)
assert data["ready"] is True
assert type(data["count"]) is int and data["count"] == 7
assert data["empty"] is None
print("scalar types preserved")

Проверенный вывод — scalar types preserved. В рабочем процессе такую проверку полезно выполнить после преобразования тестовой записи. Затем проверьте полный импорт в приложении: оно может снова переинтерпретировать строковый код как число, даже если конвертер сохранил его.

Даты и дроби требуют отдельного просмотра

YAML поддерживает значения, для которых нет непосредственного отдельного типа в JSON. В Neraviko распознанные timestamps переводятся в строки ISO 8601 с предупреждением YAML_TIMESTAMP_STRINGIFIED. Просмотрите часовой пояс и точность, а не считайте преобразованную строку автоматически подходящей для своего API.

Если дата должна быть просто меткой вида 2026-10-05, запишите её строкой в кавычках и проверьте результат. Это отличается от момента времени с часовым поясом. Не добавляйте время полуночи и Z по собственному предположению.

Числа с плавающей точкой сопровождаются YAML_FLOAT_PRECISION_REVIEW: операция сохраняет разобранное числовое значение, а не обещает исходное написание всех десятичных цифр. Некоторые большие числоподобные строки также сопровождаются предупреждением. Поэтому needs_review не следует игнорировать только потому, что поле text заполнено.

Граница поддерживаемого YAML

Neraviko обрабатывает один UTF-8 документ. Его путь YAML → JSON отклоняет anchors, aliases, теги, повторяющиеся mapping keys и несколько документов. Определённый YAML, который принимает другая программа, может быть намеренно неподдерживаем здесь. Не расширяйте возможности инструмента в уме по одному успешному примеру.

Для источника с anchors сначала выясните его контракт и подходящий парсер. Нельзя просто удалить &name или *name: это изменит связи и значения. То же относится к специальным тегам: их смысл может задаваться приложением, а универсальный конвертер его не знает.

Обратный путь JSON → YAML разбирает значения. Он не обязан восстановить прежние комментарии, стиль кавычек, запись чисел или расположение строк. Round trip оценивают по согласованной модели данных, а исходный файл сохраняют отдельно для сопровождения.

Что проверить перед передачей

Составьте маленький набор пограничных значений из своего контракта: ведущие нули, строковое true, boolean, число, пустая строка и null. Добавьте дату, если она участвует в обмене. Для каждого поля запишите ожидаемый тип результата.

После конвертации проверьте предупреждения и отдельно типы ключевых полей. Если обнаружили изменение, сначала уточните исходный тип, затем правьте документ или контракт. Заменять все значения строками без согласования так же нежелательно, как автоматически назначать числа текстовым кодам.

Обработка Neraviko серверная. Для проверок нужны искусственные записи, а не конфигурации с рабочими секретами. Лимит запроса конвертации — 262 144 байта с общими ограничениями API; YAML nesting ограничен 64 уровнями. JSON validator поможет проверить полученный JSON, но не подтвердит исходные намерения типов за вас.