JSON Interoperability

TeaLeaf provides built-in bidirectional JSON conversion for easy integration with existing tools and systems.

JSON to TeaLeaf

CLI

# JSON to TeaLeaf text (with automatic schema inference)
tealeaf from-json input.json -o output.tl

# JSON to TeaLeaf binary
tealeaf json-to-tlbx input.json -o output.tlbx

Rust API

#![allow(unused)]
fn main() {
let doc = TeaLeaf::from_json(json_string)?;

// With automatic schema inference for arrays
let doc = TeaLeaf::from_json_with_schemas(json_string)?;
}

.NET API

using var doc = TLDocument.FromJson(jsonString);

Type Mappings (JSON → TeaLeaf)

Limitations

JSON import is “plain JSON only” – it does not recognize the special JSON forms used for TeaLeaf export:

For full round-trip fidelity with these types, use binary format (.tlbx) or reconstruct programmatically.

TeaLeaf to JSON

CLI

# Text to JSON
tealeaf to-json input.tl -o output.json

# Binary to JSON
tealeaf tlbx-to-json input.tlbx -o output.json

Both commands write to stdout if -o is not specified.

Rust API

#![allow(unused)]
fn main() {
let json = doc.to_json()?;         // pretty-printed
let json = doc.to_json_compact()?;  // minified
}

.NET API

string json = doc.ToJson();         // pretty-printed
string json = doc.ToJsonCompact();   // minified

Type Mappings (TeaLeaf → JSON)

Schema Inference

When converting JSON to TeaLeaf, the from-json command (and from_json_with_schemas API) can automatically infer schemas from arrays of uniform objects.

How It Works

1. Array Detection – identifies arrays of objects with identical field sets
2. Name Inference – singularizes parent key names ("products" → product schema)
3. Type Inference – determines field types across all array items
4. Nullable Detection – fields with any null values become nullable (string?)
5. Nested Schemas – creates separate schemas for nested objects within array elements

Example

Input JSON:

{
  "customers": [
    {
      "id": 1,
      "name": "Alice",
      "billing_address": {"street": "123 Main", "city": "Boston"}
    },
    {
      "id": 2,
      "name": "Bob",
      "billing_address": {"street": "456 Oak", "city": "Denver"}
    }
  ]
}

Inferred TeaLeaf output:

@struct billing_address (city: string, street: string)
@struct customer (billing_address: billing_address, id: int, name: string)

customers: @table customer [
  (("Boston", "123 Main"), 1, "Alice"),
  (("Denver", "456 Oak"), 2, "Bob"),
]

Nested Schema Inference

When array elements contain nested objects, TeaLeaf creates schemas for those nested objects if they have uniform structure across all items:

• Nested objects become their own @struct definitions
• Parent schemas reference nested schemas by name (not object type)
• Deeply nested objects are handled recursively

Round-Trip Considerations

For types that don’t round-trip through JSON (Ref, Tagged, Map, Timestamp, Bytes), use the binary format for lossless storage.