ToonNet.Extensions.Json 4.0.0

ToonNet.Extensions.Json

JSON ↔ TOON format conversion extension

📦 What is ToonNet.Extensions.Json?

ToonNet.Extensions.Json provides seamless bidirectional conversion between JSON and TOON formats:

• ✅ JSON → TOON - Convert JSON strings/documents to TOON format
• ✅ TOON → JSON - Convert TOON strings/documents to JSON format
• ✅ System.Text.Json integration - Familiar API patterns
• ✅ Preserves structure - Round-trip conversions keep objects, arrays and values (numbers keep their exact value)
• ✅ Developer-friendly - Static ToonConvert (string-based) and ToonJsonConverter (document-based) helpers

Perfect for:

• 🤖 AI/LLM Applications - Convert JSON APIs to token-efficient TOON
• 🔄 Data Migration - Transform existing JSON data to TOON format
• 🔗 Interoperability - Work with JSON-based systems
• 📊 API Integration - Accept JSON, process as TOON, return JSON

🚀 Quick Start

Installation

# Core package (required)
dotnet add package ToonNet.Core

# JSON extension
dotnet add package ToonNet.Extensions.Json

Basic Usage - String Conversion

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

// JSON → TOON string conversion
string jsonString = """
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["reading", "coding"]
}
""";

string toonString = ToonConvert.FromJson(jsonString);

// Output (TOON format):
// name: Alice
// age: 30
// hobbies[2]: reading,coding

// TOON → JSON string conversion
string jsonBack = ToonConvert.ToJson(toonString);

Object Serialization via JSON

using ToonNet.Extensions.Json;

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies { get; set; }
}

var person = new Person 
{ 
    Name = "Bob", 
    Age = 25, 
    Hobbies = new List<string> { "gaming", "music" }
};

// Serialize C# object to JSON
string json = ToonConvert.SerializeToJson(person);

// Deserialize JSON to C# object (plain System.Text.Json, case-sensitive by default)
var personBack = ToonConvert.DeserializeFromJson<Person>(json);

// One-step: JSON string → C# object via TOON.
// TOON keys must match the property names; the camelCase policy maps "name" to Name.
var person2 = ToonConvert.ParseJson<Person>(jsonString,
    new ToonSerializerOptions { PropertyNamingPolicy = PropertyNamingPolicy.CamelCase });

📖 API Reference

String Format Conversion

// JSON string → TOON string
string toon = ToonConvert.FromJson(jsonString);
string toon = ToonConvert.FromJson(jsonString, options);  // ToonOptions

// TOON string → JSON string
string json = ToonConvert.ToJson(toonString);
string json = ToonConvert.ToJson(toonString, writerOptions);  // JsonWriterOptions
string json = ToonConvert.ToJson(toonString, writerOptions, toonOptions);  // ToonOptions for parsing the TOON input

Document Conversion (Low-level)

using ToonNet.Extensions.Json;

// JSON string → ToonDocument (options: MaxDepth, and StrictMode for duplicate keys)
ToonDocument doc = ToonJsonConverter.FromJson(jsonString);
ToonDocument doc = ToonJsonConverter.FromJson(jsonString, new ToonOptions { StrictMode = false });  // last duplicate wins; trusted JSON only

// JsonElement → ToonDocument
ToonDocument doc = ToonJsonConverter.FromJson(jsonElement);

// ToonDocument → JSON string
string json = ToonJsonConverter.ToJson(document);
string json = ToonJsonConverter.ToJson(document, writerOptions);  // JsonWriterOptions

// ToonValue → JSON string
string json = ToonJsonConverter.ToJson(toonValue);
string json = ToonJsonConverter.ToJson(toonValue, writerOptions);  // JsonWriterOptions

Object Serialization

SerializeToJson and DeserializeFromJson are thin wrappers over System.Text.Json.JsonSerializer (TOON is not involved; SerializeToJson indents when no options are passed).

// C# object → JSON string
string json = ToonConvert.SerializeToJson<T>(obj);
string json = ToonConvert.SerializeToJson<T>(obj, options);  // JsonSerializerOptions

