Universal.Common.Json 1.5.0

Universal.Common.Json

This package provides JSON Schema functionality according to the Draft 2020-12 specification, offering two distinct implementations for schema generation: JsonSchemaConverter and SelfReferencingJsonSchemaConverter. It includes functionality for direct schema manipulation, automatic schema generation from .NET types, and JSON validation against schemas.

Features

• Full support for JSON Schema Draft 2020-12
• Two schema converter implementations for different use cases
• 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

Schema Converters

JsonSchemaConverter

The standard converter is optimized for simple to moderately complex types. It's ideal when:

• Your types don't have circular references
• You need straightforward, flat schema generation
• Performance is a priority
• You're working with DTOs or simple data models

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

SelfReferencingJsonSchemaConverter

This specialized converter handles complex object graphs and self-referencing types. Use it when:

• Your types contain circular references
• You need to handle inheritance properly
• You want schemas with shared definitions
• You're working with complex domain models

var converter = new SelfReferencingJsonSchemaConverter();
JsonSchema schema = converter.Convert<ComplexType>();

Key differences:

• Creates $ref references for complex types
• Maintains a definitions section for reused types
• Handles circular dependencies gracefully
• May produce larger schemas due to type definitions

Usage Examples

Basic Type Conversion

// Using standard converter
var standardConverter = new JsonSchemaConverter();
var personSchema = standardConverter.Convert<Person>();

// Using self-referencing converter
var complexConverter = new SelfReferencingJsonSchemaConverter();
var orderSchema = complexConverter.Convert<Order>();

Handling Self-References

public class Employee
{
    [Required]
    public string Name { get; set; }

    [Required]
    public Employee Manager { get; set; }  // Self-reference

    public List<Employee> DirectReports { get; set; }
}

// Use SelfReferencingJsonSchemaConverter for this case
var converter = new SelfReferencingJsonSchemaConverter();
JsonSchema schema = converter.Convert<Employee>();

The resulting schema will include definitions to handle the self-reference:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "manager": { "$ref": "#/definitions/Employee" },
    "directReports": {
      "type": "array",
      "items": { "$ref": "#/definitions/Employee" }
    }
  },
  "required": ["name", "manager"],
  "definitions": {
    "Employee": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "manager": { "$ref": "#/definitions/Employee" },
        "directReports": {
          "type": "array",
          "items": { "$ref": "#/definitions/Employee" }
        }
      },
      "required": ["name", "manager"]
    }
  }
}

Complex Inheritance Example

public abstract class Vehicle
{
    [Required]
    public string VIN { get; set; }

    public decimal Price { get; set; }
}

public class Car : Vehicle
{
    public int Doors { get; set; }
    public List<string> Features { get; set; }
}

public class Fleet
{
    public List<Vehicle> Vehicles { get; set; }
    public Car PrimaryCar { get; set; }
}

// Use SelfReferencingJsonSchemaConverter for inheritance
var converter = new SelfReferencingJsonSchemaConverter();
JsonSchema schema = converter.Convert<Fleet>();

Validation

Both schema types can be used with the validator:

var validator = new JsonSchemaValidator(schema);
var result = validator.Validate(jsonData);
if (!result.IsValid)
{
    foreach (string error in result.Errors)
    {
        Console.WriteLine($"Validation error: {error}");
    }
}

Supported Validation Attributes

Both converters support 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

Best Practices

1. Choose the right converter:

   • Use JsonSchemaConverter for simple types and better performance
   • Use SelfReferencingJsonSchemaConverter for complex object graphs

2. Consider schema size:

   • SelfReferencingJsonSchemaConverter produces larger schemas due to definitions
   • Use it only when necessary to handle circular references or complex inheritance

3. Performance considerations:

   • JsonSchemaConverter is more performant for simple types
   • SelfReferencingJsonSchemaConverter has additional overhead for tracking references

4. Type organization:

   • Group related types to make schemas more maintainable
   • Use inheritance thoughtfully to avoid overly complex schemas

5. Validation attributes:

   • Apply validation attributes consistently across your models
   • Consider using custom attributes for special cases

Known Limitations

• JsonSchemaConverter doesn't handle circular references
• SelfReferencingJsonSchemaConverter may produce larger schemas
• Both converters have limited support for dynamic types
• Custom serialization attributes may not be fully supported