tomljson

Lossless TOML ↔ JSON translation in pure Rust.

What it does

Encode serde_json::Value to TOML and back, handling the impedance gaps where TOML's data model can't natively represent something JSON can:

• Null — TOML has no null type. JSON null is encoded as a string placeholder (default "__null__", configurable). Decoding substitutes the placeholder back to null.
• Top-level non-table values — TOML documents must have a table at the root. Non-table JSON values (booleans, scalars, arrays) are wrapped under a configurable root key (default "__root__") on encode and unwrapped on decode.
• Integer range — TOML integers are signed 64-bit. Encoding rejects values larger than i64::MAX.
• Float fidelity — f64 values round-trip via f64::to_string (Ryū-shortest representation). NaN and ±∞ error explicitly on decode (JSON's number model can't represent them).
• Datetime canonicalization — all four TOML datetime variants (Date, Time, LocalDateTime, OffsetDateTime) decode to JSON strings in canonical RFC 3339 form.

The motivating use case is JSON Schema 2020-12 documents authored as TOML, but tomljson is application-agnostic — anyone moving JSON-shaped data through TOML can use it.

Quick start

use serde_json::json;

let value = json!({
    "type": "object",
    "properties": {
        "name": { "type": "string" }
    }
});

let toml_str = tomljson::to_string(&value).unwrap();
let back = tomljson::from_str(&toml_str).unwrap();
assert_eq!(back, value);

API surface

Plus:

• TomlJsonOptions { null_placeholder: String, root_placeholder: String } — configure both reserved strings if your data collides with the defaults.
• DEFAULT_NULL_PLACEHOLDER ("__null__"), DEFAULT_ROOT_PLACEHOLDER ("__root__").
• Error, Result.

Encoding rules

JSON → TOML (encode)

Internal structure on encode:

• Sub-objects → [section] headers.
• Arrays whose elements are all objects → [[array.of.tables]] headers.
• Other arrays + scalars → inline.

TOML → JSON (decode)

Design notes

Why +inf / -inf / NaN error on decode

serde_json::Number::from_f64 rejects non-finite floats. JSON itself has no syntax for them. JSON Schema's validation model can't compare against them either — maximum: inf is meaningless because every finite number satisfies it.

Producers wanting "no upper bound" should omit maximum rather than write inf. Storage layers (Parquet, Arrow, LanceDB) handle infinities natively, but the JSON validation layer cannot, and tomljson errors at the boundary so the limitation surfaces early instead of silently corrupting data.

Why absent and null must be distinguished

TOML's grammar has no syntax for "key present, no value":

x =          # parse error

But JSON treats {} and {"x": null} as different objects (key present, value null vs. key absent). To preserve this distinction across the round-trip, tomljson uses a placeholder string for null:

x = "__null__"   # x is present, value is JSON null
                 # (vs. omitting the line, which means x is absent)

Limitations

• No generic Serialize/DeserializeOwned wrapper. Callers with typed structs convert at the boundary via serde_json::to_value / serde_json::from_value.
• No streaming. Both encode and decode operate on whole documents. The underlying toml crate has no streaming parser, and TOML's key-order freedom would defeat streaming on the decode side anyway.
• Datetime decode is one-way. Decoding produces JSON strings (RFC 3339); re-encoding those strings doesn't reconstruct TOML's native datetime form. JSON has no native datetime type.

License

MIT. See LICENSE.