Bebop.JsonSchema 1.1.0

Bebop.JsonSchema

A high-performance JSON Schema validator for .NET, built on top of System.Text.Json.

Supported JSON Schema Versions

When no $schema is specified, Draft 2020-12 is assumed. Custom meta-schemas are supported — define your own vocabularies and dialects on top of Draft 2020-12 or 2019-09.

Features

• Zero-allocation validation path — designed with performance in mind; minimal allocations on the hot path
• Built on System.Text.Json — no third-party JSON parser dependencies
• Async-first API — schema creation, preparation, and validation are all async
• $ref and $dynamicRef resolution — local, HTTP-resolving, and custom schema registries
• Format validation — built-in validators for email, ipv4, ipv6, uri, uuid, date-time, date, time, duration, and more. In Draft 2020-12 and 2019-09, format is annotation-only by default and becomes an assertion when the format-assertion vocabulary is active.
• Comprehensive keyword support — type, enum, const, allOf/anyOf/oneOf/not, if/then/else, properties, patternProperties, additionalProperties, items, prefixItems, contains, uniqueItems, unevaluatedProperties, unevaluatedItems, dependentSchemas, dependentRequired, dependencies, and all validation keywords

Targets

Installation

Install via NuGet:

dotnet add package Bebop.JsonSchema

Or visit the NuGet package page.

Getting Started

Create and validate against a schema

using Bebop.JsonSchema;
using System.Text.Json;

// Define a schema
var schema = await JsonSchema.Create("""
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "required": ["name", "age"],
      "properties": {
        "name": { "type": "string", "minLength": 1 },
        "age":  { "type": "integer", "minimum": 0 }
      }
    }
    """);

// Prepare the schema (resolves $ref, etc.)
await schema.Prepare();

// Validate a JSON document
using var doc = JsonDocument.Parse("""{ "name": "Alice", "age": 30 }""");

var errors = new ErrorCollection();
bool isValid = await schema.Validate(doc, errors);
// isValid == true

Validate from a JsonElement

using var doc = JsonDocument.Parse("""{ "name": "", "age": -1 }""");

var errors = new ErrorCollection();
bool isValid = await schema.Validate(doc.RootElement, errors);
// isValid == false

// Access validation errors
Console.WriteLine($"Found {errors.Count} validation errors:");
foreach (var error in errors)
{
    Console.WriteLine($"  - {error.Message} at {error.Path}");
}

Use a remote-resolving schema registry

If your schema references external schemas via $ref, use a resolving registry that fetches them over HTTP:

var registry = SchemaRegistry.Resolving();
var schema = await JsonSchema.Create(schemaDocument, registry);
await schema.Prepare();

Use a custom schema resolver

Implement ISchemaResolver to control how referenced schemas are loaded (e.g. from a database, embedded resources, or a local file system):

public class MyResolver : ISchemaResolver
{
    public async ValueTask<JsonElement?> Resolve(Uri id)
    {
        // Load the schema JSON by URI and return the root element,
        // or return null if not found.
    }
}

var registry = SchemaRegistry.Custom(new MyResolver());
var schema = await JsonSchema.Create(schemaDocument, registry);
await schema.Prepare();

Schema Registries

Built-in Format Validators

The following format values are validated when the format vocabulary is active:

email · idn-email · ipv4 · ipv6 · uri · uuid · date-time · date · time · duration

Performance

Benchmarks validate a realistic Person object (nested objects, arrays, $ref, $defs, pattern, format, additionalProperties, if/then) against a ~230-line Draft 2020-12 schema. Compared against JsonSchema.Net v8.0.4.

BenchmarkDotNet v0.15.8, Windows 11
Intel Core i7-6560U CPU 2.20GHz (Skylake), 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.103

~2.6× faster and ~60 % less memory than JsonSchema.Net on the same workload.

Reproduce locally: dotnet run --project Benchmarks.Bebop.JsonSchema -c Release

Project Structure

Bebop.JsonSchema/              # Core library
Tests.Bebop.JsonSchema/        # xUnit test suite (JSON Schema Test Suite)
Benchmarks.Bebop.JsonSchema/   # BenchmarkDotNet benchmarks

Building

dotnet build

Running Tests

dotnet test

Running Benchmarks

dotnet run --project Benchmarks.Bebop.JsonSchema -c Release

License

See LICENSE for details.