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
| Method | Description |
|---|---|
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(12345678901234567890and1299.99round-trip unchanged); other magnitudes use the nearestdouble, and a number that is not finite as adouble(1e400) is kept as a string. Numbers are written in canonical form as TOON spec §2 requires:35.00becomes35. FromJsonlimits nesting withToonOptions.MaxDepth(default 100; the root is at depth 0, as in TOON; aJsonElementtoo), accepts comments and trailing commas (as inappsettings.json), and rejects duplicate keys with aJsonExceptionin strict mode (the default); withStrictMode = falsethe last value wins. Every error is aJsonException(or a type derived from it): too deep, invalid JSON, a duplicate key, or a string or key with an unpaired surrogate escape ("\uD800").ToJsonwrites trees as deep as TOON allows (1,000 levels below the root); a deeper tree built in code, or one deeper than theMaxDepthof theJsonWriterOptionsyou pass, throwsInvalidOperationException.ToJsonwrites non-ASCII text as is ("Çağrı", not"\u00C7a\u011Fr\u0131"); HTML-sensitive characters such as<stay escaped. Pass your ownJsonWriterOptionsto change the encoder or indentation.ToonConvert.ToJsonparses TOON with the defaultToonOptions(strict mode); passtoonOptions:to change that.
Use Cases
- API Response Transformation: Convert JSON APIs to TOON for LLM consumption
- Data Migration: Import JSON data into TOON-based systems
- Format Conversion: Bi-directional JSON ↔ TOON transformation
- Token Optimization: Send compact TOON instead of JSON to LLMs
- Interoperability: Work with JSON systems while using TOON internally
See Also
- YAML Integration: Convert YAML ↔ TOON
- Converter Examples: Converters for types with their own text form