Universal.Common.Json 1.2.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

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}");
    }
}

The validator supports all JSON Schema Draft 2020-12 features including:

• Type validation
• String constraints (length, pattern, format)
• Numeric constraints (minimum, maximum, exclusive ranges)
• Array validation (length, item types)
• Object validation (required properties, property dependencies)
• Logical operators (allOf, anyOf, oneOf, not)
• Conditional validation (if/then/else)
• Format validation (email, date-time, uri, etc.)
• Enum and const values

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);