Конвертер JSON в TOML

Что такое TOML и зачем преобразовывать из JSON?

// Convert JSON to TOML in Node.js using the smol-toml library
import { stringify } from 'smol-toml';

const data = JSON.parse(`{
  "package": { "name": "my-app", "version": "1.0.0" },
  "dependencies": { "serde": { "version": "1.0" } }
}`);

// The top-level value must be an object; null values on objects are dropped.
const toml = stringify(data);

console.log(toml);
// [package]
// name = "my-app"
// version = "1.0.0"
//
// [dependencies.serde]
// version = "1.0"

Ключевые возможности

Примеры

{
  "package": {
    "name": "my-app",
    "version": "1.0.0",
    "edition": "2021"
  },
  "dependencies": {
    "serde": { "version": "1.0", "features": ["derive"] },
    "tokio": { "version": "1", "features": ["full"] }
  }
}

{
  "build-system": {
    "requires": ["hatchling"],
    "build-backend": "hatchling.build"
  },
  "project": {
    "name": "my-package",
    "version": "0.3.1",
    "requires-python": ">=3.10",
    "dependencies": ["requests>=2.31", "pydantic>=2.0"]
  }
}

{
  "title": "My Service",
  "debug": false,
  "port": 8080,
  "database": {
    "host": "localhost",
    "port": 5432,
    "pool_size": 10
  },
  "features": ["auth", "metrics", "tracing"]
}

{
  "servers": [
    { "name": "alpha", "ip": "10.0.0.1", "ports": [8001, 8002] },
    { "name": "beta", "ip": "10.0.0.2", "ports": [9001] }
  ]
}

{
  "build": {
    "command": "npm run build",
    "publish": "dist",
    "environment": { "NODE_VERSION": "20" }
  },
  "redirects": [
    { "from": "/old", "to": "/new", "status": 301, "force": true }
  ]
}

{
  "tool": {
    "ruff": { "line-length": 100, "target-version": "py310" },
    "black": { "line-length": 100 }
  }
}

Как использовать

1. 1

   Вставьте свой JSON

   Введите или вставьте свой JSON в поле ввода выше. Также можно нажать «Загрузить пример», чтобы попробовать исходник Cargo.toml, исходник pyproject.toml или объект настроек приложения.

2. 2

   Смотрите живой вывод TOML

   TOML появляется мгновенно в панели вывода. Если у вашего JSON массив верхнего уровня или значения null, инструмент точно объяснит, что делать, вместо того чтобы выдавать сломанный вывод.

3. 3

   Копируйте или скачивайте

   Нажмите «Копировать», чтобы поместить TOML в буфер обмена, или «Скачать», чтобы сохранить как файл .toml, готовый для Cargo, Poetry, Hugo, Netlify или любого инструмента, читающего TOML.

Частые подводные камни преобразования JSON в TOML

[1, 2, 3]

{ "items": [1, 2, 3] }

{ "name": "a", "nickname": null }

{ "name": "a", "nickname": "" }

{ "ports": [8001, null, 8003] }

{ "ports": [8001, 8003] }

{ 'name': 'a', 'active': true, }

{ "name": "a", "active": true }

{ "ratio": 1.0 }  →  ratio = 1

{ "ratio": 1.5 }  →  ratio = 1.5

{ "server": { "a": 1 }, "server": [1] }

{ "server": { "a": 1 }, "servers": [1] }

Частые сценарии использования

Генерация Cargo.toml

Превратите структурированный JSON — от инструмента-скаффолдера, API или скрипта — в валидный Rust Cargo.toml с автоматически создаваемыми вложенными таблицами [dependencies] и встроенными таблицами.

Генерация pyproject.toml

Преобразуйте метаданные проекта JSON в pyproject.toml формата PEP 621, включая точечные таблицы [tool.*], чтобы инструменты, выдающие JSON, могли создавать конфигурацию упаковки Python.

Редактируемая человеком конфигурация из JSON

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

Генерация конфигурации развёртывания

Создавайте netlify.toml, foundry.toml или похожие конфигурации платформ из JSON, превращая вложенные объекты и массивы объектов в таблицы и массивы таблиц, которые ожидают эти инструменты.

Миграция формата конфигурации

Перенесите конфигурацию из системы на основе JSON в систему на основе TOML, используя этот конвертер как мост, а предупреждения о null и верхнем уровне — чтобы поймать всё, что не отобразится.

Прототипирование структуры TOML

Набросайте конфигурацию как JSON — формат, который большинство разработчиков набирают свободно — затем преобразуйте в TOML, чтобы увидеть идиоматичную раскладку таблиц и массивов таблиц перед фиксацией в репозитории.

Технические детали

Разбор JSON по RFC 8259

Ввод JSON разбирается нативным JSON.parse() браузера, полностью совместимым с RFC 8259. Перед сериализацией инструмент проверяет, что значение верхнего уровня — объект, и сканирует значения null, чтобы предупредить об удалённых ключах объекта или отклонить null внутри массива с точным путём.

Вывод TOML 1.0.0 через smol-toml

TOML генерируется библиотекой smol-toml — сериализатором без зависимостей, полностью совместимым с TOML 1.0.0. Вложенные объекты становятся таблицами, глубоко вложенные объекты становятся точечными таблицами, а массивы объектов становятся массивами таблиц. Числа с плавающей точкой с нулевой дробной частью записываются как целые по правилам TOML, с предупреждением.

100% на стороне браузера — без загрузки, без сервера

Вся обработка происходит в движке JavaScript вашего браузера. Данные не передаются ни в какой момент. Ввод больше 200 КБ переключается с живого в ручной режим (явное нажатие «Конвертировать»), чтобы интерфейс оставался отзывчивым.

Лучшие практики

Оборачивайте массивы верхнего уровня под ключом

Если ваши данные естественно являются JSON-массивом, оберните их в объект с описательным ключом ({ "items": [...] }) перед преобразованием. Документы TOML должны быть таблицей в корне, и ключ даёт вашему массиву понятное имя в выводе.

Решите, что должны означать значения null

Перед преобразованием решите, должно ли поле null исчезнуть (отбросить ключ) или нести значение. TOML отбросит объектные null и отклонит массивные null, поэтому разрешение их в вашем JSON заранее даёт предсказуемый, полный вывод.

Используйте вложенные объекты для группировки

Группируйте связанные настройки во вложенные объекты в вашем JSON — они становятся чистыми [таблицами] и точечными таблицами в TOML, что гораздо читабельнее плоского списка ключей и соответствует тому, как организованы конфигурации Cargo и pyproject.

Сначала проверяйте свой JSON

Если ваш JSON написан вручную или получен из ненадёжного источника, проверьте его нашим Форматировщиком JSON, чтобы поймать замыкающие запятые и ошибки кавычек перед преобразованием в TOML.

Добавляйте комментарии после преобразования

В JSON нет комментариев, поэтому ни один не переносится. Поскольку TOML поддерживает комментарии с #, добавьте документацию в сгенерированный TOML вручную — одна из главных причин переносить редактируемую человеком конфигурацию в TOML.

Часто задаваемые вопросы