Статья
Конвертация между CSV, XML, JSON и YAML: практическое руководство
CSV, JSON, XML и YAML, четыре формата, с которыми разработчики чаще всего сталкиваются в конвейерах обработки данных, файлах конфигурации и API. Конвертация между ними проста, когда модели данных совпадают, и неожиданно разрушительна для данных, когда не совпадают. В этом руководстве рассматривается, что каждый формат может и не может представить, где информация исчезает при конвертации и какие ловушки кодировки приводят к скрытому повреждению данных. Инструмент data-converter на этом сайте работает с тремя из четырёх форматов (CSV, JSON и YAML) полностью в браузере; разделы про XML здесь служат справочным материалом на случай, если вы переносите данные вручную или с помощью отдельного инструмента.
Четыре формата и их модели данных
CSV организует данные в виде плоской таблицы строк и столбцов. Первая строка обычно содержит названия столбцов, каждая последующая строка, одна запись. Нет вложенности, нет информации о типах и нет стандарта ни для чего, кроме простого текста в ячейках. Каждое значение является строкой, если только принимающее приложение не устанавливает тип. JSON представляет данные в виде дерева объектов (отображений ключ-значение) и массивов. Значения могут быть строками, числами, булевыми значениями, null, вложенными объектами или массивами любой глубины. Это позволяет одному документу JSON представлять запись клиента со встроенными объектами адреса, массивами позиций и типизированными числовыми итогами. XML представляет данные в виде дерева элементов. Каждый элемент может иметь именованные атрибуты и содержать дочерние элементы или текстовое содержимое. Встроенных числовых или булевых типов нет: всё является текстом. Схемы, такие как XSD, могут применять типы при проверке, но формат передачи данных всегда остаётся символьными данными. YAML использует отступы для выражения той же модели объектов и массивов, что и JSON, но с более чистым, удобочитаемым синтаксисом. YAML является надмножеством JSON: любой допустимый документ JSON является также допустимым YAML. Он добавляет многострочные строки, комментарии и ссылки на якоря для повторяющихся блоков. YAML распространён в файлах конфигурации, JSON, в ответах API.
Конвертация с потерями: выравнивание и неоднозначность XML
Наиболее распространённая конвертация с потерями, выравнивание вложенного JSON или XML в CSV. Объект JSON с вложенным полем адреса не может аккуратно отобразиться в строку CSV. Типичный обходной путь, имена столбцов с точечной нотацией: customer.address.city превращается в отдельный столбец. Это работает для одного уровня вложенности, но полностью ломается, когда появляется массив. Клиент с тремя номерами телефонов требует либо трёх отдельных столбцов (с жёстко закодированным максимальным количеством), либо разделения на второй файл CSV, либо кодирования массива в виде строки с разделителями в одной ячейке. Ни один из этих вариантов не позволяет восстановить исходный JSON без дополнительных метаданных. XML вносит отдельную неоднозначность: выбор между атрибутом и дочерним элементом. Значение Paris может храниться как атрибут (<city name="Paris">) или как дочерний элемент (<city><name>Paris</name></city>). Когда конвертер читает XML и создаёт JSON, он должен решить, как отобразить атрибуты. Распространённые соглашения включают добавление префикса @ к ключам атрибутов или размещение их под ключом "_attributes". Выбор не стандартизирован, поэтому два конвертера, читающие один и тот же XML, могут создавать структурно разные JSON. Если вы планируете преобразовывать данные туда и обратно между XML и JSON, зафиксируйте соглашение заранее.
Ловушки CSV: разделители, кавычки и кодировка
У CSV нет единого формального стандарта, только RFC 4180 в качестве широко используемого справочника. Наиболее распространённый разделитель, запятая, но в практике встречаются точки с запятой (распространены в европейских локалях, где запятые служат десятичными разделителями), табуляция (TSV) и вертикальные черты. Файл с расширением .csv может использовать любой из них, не указывая какой именно. Когда значение поля содержит сам разделитель, RFC 4180 требует заключить поле в двойные кавычки: "San Francisco, CA". Двойная кавычка внутри поля в кавычках должна быть экранирована удвоением: "He said ""hello""". Поле, содержащее буквальный перенос строки, также должно быть взято в кавычки. Синтаксические анализаторы, пропускающие этот шаг, создают трудноотслеживаемые ошибки в количестве строк. Кодировка, отдельная ловушка. CSV-файлы из инструментов Windows часто содержат BOM UTF-8 (метку порядка байтов: три байта EF BB BF в начале файла). BOM помогает Excel идентифицировать кодировку, но многие синтаксические анализаторы языков программирования воспринимают BOM как часть первого имени столбца, создавая столбец с именем "id" вместо "id". Это ломает любой нижестоящий код, который ищет столбцы по имени. При программном чтении CSV-файла удалите BOM перед разбором или используйте библиотеку, которая обрабатывает его явно.
Выбор формата: конфигурация, обмен данными и таблицы
Выбор формата обычно определяется контекстом, а не предпочтениями. JSON, стандарт по умолчанию для REST API и обмена данными между браузером и сервером. Он компактен, нативно разбирается на каждом языке программирования и содержит информацию о типах для чисел и булевых значений. Его слабость, отсутствие комментариев, что делает его непригодным для файлов, которые разработчики читают и редактируют вручную. YAML предпочтителен для файлов конфигурации (манифесты Kubernetes, определения конвейеров CI, плейбуки Ansible), поскольку позволяет добавлять встроенные комментарии и читается легче, чем JSON с многими уровнями отступов. Основной риск: ошибки в отступах незаметны, смещённый ключ перемещается в другую область без какой-либо ошибки разбора. XML остаётся стандартом в старых корпоративных системах, веб-сервисах SOAP, форматах документов (DOCX, SVG, RSS) и контекстах, требующих проверки схемы или разрешения пространств имён. Он многословен, но инструментарий XPath и XSLT зрелый. CSV, правильный выбор, когда данные действительно плоские, а потребитель, это приложение для работы с таблицами или аналитик данных. Он не подходит для конфигурации или обмена через API, потому что не имеет системы типов и вложенности.
Локальная работа с data-converter
Инструмент data-converter на этом сайте разбирает и конвертирует между CSV, JSON и YAML полностью внутри браузера; XML он не читает и не записывает. Данные не передаются на сервер ни в какой момент. Конвертация выполняется в локальной среде выполнения JavaScript, а результат доступен для скачивания или копирования без передачи чего-либо за пределы вашего устройства. Это важно для данных, которые вы не вправе передавать: ответы API, содержащие персональную информацию, файлы конфигурации с внутренними именами хостов или CSV-экспорты из внутренних баз данных. Вставка таких данных в веб-конвертер, работающий на сервере, означает, что содержимое отправляется по сети и обрабатывается на оборудовании, которое вы не контролируете. С data-converter вкладка браузера является средой обработки. Инструмент применяет кавычки RFC 4180 при чтении и записи CSV и ожидает плоский массив объектов при конвертации JSON или YAML в CSV: вложенный объект или массив под ключом не получает автоматического выравнивания с точечной нотацией, поэтому такие поля нужно разворачивать самостоятельно перед конвертацией, если они нужны как отдельные столбцы. Если требуется перенести данные в XML или из XML, сначала преобразуйте их в JSON или YAML отдельным инструментом для работы с XML, а затем обработайте результат здесь.
Инструменты из этой статьи
Частые вопросы
Можно ли преобразовать JSON через CSV и получить исходный файл обратно?
Только если JSON представляет собой плоский массив объектов без вложенных полей и без массивов в качестве значений. Как только появляется вложенный объект или значение-массив, представление CSV требует структурного решения (столбцы с точечной нотацией, несколько строк или закодированные строки), которое нельзя автоматически обратить. Если ваши данные имеют вложенность, JSON, XML или YAML успешно преобразуются туда и обратно, а CSV нет.
Почему мой CSV выглядит неправильно в Excel после экспорта из европейского приложения?
Европейские локали часто используют точки с запятой в качестве разделителя CSV, потому что запятые зарезервированы для десятичной нотации. Excel в европейской локали ожидает точки с запятой. Если файл использует запятые, Excel воспринимает всю строку как один столбец. Решение: изменить разделитель в настройках экспорта или использовать мастер импорта данных Excel, который позволяет указать разделитель вручную. Проблема с BOM UTF-8 отдельная: без BOM Excel может также неправильно отображать символы с диакритическими знаками.
В чём разница между YAML и JSON на практике?
Оба представляют одну и ту же базовую модель данных: объекты, массивы, строки, числа, булевы значения и null. YAML добавляет комментарии (строки, начинающиеся с #), многострочные строковые литералы и ссылки на якоря для повторяющихся блоков. JSON является строгим подмножеством допустимого YAML, но синтаксические анализаторы JSON не читают YAML. Практическое правило: используйте JSON для полезных нагрузок API и хранения данных, YAML для файлов конфигурации, которые люди редактируют и которым нужны встроенные комментарии.