JSON to TOML Tutorial: Convert JSON Objects to TOML Tables

Q: What JSON structures cannot be converted to TOML?

Several JSON structures cannot be represented in TOML. First, JSON null has no TOML equivalent — TOML does not have a null type. Second, a JSON root value that is an array cannot be represented in TOML because the TOML root must always be a table (object). Third, mixed-type arrays — arrays where elements are different types such as [1, "two", true] — are not allowed in TOML, which requires all array elements to be the same type. Fourth, arrays that mix objects and primitives have no clean TOML representation. Before converting, remove null values, ensure the root is an object, and verify arrays contain homogeneous types.

Q: How does TOML represent JSON arrays of objects?

JSON arrays of objects map to TOML array tables, which use double bracket syntax [[section-name]]. Each [[section-name]] header creates a new object in the array. For example, a JSON value {"plugins": [{"name": "auth"}, {"name": "billing"}]} becomes two [[plugins]] blocks in TOML, each with their own key-value pairs. This is a powerful feature that makes repeated config structures like server instances, plugin lists, and route definitions readable. For small inline arrays of simple objects, TOML also supports inline tables on a single line: items = [{name = "auth"}, {name = "billing"}].

Q: What are TOML tables vs inline tables?

A TOML table uses a section header [table-name] on its own line, followed by key-value pairs below it. This is the standard way to represent a nested object in TOML and is the format most people associate with TOML. An inline table puts the entire object on a single line using curly braces: server = {host = "localhost", port = 8080}. Inline tables are useful for small objects that fit comfortably on one line and when the object is a value inside an array. Inline tables cannot be extended after their closing brace — all keys must be defined in that one line. For most configuration sections, regular tables are preferred for readability.

Q: Can null JSON values be represented in TOML?

No. TOML has no null type. This is the most important limitation when converting JSON to TOML. If your JSON contains null values, you must decide how to handle them before conversion. Options include: removing the key entirely (the most common choice, since a missing key and null often have the same meaning in config), replacing null with an empty string (""), using a sentinel value like 0 or -1 for numeric fields, or using a TOML-specific convention your application understands. If null values are semantically important in your data — for example, a database schema that distinguishes null from missing — TOML is the wrong output format.

Q: How do I convert JSON to TOML in Python?

Python does not have a built-in TOML writer, but the tomli-w package (write-only) works well: pip install tomli-w. Then: import json, tomli_w; data = json.loads(json_string); print(tomli_w.dumps(data)). Remove any null values before passing to tomli_w since TOML has no null type. For reading existing TOML files, use tomllib (built-in since Python 3.11) or tomli (pip install tomli for Python 3.10 and earlier). The rtoml package is another option that uses a Rust-based TOML implementation under the hood for better spec compliance.

Q: What is the TOML equivalent of a JSON object?

A JSON object maps to a TOML table. A top-level JSON object becomes the root TOML document — its keys are top-level key-value pairs. A nested JSON object at key "server" becomes a TOML table declared with [server]. Further nesting becomes dotted table headers like [server.database] or dotted key syntax like server.database.host = "localhost". For an object that is a value inside an array, it becomes an element of a TOML array table using [[array-name]] syntax. For small objects used as values inline, TOML inline table syntax {key = "value"} can be used on a single line.

Last updated: May 12, 2026

Converting JSON to TOML follows 4 mapping rules: flat key-value pairs stay as-is, nested objects become [table] sections, arrays of objects become [[array-of-tables]] blocks, and primitive arrays stay inline. There are 3 hard conversion blockers: JSON null has no TOML equivalent and must be dropped or replaced, mixed-type arrays are invalid in TOML (all elements must share 1 type), and numeric JSON keys like "1" must be quoted or renamed. In Python, tomli-w or tomlkit handles conversion in 3 lines. This guide covers the full 8-type mapping table, conversion code in Python and JavaScript, inline table vs section syntax, and the 4 edge cases that silently break TOML output.

Convert a flat JSON object to TOML

{
  "name": "jsonic",
  "version": "1.0.0",
  "private": true,
  "retries": 3
}

name = "jsonic"
version = "1.0.0"
private = true
retries = 3

Convert nested objects to TOML tables

Nested JSON objects usually become TOML tables.

{
  "server": {
    "host": "localhost",
    "port": 8080
  },
  "database": {
    "poolSize": 10
  }
}

[server]
host = "localhost"
port = 8080

[database]
poolSize = 10

Convert arrays of objects to array tables

JSON arrays that contain objects map naturally to TOML array tables.

{
  "plugins": [
    { "name": "auth", "enabled": true },
    { "name": "billing", "enabled": false }
  ]
}

[[plugins]]
name = "auth"
enabled = true

[[plugins]]
name = "billing"
enabled = false

Handle JSON null before converting

TOML does not support null. Replace null fields with a real default, remove them, or choose a sentinel string that your app understands.

// JSON input that needs cleanup
{
  "theme": null,
  "enabled": true
}

// TOML-safe version
{
  "enabled": true
}

When JSON to TOML conversion works best

The root JSON value is an object, not an array.
Nested objects represent configuration sections.
Arrays contain primitives or similarly shaped objects.
The data does not need null values.
The output will be edited by humans as config.

Common JSON to TOML mistakes

Trying to convert arbitrary API payloads instead of config-like objects.
Leaving null values in the input.
Using mixed-type arrays that are hard for config consumers to interpret.
Expecting TOML to preserve JSON object key order as business logic.

Convert JSON to TOML online

Use Jsonic's JSON to TOML converter to transform config-like JSON into TOML tables and array tables in your browser.

Open JSON to TOML

Frequently asked questions

What JSON structures cannot be converted to TOML?

JSON null (no TOML equivalent), a root JSON array (TOML root must be a table), mixed-type arrays (TOML requires homogeneous array elements), and arrays mixing objects and primitives. Remove null values and ensure the root is an object before converting.

How does TOML represent JSON arrays of objects?

Arrays of objects become TOML array tables using double brackets: [[plugins]]. Each [[plugins]] header adds a new object to the array. For small inline arrays, TOML also supports inline table syntax: items = [{name = "auth"}, {name = "billing"}].

What are TOML tables vs inline tables?

A regular table uses a [section-name] header on its own line with key-value pairs below. An inline table puts the whole object on one line with curly braces: server = {host = "localhost", port = 8080}. Inline tables cannot be extended after their closing brace.

Can null JSON values be represented in TOML?

No. Remove the key entirely, replace with an empty string, or use a sentinel value. If null vs missing is semantically important in your data, TOML is the wrong output format — use JSON or a database instead.

How do I convert JSON to TOML in Python?

Use tomli-w (pip install tomli-w): import json, tomli_w; data = json.loads(json_string); print(tomli_w.dumps(data)). Remove null values first. For reading TOML, use tomllib (Python 3.11+) or tomli (older Python).

What is the TOML equivalent of a JSON object?

A JSON object becomes a TOML table. Top-level keys are bare key-value pairs. Nested objects become [section] headers. Further nesting uses dotted headers like [server.database]. Objects in arrays use [[array-name]] syntax.