--- url: https://findutils.com/guides/json-to-toml title: "JSON to TOML: Convert Tables, Arrays and Null Values" description: "Convert JSON to TOML with clear rules for nulls, nested tables and arrays. Check what changes when you convert TOML dates and comments back into JSON output." category: developer content_type: guide guide_type: subtopic cluster: configuration locale: en read_time: 7 status: published author: "olgunozoktas" published_at: 2026-09-08T07:14:00Z updated_at: 2026-09-08T07:14:00Z excerpt: "TOML cannot represent JSON null. Learn how the converter handles that difference, nested tables, arrays and date values before you use the output." tag_ids: ["toml", "json", "configuration", "developer-tools"] tags: ["TOML", "JSON", "Configuration", "Developer Tools"] primary_keyword: "json to toml" secondary_keywords: ["toml to json", "json toml null", "toml arrays of tables", "convert json to toml", "toml date json string"] tool_tag: "json-toml-converter" related_tool: "json-toml-converter" related_tools: ["json-toml-converter", "json-formatter", "properties-json-converter"] og_image: "/images/content/guides/json-to-toml-null-handling.webp" image_alt: "Nested paper compartments become separate rows beside a small empty compartment with an amber edge." --- Convert JSON to TOML from an object, then review every null value before you use the output. FindUtils [JSON TOML Converter](/developers/json-toml-converter/) writes nested objects as tables and reports the null values that it removes or replaces. The tool supports conversion in both directions. This guide explains the available settings, a repeatable example, and information that a conversion cannot preserve. ## Why does JSON to TOML need a null rule? TOML 1.0 supports strings, numbers, booleans, date and time values, arrays, and tables. It has no null type. A converter must therefore reject a JSON null or apply a replacement rule. See the [TOML 1.0 specification](https://toml.io/en/v1.0.0). FindUtils offers two rules: **Drop** removes the null value; **Empty string** replaces it with `""`. Neither rule preserves null as null. - **Optional settings:** Removing a key can activate a destination default. - **Text fields:** An empty string can mean an intentionally blank value. - **Arrays:** Removing an entry changes the array length and later indexes. These differences matter even when the resulting TOML is valid. Choose the rule from the receiving application's requirements. ## How to convert JSON to TOML Use a small object with one null value first. Check the complete result before you convert a larger document. ### Step 1: Select the conversion direction Open the [JSON TOML Converter](/developers/json-toml-converter/). Select **JSON to TOML**. Paste this invented configuration example. The root is an object, as this converter requires. ```json { "app": { "name": "Field Notes", "enabled": true, "ports": [8080, 8081], "description": null }, "targets": [ {"name": "preview", "enabled": true}, {"name": "release", "enabled": false} ] } ``` ### Step 2: Select a null policy Leave **Nulls** set to **Drop** for the first comparison. The output omits `app.description`. The **Notes** area names that path. Confirm that an absent description is acceptable. ### Step 3: Check the tables and arrays The `app` object becomes a table. Its numeric array stays inline. Each object inside `targets` becomes a separate array-of-tables entry. The output has this structure: ```toml [app] name = "Field Notes" enabled = true ports = [ 8080, 8081 ] [[targets]] name = "preview" enabled = true [[targets]] name = "release" enabled = false ``` ### Step 4: Compare the empty-string option Select **Empty string**. The `app` table now includes `description = ""`. The notes still identify `app.description`. Keep this setting only if the destination expects an empty string. ### Step 5: Export the reviewed result Copy the TOML or download `converted.toml`. Select **TOML to JSON** if you want to inspect the converted values as JSON. The current output moves into the input when you switch direction. ## Examples that need a separate decision Nulls, dates, and package metadata need more than a syntax check. The following examples identify what the converter can produce and what you must decide. ### A null inside an array For `{"stages":["draft",null,"approved"]}`, **Drop** produces an array with two entries. `approved` moves from index 2 to index 1. **Empty string** keeps three entries but changes the middle value to a string. The notes identify `stages[1]` in either case. Do not accept the shorter array if another setting refers to an entry by position. Change the source representation if neither option matches the destination's requirements. ### A date that changes type A JSON date string stays a quoted TOML string. The converter does not decide that a date-shaped string should become a TOML date. ```json {"release_date":"2026-09-08"} ``` ```toml release_date = "2026-09-08" ``` An unquoted TOML local date follows another path: ```toml release_date = 2026-09-08 ``` The JSON result contains `"release_date": "2026-09-08"`. JSON has no native date type, so that output cannot record whether the source used a TOML date or a string. Converting that JSON back produces a quoted TOML string. A successful conversion in both directions therefore does not prove that every type survived. ### A generated project file The converter can serialize an object that already has the required tables for a destination file. It does not translate one application's settings into another application's schema. For example, a JSON property named `dependencies` does not tell the converter how a particular package tool expects versions or optional features. Check those requirements separately. Valid TOML alone does not establish that a project file is valid for its consumer. ## What survives the conversion? Use this table as a review plan. It compares representations rather than claiming that the formats are interchangeable. | Source value or feature | Converter result | Required check | |---|---|---| | JSON object | TOML table structure | Table names match the destination | | JSON array of objects | TOML array of tables | Entry order and count remain correct | | JSON scalar array | TOML inline array | Values and their types match | | JSON null | Removed value or empty string | The replacement has the intended meaning | | JSON date string | Quoted TOML string | The consumer accepts a string | | TOML date or time | JSON string representation | Native date or time type information is lost | | TOML comment | No JSON comment | Keep explanations in the original document | **Sort keys** sorts object keys at each level for JSON-to-TOML output. It does not sort array entries. Sorting can make files easier to compare, but it cannot correct an incorrect value. ## Common mistakes and corrections Check the source structure before you investigate a parser error. Some valid JSON values are outside this converter's accepted input shape. ### Mistake 1: Starting with a root array The JSON root must be an object. A bare array produces a root error. Place it under a meaningful property only if the receiving application expects that property. ### Mistake 2: Treating removed nulls as harmless Read the notes before you copy the output. Inspect each named path. Removal can affect defaults, required fields, or array positions. ### Mistake 3: Expecting comments to return TOML comments do not enter the JSON result. A later conversion cannot reconstruct them. Keep the original file as the record of human explanations. ### Mistake 4: Treating dates as ordinary text in both directions Check whether the source date has quotes. A date-shaped string and a native TOML date can produce the same JSON string. Record the original type when it matters to the destination. ### Mistake 5: Ignoring number precision JSON parsing in this browser tool uses JavaScript numbers. Very large integer values can lose precision before TOML output. Keep exact identifiers as strings. The [JSON standard's number guidance](https://www.rfc-editor.org/rfc/rfc8259.html#section-6) explains interoperability limits. ## Tools used in this guide FindUtils provides separate tools for the source format and the review task. - [JSON TOML Converter](/developers/json-toml-converter/) converts JSON objects and TOML documents in the browser. - [JSON Formatter](/developers/json-formatter/) checks JSON syntax and makes nested data easier to read. - [Properties JSON Converter](/developers/properties-json-converter/) handles Java properties when that is the actual source format. ## FAQ **Q: Does TOML support null?** A: No. The converter offers removal or an empty string. Both options change the original JSON value. **Q: Does sorting change the order of array entries?** A: No. This converter sorts object keys. It keeps array entry order, except that the Drop policy removes null entries. **Q: Can I convert TOML back to JSON?** A: Yes. Select TOML to JSON. The output uses JSON-compatible values and string representations for date and time values. **Q: Does this tool validate a package manifest?** A: No. It converts the document syntax and data structure. It does not check application-specific manifest requirements. **Q: Does the converter upload the document?** A: Conversion runs in the browser without sending the document to FindUtils. The page can still load advertisements and other external resources. **Q: Can I use this converter through REST or MCP?** A: No. This converter currently has a browser page only. The page does not require an account. ## Next steps Use the [configuration conversion review](/blog/config-conversion-review-checklist/) before you replace an existing file. Read the [ENV to JSON guide](/guides/env-to-json/) for flat environment values. Read the [Properties to JSON guide](/guides/properties-to-json/) for dotted property names and Java escapes.