JsonStructure 0.5.5

JSON Structure C# SDK

A comprehensive C# SDK for JSON Structure validation, including schema validation, instance validation, schema export from .NET types, and System.Text.Json converters for correct serialization of large numeric types.

Features

• Schema Validation: Validate JSON Structure schema documents
• Instance Validation: Validate JSON instances against JSON Structure schemas
• Schema Export: Generate JSON Structure schemas from .NET types (similar to System.Text.Json.Schema.JsonSchemaExporter)
• System.Text.Json Converters: Serialize large integers (int64, uint64, int128, uint128, decimal) as strings to preserve precision

Installation

dotnet add package JsonStructure

Usage

Schema Validation

using JsonStructure.Validation;
using System.Text.Json.Nodes;

var validator = new SchemaValidator();

var schema = new JsonObject
{
    ["type"] = "object",
    ["properties"] = new JsonObject
    {
        ["name"] = new JsonObject { ["type"] = "string" },
        ["age"] = new JsonObject { ["type"] = "int32" }
    },
    ["required"] = new JsonArray { "name" }
};

var result = validator.Validate(schema);
if (result.IsValid)
{
    Console.WriteLine("Schema is valid!");
}
else
{
    foreach (var error in result.Errors)
    {
        Console.WriteLine($"{error.Path}: {error.Message}");
    }
}

Instance Validation

using JsonStructure.Validation;
using System.Text.Json.Nodes;

var validator = new InstanceValidator();

var schema = new JsonObject
{
    ["type"] = "object",
    ["properties"] = new JsonObject
    {
        ["name"] = new JsonObject { ["type"] = "string" },
        ["age"] = new JsonObject { ["type"] = "int32", ["minimum"] = 0 }
    },
    ["required"] = new JsonArray { "name" }
};

var instance = new JsonObject
{
    ["name"] = "John",
    ["age"] = 30
};

var result = validator.Validate(instance, schema);
if (result.IsValid)
{
    Console.WriteLine("Instance is valid!");
}

Sideloading External Schemas

When using $import to reference external schemas, you can provide those schemas directly instead of fetching them from URIs:

using JsonStructure.Validation;
using System.Text.Json.Nodes;

// External schema that would normally be fetched
var addressSchema = new JsonObject
{
    ["$schema"] = "https://json-structure.org/meta/core/v0/#",
    ["$id"] = "https://example.com/address.json",
    ["type"] = "object",
    ["properties"] = new JsonObject
    {
        ["street"] = new JsonObject { ["type"] = "string" },
        ["city"] = new JsonObject { ["type"] = "string" }
    }
};

// Main schema that imports the address schema
var mainSchema = new JsonObject
{
    ["$schema"] = "https://json-structure.org/meta/core/v0/#",
    ["type"] = "object",
    ["properties"] = new JsonObject
    {
        ["name"] = new JsonObject { ["type"] = "string" },
        ["address"] = new JsonObject { ["$ref"] = "#/definitions/Imported/Address" }
    },
    ["definitions"] = new JsonObject
    {
        ["Imported"] = new JsonObject
        {
            ["$import"] = "https://example.com/address.json"
        }
    }
};

// Sideload the address schema - keyed by URI
var options = new ValidationOptions
{
    AllowImport = true,
    ExternalSchemas = new Dictionary<string, JsonNode>
    {
        ["https://example.com/address.json"] = addressSchema
    }
};

var validator = new SchemaValidator(options);
var result = validator.Validate(mainSchema);

Schema Export from .NET Types

Generate JSON Structure schemas from C# classes:

using JsonStructure.Schema;
using System.ComponentModel.DataAnnotations;

public class Person
{
    [Required]
    [StringLength(100, MinimumLength = 1)]
    public string Name { get; set; } = "";

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

    public List<string> Tags { get; set; } = new();

    public Dictionary<string, int> Scores { get; set; } = new();
}

// Generate schema
var schema = JsonStructureSchemaExporter.GetJsonStructureSchemaAsNode<Person>();

// Output:
// {
//   "$schema": "https://json-structure.org/meta/core/v1.0",
//   "type": "object",
//   "title": "Person",
//   "properties": {
//     "Name": { "type": "string", "minLength": 1, "maxLength": 100 },
//     "Age": { "type": "int32", "minimum": 0, "maximum": 150 },
//     "Tags": { "type": "array", "items": { "type": "string" } },
//     "Scores": { "type": "map", "values": { "type": "int32" } }
//   },
//   "required": ["Name"]
// }

System.Text.Json Converters

Use the converters to correctly serialize large integers as strings (avoiding JavaScript precision issues):

using JsonStructure.Converters;
using System.Text.Json;

// Create options with all JSON Structure converters
var options = JsonStructureConverters.CreateOptions();

// Or add to existing options
var existingOptions = new JsonSerializerOptions();
JsonStructureConverters.ConfigureOptions(existingOptions);

// Now large numbers are serialized as strings
var data = new { BigNumber = 9007199254740993L };
var json = JsonSerializer.Serialize(data, options);
// Output: {"BigNumber":"9007199254740993"}

// Decimals are also serialized as strings for precision
var money = new { Amount = 12345.67890123456789m };
var moneyJson = JsonSerializer.Serialize(money, options);
// Output: {"Amount":"12345.67890123456789"}

Individual Converters

The SDK includes the following converters:

Supported Types

Primitive Types

Compound Types

Validation Options

var options = new ValidationOptions
{
    StopOnFirstError = false,           // Continue collecting all errors
    StrictFormatValidation = true,      // Validate format keywords strictly
    MaxValidationDepth = 100,           // Maximum schema nesting depth
    AllowImport = true,                 // Enable $import/$importdefs processing
    ExternalSchemas = new Dictionary<string, JsonNode>
    {
        // Sideloaded schemas for import resolution (keyed by URI)
        ["https://example.com/address.json"] = addressSchema
    },
    ReferenceResolver = uri =>          // Custom $ref resolver
    {
        // Return resolved schema or null
        return null;
    }
};

var validator = new InstanceValidator(options);

Schema Export Options

var exporterOptions = new JsonStructureSchemaExporterOptions
{
    SchemaUri = "https://json-structure.org/meta/core/v1.0",
    IncludeSchemaKeyword = true,
    IncludeTitles = true,
    IncludeDescriptions = true,
    TreatNullObliviousAsNonNullable = true,
    TransformSchema = (context, schema) =>
    {
        // Custom schema transformation
        if (context.IsRoot && schema is JsonObject obj)
        {
            obj["$id"] = "https://example.com/my-schema";
        }
        return schema;
    }
};

var schema = JsonStructureSchemaExporter.GetJsonStructureSchemaAsNode<MyClass>(
    exporterOptions: exporterOptions);

License

MIT License. See LICENSE for details.