Universal.Common.Json 1.4.0

Universal.Common.Json

This package provides JSON Schema functionality according to the Draft 2020-12 specification, including a JsonSchema class for direct schema manipulation, a JsonSchemaConverter for automatically generating schemas from .NET types, and a JsonSchemaValidator for validating JSON data against schemas.

Features

• Full support for JSON Schema Draft 2020-12
• Serialization and deserialization using both Newtonsoft.Json and System.Text.Json
• Extension data support for custom keywords
• Automatic schema generation from .NET types
• Support for data annotation attributes
• Comprehensive JSON validation against schemas
• JSON token extraction based on schema matching

Usage

Creating Schemas Manually

Here's a basic example of how to create and serialize a JSON Schema:

using Universal.Common.Json;
using System.Text.Json;

var schema = new JsonSchema
{
    Title = "Person",
    Type = "object",
    Properties = new Dictionary<string, JsonSchema>
    {
        ["name"] = new JsonSchema { Type = "string" },
        ["age"] = new JsonSchema { Type = "integer", Minimum = 0 },
        ["email"] = new JsonSchema { Type = "string", Format = "email" }
    },
    Required = new[] { "name", "email" }
};

string jsonString = JsonSerializer.Serialize(schema);
Console.WriteLine(jsonString);

Validating JSON Data

You can validate JSON data against your schemas using the bool Validate(string) method on JsonSchema or, to retrieve a full list of errors, the dedicated JsonSchemaValidator class:

var schema = new JsonSchema
{
    Type = "object",
    Properties = new Dictionary<string, JsonSchema>
    {
        ["name"] = new JsonSchema { Type = "string", MinLength = 2 },
        ["age"] = new JsonSchema { Type = "integer", Minimum = 0 },
        ["email"] = new JsonSchema { Type = "string", Format = "email" }
    },
    Required = new[] { "name", "email" }
};

var validator = new JsonSchemaValidator(schema);

// Validate JSON string
string validJson = @"{
    ""name"": ""John"",
    ""age"": 30,
    ""email"": ""john@example.com""
}";

var result = validator.Validate(validJson);
if (result.IsValid)
{
    Console.WriteLine("Validation successful!");
}
else
{
    Console.WriteLine("Validation errors:");
    foreach (string error in result.Errors)
    {
        Console.WriteLine($"- {error}");
    }
}

Extracting Schema-Matched JSON

The JsonSchemaExtractor class allows you to find and extract JSON tokens from a larger text that match a specific schema. This is particularly useful when processing logs, documents, or other text that might contain JSON data:

// Create a schema for the JSON you want to extract
var schema = new JsonSchema
{
    Type = "object",
    Properties = new Dictionary<string, JsonSchema>
    {
        ["id"] = new JsonSchema { Type = "string" },
        ["data"] = new JsonSchema { Type = "object" }
    },
    Required = new[] { "id" }
};

var extractor = new JsonSchemaExtractor(schema);

// Example text containing multiple JSON objects
string text = @"Some text here { ""id"": ""123"", ""data"": {} }
                more text { ""id"": ""456"", ""data"": { ""value"": 42 } }";

// Extract all matching JSON objects
foreach (var match in extractor.Extract(text))
{
    Console.WriteLine($"Found match at position {match.Index}:");
    Console.WriteLine(match.Text);
    
    // Convert to strongly-typed object
    var typedObject = match.As<MyClass>();
}

The extractor supports:

• Finding object ({}) or array ([]) tokens based on schema type
• Proper handling of nested objects and arrays
• Correct processing of escaped characters and strings
• Strong-type conversion of matched tokens
• Position tracking (index and length) of matches in the original text

Generating Schemas from .NET Types

You can automatically generate JSON Schemas from your .NET classes using the JsonSchemaConverter:

using Universal.Common.Json;
using System.ComponentModel.DataAnnotations;

// Define your model with validation attributes
public class Person
{
    [Required]
    [StringLength(50, MinimumLength = 2)]
    public string Name { get; set; }

    [Range(0, 120)]
    public int Age { get; set; }

    [Required]
    [RegularExpression(@"^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$")]
    public string Email { get; set; }

    [MinLength(1)]
    [MaxLength(10)]
    public List<string> Tags { get; set; }
}

// Generate schema
var converter = new JsonSchemaConverter();
JsonSchema schema = converter.Convert<Person>();

Supported Validation Attributes

The JsonSchemaConverter supports the following validation attributes:

• [Required] - Marks properties as required in the schema
• [StringLength] - Sets minimum and maximum string length
• [MinLength], [MaxLength] - Sets collection size constraints
• [Range] - Sets minimum and maximum numeric values
• [RegularExpression] - Sets string patterns
• [JsonPropertyName] - Customizes property names in the schema
• [Description] - Adds property descriptions to the schema

Deserialization

You can deserialize existing JSON Schema strings into JsonSchema objects:

string jsonString = @"{
    ""$schema"": ""https://json-schema.org/draft/2020-12/schema"",
    ""title"": ""Person"",
    ""type"": ""object"",
    ""properties"": {
        ""name"": { ""type"": ""string"" },
        ""age"": { ""type"": ""integer"", ""minimum"": 0 },
        ""email"": { ""type"": ""string"", ""format"": ""email"" }
    },
    ""required"": [""name"", ""email""]
}";

JsonSchema schema = JsonSerializer.Deserialize<JsonSchema>(jsonString);

Special Cases

The converter handles several special cases:

• Collections (IEnumerable<T>, List<T>, arrays) are converted to array schemas
• Objects marked with [JsonObject] are treated as objects even if they implement collection interfaces
• Nullable types are supported
• Nested objects are automatically converted to nested schemas
• Both System.Text.Json and Newtonsoft.Json attributes are respected

Example with Complex Types

public class Order
{
    [Required]
    public string OrderId { get; set; }

    [Required]
    public Customer Customer { get; set; }

    [MinLength(1)]
    public List<OrderItem> Items { get; set; }

    [Range(0, double.MaxValue)]
    public decimal TotalAmount { get; set; }
}

public class Customer
{
    [Required]
    [StringLength(100)]
    public string Name { get; set; }

    [Required]
    [RegularExpression(@"^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$")]
    public string Email { get; set; }
}

public class OrderItem
{
    [Required]
    public string ProductId { get; set; }

    [Range(1, int.MaxValue)]
    public int Quantity { get; set; }
}

// Generate and validate against a schema
var converter = new JsonSchemaConverter();
JsonSchema orderSchema = converter.Convert<Order>();

var validator = new JsonSchemaValidator(orderSchema);
var result = validator.Validate(jsonOrderData);