// JSON string → C# object
T obj = ToonConvert.DeserializeFromJson<T>(jsonString);
T obj = ToonConvert.DeserializeFromJson<T>(jsonString, options);  // JsonSerializerOptions

// JSON string → TOON → C# object (one step)
T obj = ToonConvert.ParseJson<T>(jsonString);
T obj = ToonConvert.ParseJson<T>(jsonString, options);  // ToonSerializerOptions

🎯 Real-World Examples

Example 1: AI/LLM Token Optimization

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

// Receive JSON from API
string apiResponse = await httpClient.GetStringAsync("/api/products");

// Convert to TOON (fewer tokens for LLM)
string toonData = ToonConvert.FromJson(apiResponse);

// Use in LLM prompt
string prompt = $"""
You are a product analyst. Here is the product catalog:

{toonData}

Recommend the best products for a software developer.
""";

// Uniform arrays of objects become TOON tables, which usually take fewer tokens than JSON

Example 2: Data Migration

// Load existing JSON configuration
string jsonConfig = File.ReadAllText("appsettings.json");

// Convert to TOON format
string toonConfig = ToonConvert.FromJson(jsonConfig);

// Save as TOON (more human-readable)
File.WriteAllText("appsettings.toon", toonConfig);

// Later: Load TOON and convert back if needed
string toonContent = File.ReadAllText("appsettings.toon");
var config = ToonSerializer.Deserialize<AppSettings>(toonContent);

Example 3: Roundtrip Verification

// Original JSON
string originalJson = """{"discount": 35.00, "active": true}""";

// JSON → TOON → JSON
string toonString = ToonConvert.FromJson(originalJson);
string roundtripJson = ToonConvert.ToJson(toonString);

// Normalize both for comparison
var original = JsonSerializer.Deserialize<object>(originalJson);
var roundtrip = JsonSerializer.Deserialize<object>(roundtripJson);

// Semantic equivalence preserved (format may differ)
// roundtripJson is {"discount":35,"active":true}

🔄 Format Conversion Behavior

Type Mapping

• FromJson limits nesting with ToonOptions.MaxDepth (default 100; the root is at depth 0, as in TOON), 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.
• 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.

Semantic Equivalence

Important: Format conversions preserve semantic equivalence, not exact formatting:

// JSON: {"price": 35.00}
// TOON: price: 35
// JSON (roundtrip): {"price":35}  ← Format differs, value identical

JSON numbers are converted with the TOON number rules: the exact value is kept when it fits in a decimal (so 12345678901234567890 and 1299.99 round-trip unchanged), smaller or larger magnitudes use the nearest double, and a number that is not finite as a double (e.g. 1e400) is kept as a string. As TOON spec §2 requires, numbers are written in canonical form, so 35.00 becomes 35 and 1.0 becomes 1 (same value). ToonJsonConverter.FromJson(string) limits the nesting to the MaxDepth of the ToonOptions (default 100, the root at depth 0) and accepts comments and trailing commas, as in appsettings.json files.

See Roundtrip Guarantees for details.

🔒 Thread-Safety

• ToonSerializer and JSON conversion methods are safe to call concurrently across threads.
• Shared metadata/name caches use ConcurrentDictionary for concurrent access.
• Cache entries are created on demand and retained for the process lifetime (no eviction).
• Do not mutate a single ToonSerializerOptions instance concurrently across threads.

🔗 Related Packages

Core:

• ToonNet.Core - Core serialization (required)

Other Extensions:

• ToonNet.Extensions.Yaml - YAML ↔ TOON conversion

Web Integration:

• ToonNet.AspNetCore - TOON configuration provider and DI integration
• ToonNet.AspNetCore.Mvc - MVC formatters

Development:

• ToonNet.Demo - Sample applications with JSON examples
• ToonNet.Tests - JSON conversion test suite

📚 Documentation

• Main Documentation - Complete ToonNet guide
• API Guide - Detailed API reference
• Samples - Real-world JSON examples

🧪 Testing

# Run JSON conversion tests
cd tests/ToonNet.Tests
dotnet test --filter "FullyQualifiedName~ToonJsonConverter"

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Part of the ToonNet serialization library family.