Skip to main content

JSON Integration

Convert between JSON and TOON formats using ToonNet.Extensions.Json.

Installation​

dotnet add package ToonNet.Extensions.Json

ToonConvert Class​

Static utility class for JSON ↔ TOON ↔ .NET object conversion. Its methods work on strings.

Deserialize from JSON​

Convert a JSON string directly to a .NET object. This is a thin wrapper over System.Text.Json's JsonSerializer.Deserialize (TOON is not involved), so the usual System.Text.Json rules apply: property names are matched case-sensitively unless you pass options.

using System.Text.Json;
using ToonNet.Extensions.Json;

string jsonString = """
{
"name": "Alice",
"age": 30
}
""";

var jsonOptions = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
Person? person = ToonConvert.DeserializeFromJson<Person>(jsonString, jsonOptions);

To go JSON → TOON → .NET object instead, use ToonConvert.ParseJson<T>(json, toonSerializerOptions). TOON keys must then match the property names (or the PropertyNamingPolicy).

Serialize to JSON​

Convert .NET objects directly to JSON (a wrapper over JsonSerializer.Serialize; indented when no options are passed):

var person = new Person { Name = "Alice", Age = 30 };
string json = ToonConvert.SerializeToJson(person);

JSON to TOON Conversion​

string json = """{ "name": "Alice", "age": 30 }""";

string toonString = ToonConvert.FromJson(json);
// Output:
// name: Alice
// age: 30

Pass ToonOptions to control the encoding, e.g. ToonConvert.FromJson(json, new ToonOptions { Delimiter = '|' }).

TOON to JSON Conversion​

string toonString = """
name: Alice
age: 30
""";

string json = ToonConvert.ToJson(toonString);
// Output: {"name":"Alice","age":30}

ToonJsonConverter Class​

Bidirectional converter with more control:

using ToonNet.Core.Encoding;
using ToonNet.Core.Models;
using ToonNet.Extensions.Json;

// JSON → TOON
string json = """{"users": [{"name": "Alice"}, {"name": "Bob"}]}""";
ToonDocument toonDoc = ToonJsonConverter.FromJson(json);
string toon = new ToonEncoder().Encode(toonDoc);
// Output:
// users[2]{name}:
// Alice
// Bob

// TOON → JSON
string toonInput = """
users[2]{name}:
Alice
Bob
""";
ToonDocument doc = ToonDocument.Parse(toonInput);
string jsonBack = ToonJsonConverter.ToJson(doc);
// Output: {"users":[{"name":"Alice"},{"name":"Bob"}]}

ToonJsonConverter.ToJson also accepts a single ToonValue.

With JsonElement​

using System.Text.Json;

JsonDocument jsonDoc = JsonDocument.Parse(jsonString);
JsonElement element = jsonDoc.RootElement;

ToonDocument toonDoc = ToonJsonConverter.FromJson(element);

With JsonWriterOptions​

var options = new JsonWriterOptions
{
Indented = true
};

string prettyJson = ToonJsonConverter.ToJson(toonDoc, options);

Complete Workflow Examples​

Scenario 1: API Migration (JSON → TOON)​

// Existing JSON API response
string jsonResponse = await httpClient.GetStringAsync("/api/users");

// Convert to TOON for AI/LLM
string toonString = ToonConvert.FromJson(jsonResponse);

// Now use with an LLM (uniform arrays of objects become compact tables)
string prompt = $"Analyze this data:\n{toonString}";

Scenario 2: Data Import​

using ToonNet.Core.Serialization;
using ToonNet.Extensions.Json;

// Read JSON file
string json = File.ReadAllText("data.json");

// Convert to .NET objects via TOON
var data = ToonConvert.ParseJson<MyData>(json);

// Process data
ProcessData(data);

// Save as TOON for future use
string toon = ToonSerializer.Serialize(data);
File.WriteAllText("data.toon", toon);

Scenario 3: Format Transformation​

using System.Text.Json;
using ToonNet.Core.Models;
using ToonNet.Extensions.Json;

// JSON → TOON → JSON (with formatting)
string compactJson = """{"name":"Alice","age":30}""";

ToonDocument toonDoc = ToonJsonConverter.FromJson(compactJson);

var options = new JsonWriterOptions { Indented = true };
string prettyJson = ToonJsonConverter.ToJson(toonDoc, options);

Console.WriteLine(prettyJson);
// Output:
// {
// "name": "Alice",
// "age": 30
// }

Key Methods Summary​

MethodDescription
ToonConvert.DeserializeFromJson<T>(string, JsonSerializerOptions?)JSON → .NET object (System.Text.Json)
ToonConvert.SerializeToJson<T>(T, JsonSerializerOptions?).NET object → JSON (System.Text.Json)
ToonConvert.ParseJson<T>(string, ToonSerializerOptions?)JSON → TOON → .NET object
ToonConvert.FromJson(string, ToonOptions?)JSON string → TOON string
ToonConvert.ToJson(string, JsonWriterOptions?, ToonOptions?)TOON string → JSON string
ToonJsonConverter.FromJson(string), FromJson(string, ToonOptions?)JSON string → ToonDocument
ToonJsonConverter.FromJson(JsonElement), FromJson(JsonElement, ToonOptions?)JsonElement → ToonDocument
ToonJsonConverter.ToJson(ToonDocument, JsonWriterOptions?)ToonDocument → JSON string
ToonJsonConverter.ToJson(ToonValue, JsonWriterOptions?)ToonValue → JSON string

Conversion Notes​

  • JSON numbers keep their exact value when it fits in a decimal (12345678901234567890 and 1299.99 round-trip unchanged); other magnitudes use the nearest double, and a number that is not finite as a double (1e400) is kept as a string. Numbers are written in canonical form as TOON spec §2 requires: 35.00 becomes 35.
  • FromJson limits nesting with ToonOptions.MaxDepth (default 100; the root is at depth 0, as in TOON; a JsonElement too), accepts comments and trailing commas (as in appsettings.json), and rejects duplicate keys with a JsonException in strict mode (the default); with StrictMode = false the last value wins. Every error is a JsonException (or a type derived from it): too deep, invalid JSON, a duplicate key, or a string or key with an unpaired surrogate escape ("\uD800").
  • ToJson writes trees as deep as TOON allows (1,000 levels below the root); a deeper tree built in code, or one deeper than the MaxDepth of the JsonWriterOptions you pass, throws InvalidOperationException.
  • ToJson writes non-ASCII text as is ("Çağrı", not "\u00C7a\u011Fr\u0131"); HTML-sensitive characters such as < stay escaped. Pass your own JsonWriterOptions to change the encoder or indentation.
  • ToonConvert.ToJson parses TOON with the default ToonOptions (strict mode); pass toonOptions: to change that.

Use Cases​

  1. API Response Transformation: Convert JSON APIs to TOON for LLM consumption
  2. Data Migration: Import JSON data into TOON-based systems
  3. Format Conversion: Bi-directional JSON ↔ TOON transformation
  4. Token Optimization: Send compact TOON instead of JSON to LLMs
  5. Interoperability: Work with JSON systems while using TOON internally

See Also​