ToonNet.Extensions.Json 1.4.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 maintain data integrity
• ✅ Developer-friendly - Extension methods on ToonSerializer

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
var personBack = ToonConvert.DeserializeFromJson<Person>(json);

// One-step: JSON string → C# object via TOON
var person2 = ToonConvert.ParseJson<Person>(jsonString);

📖 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

Document Conversion (Low-level)

using ToonNet.Extensions.Json;

// JSON string → ToonDocument
ToonDocument doc = ToonJsonConverter.FromJson(jsonString);

// 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

// 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.
""";

// TOON is ~40% 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)
// 35.00 → 35 is semantically equal (JSON spec compliant)

🔄 Format Conversion Behavior

Type Mapping

Semantic Equivalence

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

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

This is standard behavior across all serialization libraries (System.Text.Json, Newtonsoft.Json). 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 - ASP.NET Core middleware
• 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"

# Run specific test categories
dotnet test --filter "Category=JsonConversion"

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Part of the ToonNet serialization library family.