Universal.Common.Json 1.1.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 and a JsonSchemaConverter for automatically generating schemas from .NET types.

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

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

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 schema for the entire object graph
var converter = new JsonSchemaConverter();
JsonSchema orderSchema = converter.Convert<Order>();