PDFFlare
7 min read

How to Convert JSON to TOML (and TOML to JSON) Online for Free

Need a JSON to TOML converter for hand-editable config files? Here's the practical workflow. TOML is the format of choice for Rust's Cargo, Python's pyproject.toml, and a growing list of CLIs. JSON is the lingua franca of APIs and serialized state. Converting between the two shows up surprisingly often: programmatic config generation, migrating off old TOML config, or just exporting state for human review.

In this guide you'll learn how to convert JSON to TOML (and back) with PDFFlare's JSON to TOML tool — how TOML tables map to JSON objects, how arrays of tables differ from inline arrays, and where the two formats diverge.

Why TOML?

TOML (Tom's Obvious, Minimal Language) was designed for config files: human-friendly, unambiguous, and a clear superset of INI for nesting. Cargo.toml and pyproject.toml are the biggest deployments, but Hugo, Black, ruff, and many other tools read TOML too.

How TOML Maps to JSON

  • TOML tables ([section]) become JSON objects.
  • TOML arrays of tables ([[section]]) become JSON arrays of objects.
  • TOML scalars (string, integer, float, boolean, datetime) map to JSON scalars; datetimes become ISO 8601 strings.

How to Convert JSON to TOML (Step by Step)

  1. Open PDFFlare's JSON to TOML tool.
  2. Paste your JSON or TOML. The tool detects the input format from context.
  3. Click Convert. The output is the other format, pretty-printed and ready to paste into Cargo.toml, pyproject.toml, or similar config files.
  4. Copy and ship.

Real Use Cases

Programmatic Cargo.toml generation

A workspace generator that maintains Cargo.toml across crates. Compute the desired state in JSON, convert to TOML, write the file.

pyproject.toml migration

Python projects moving from setup.py to pyproject.toml — generate the new TOML from a JSON intermediate that's easier for the migration script to construct.

Reviewing TOML in JSON-aware tools

Convert TOML → JSON and feed into JSON Diff or JSONPath.

Common Mistakes (and How to Avoid Them)

  • Forgetting that TOML datetimes are typed. JSON has no native datetime — they're stringified on conversion. To re-deserialize as a TOML datetime, format the string in RFC 3339.
  • Mixing inline arrays with arrays of tables. TOML's [[section]]arrays of tables are different from inline arrays. The converter picks based on element shape; refine manually if the result doesn't match.
  • Trying to express null. TOML has no null — absent keys are simply absent. JSON null is dropped in the JSON → TOML direction.

Privacy: Your Data Stays Local

Conversion runs in your browser. Safe for internal config files.

Related Workflows in the JSON Suite

Adjacent tools you might find useful while working on the same JSON document: the JSON to YAML and JSON Formatter both pair well with the conversion above. The first handles a different output format that consumers of your data may prefer; the second covers the validation side of the same workflow.

Related Tools

When TOML Is the Right Configuration Format

The configuration format landscape has evolved significantly over the past decade. JSON, YAML, TOML, and INI all compete for the role of “the configuration format you use,” and each has earned a niche. TOML's niche is hand-edited configuration where comments matter, the structure is shallow to moderate in depth, and the file will be read by humans more often than by programs. Understanding when those conditions apply is the key to using TOML well.

The Rust ecosystem standardized on TOML for Cargo.toml, and the Python ecosystem has been steadily adopting it for pyproject.toml. Both choices reflect the same calculation: package metadata is hand-edited by developers, comments add genuine value (explaining why a particular dependency version was pinned, for instance), and the structure is shallow enough that TOML's sectioned syntax is more readable than the alternatives. For tools in the same space — build tools, package managers, CLI utilities — TOML is a strong default.

Application configuration is the other natural fit. A server config with a few sections (database, logging, server) and ten or twenty settings reads more naturally in TOML than in JSON. The section headers act as inline documentation about what each block configures, and comments let operators explain non-default choices. When you ship a tool that operators will configure, TOML often produces a friendlier first impression than JSON.

Where TOML breaks down is deep nesting. Once your config has more than two or three levels of nested structure, TOML's syntax becomes harder to read than JSON or YAML. The dotted-key syntax for deep nesting works but stops being graceful past a certain depth. If your configuration genuinely needs deep nesting, YAML or JSON is probably a better fit. TOML earns its place when the structure is shallow enough that the section-based syntax is a readability win, not a constraint to fight against.

Production Patterns for JSON to TOML

TOML is human-friendly config; a few production patterns:

Use Tables for Logical Grouping

TOML's killer feature is the [section] header. Group related config (database, server, logging) under named sections so users can scan the file. The generator preserves nesting; if your JSON is flat, refactor to nested objects before converting.

Comments for Documentation

Add comments above each section explaining what it controls. TOML supports # commentsyntax. JSON doesn't, so this is one of the big upgrades when you switch from JSON to TOML for hand-edited config.

Arrays of Tables for Repeated Items

A list of similar objects (e.g., multiple database connections) becomes [[connections]] sections in TOML — cleaner than nested arrays. The generator handles this transformation automatically when it sees { array: [{...}, {...}] }.

When to Use a Different Format

TOML excels at config but isn't universal:

  • For DevOps configs, YAML is the convention. Use JSON to YAML.
  • For programmatic use, just use JSON — no conversion needed.
  • For wire format efficiency, use JSON to Protobuf.

Common Mistakes to Avoid

  1. Mixing inline tables and section headers. TOML allows both, but consistency matters for readability. Pick one style for similar items.
  2. Forgetting datetime parsing.TOML has built-in datetime types; JSON doesn't. The generator converts ISO-8601 strings to TOML datetimes — verify the output if dates matter.
  3. Putting empty arrays vs missing keys. In TOML, an empty array [] is different from a missing key. Decide which semantic you want and stay consistent.
  4. Trying to express deeply nested structures. TOML gets awkward past 3 levels. If your data is deeply nested, JSON or YAML is the better format.
  5. Editing TOML by hand without a parser. Whitespace, quotes, and brackets matter. Use a TOML-aware editor (most IDEs have plugins) — saves syntax errors.

Real-World Use Cases

  • Rust's Cargo.toml. The canonical TOML use case — package metadata, dependencies, build config.
  • Python's pyproject.toml. Modern Python build tooling adopted TOML for project metadata.
  • Application config files. Self-hosted tools (Hugo, Zola) use TOML for site config.
  • Per-environment overrides. Ship a base config; allow operators to drop a small TOML override per environment.

Polishing the Generator's Output

TOML is at its best when the configuration it represents is meant to be read and edited by humans rather than parsed by a machine. Whatever your specific use case, treat the generated output as a draft that deserves a careful read-through. Generators are excellent at producing the mechanical structure of an artifact and not at the editorial decisions that make the difference between something a colleague will tolerate and something a colleague will appreciate. Read every section of the output the way you would read a piece of writing you were proofreading for a friend. Look for inconsistent naming, missed opportunities to consolidate similar items, and places where the structure is mechanically correct but conceptually awkward. The five minutes spent on this review are the difference between an artifact that pays back over months and one that needs a second pass before it can be used. The generator handles the heavy lifting; you handle the polish that turns a draft into a deliverable. This division of labor is what makes generated code worthwhile in the first place. Without that final pass of human editorial judgment, the generator's output is merely fast rather than valuable, and the value matters more than the speed in nearly every real production setting.

The same logic applies to documentation, comments, and inline context that your generator output rarely supplies. A generated artifact has structure but no narrative; the narrative is what makes the thing useful to the next person who reads it. Add the few sentences of context that explain why a particular choice was made, what the surrounding system expects, and what the next person should look out for. These small editorial gestures cost almost nothing in the moment and pay back many times over when someone is trying to understand what you produced months later. Treat generation as the first ten percent of the work and these editorial passes as the remaining ninety percent that turns mechanical output into something a colleague will reach for again and again. Build the habit early and the gap between your generated artifacts and hand-written ones gets very small over time, which is the real prize.

Wrapping Up

For programmatic TOML work, PDFFlare's JSON to TOML tool gives you a bidirectional bridge with no signup. Ideal for one-off migrations, programmatic generation, and review workflows.

Back to all posts