Zaiets.JsonSchema.Net 1.0.0

Zaiets.JsonSchema.Net

Generate JSON Schema from C# types — reflection-based, zero dependencies, OpenAPI-ready.

Installation

dotnet add package Zaiets.JsonSchema.Net

Quick start

using Zaiets.JsonSchema.Net;

// Generate a schema from any C# type
var schema = JsonSchemaGenerator.Default.Generate<CreateUserRequest>();
Console.WriteLine(schema.ToJson());

Output:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "CreateUserRequest",
  "type": "object",
  "properties": {
    "name":  { "type": "string", "minLength": 1, "maxLength": 100 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["name", "email"]
}

Annotating your models

using System.ComponentModel.DataAnnotations;
using Zaiets.JsonSchema.Net;

[SchemaId("https://sarmkadan.com/schemas/user.json")]
[SchemaTitle("User")]
[SchemaDescription("A registered user account.")]
public class CreateUserRequest
{
    [Required]
    [MinLength(1), MaxLength(100)]
    [SchemaDescription("Full display name")]
    public string Name { get; set; } = "";

    [Required]
    [EmailAddress]
    public string Email { get; set; } = "";

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

    [SchemaWriteOnly]
    [MinLength(8)]
    [SchemaFormat(SchemaFormats.Password)]
    public string? Password { get; set; }

    [SchemaReadOnly]
    public DateTimeOffset CreatedAt { get; set; }

    [SchemaDeprecated("Use Tags instead.")]
    public string? Category { get; set; }
}

Supported attributes

Generator options

// Draft 7 (default)
var generator = new JsonSchemaGenerator();

// Draft 2020-12
var generator = new JsonSchemaGenerator(new JsonSchemaGeneratorOptions
{
    SchemaVersion = JsonSchemaVersion.Draft202012,
});

// OpenAPI 3.0 (nullable: true style, no $schema header)
var generator = new JsonSchemaGenerator(JsonSchemaGeneratorOptions.ForOpenApi30());

// OpenAPI 3.1
var generator = new JsonSchemaGenerator(JsonSchemaGeneratorOptions.ForOpenApi31());

// Strict: no additional properties
var generator = new JsonSchemaGenerator(JsonSchemaGeneratorOptions.Strict());

// Custom property naming
var generator = new JsonSchemaGenerator(new JsonSchemaGeneratorOptions
{
    PropertyNameTransformer = name => name.ToUpperInvariant(),
});

Nullable handling

Nullable reference types and Nullable<T> are fully supported.

public class Product
{
    public string Name { get; set; } = "";   // required, non-nullable
    public string? Description { get; set; } // nullable reference type
    public int? Stock { get; set; }          // Nullable<int>
}

Draft 7 output (default — uses anyOf):

{
  "description": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
  "stock":       { "anyOf": [{ "type": "integer", "format": "int32" }, { "type": "null" }] }
}

OpenAPI 3.0 output (UseOpenApiNullable: true):

{
  "description": { "type": "string",  "nullable": true },
  "stock":       { "type": "integer", "nullable": true }
}

Fluent builder

Build schemas programmatically without reflection:

var addressSchema = JsonSchemaBuilder.New()
    .ObjectType()
    .Title("Address")
    .Property("street", JsonSchemaBuilder.StringType(b => b.MinLength(1)), required: true)
    .Property("city",   JsonSchemaBuilder.StringType(b => b.MinLength(1)), required: true)
    .Property("zip",    JsonSchemaBuilder.StringType(b => b.Pattern(@"^\d{5}$")))
    .Property("country", b => b
        .StringType()
        .Enum("US", "CA", "GB", "DE", "FR"))
    .NoAdditionalProperties()
    .Build();

Console.WriteLine(addressSchema.ToJson());

Validation

Validate JSON instances against a schema:

var schema = JsonSchemaGenerator.Default.Generate<CreateUserRequest>();

// Validate a JSON string
var result = SchemaValidator.Validate("""{"name":"Alice","email":"alice@example.com"}""", schema);

if (!result.IsValid)
    foreach (var error in result.Errors)
        Console.WriteLine(error); // [required] /: Required property 'email' is missing.

// Validate an object directly
var user = new CreateUserRequest { Name = "Bob", Email = "bob@example.com" };
var objectResult = SchemaValidator.Validate(user, schema);
Console.WriteLine(objectResult.IsValid); // True

OpenAPI integration

// Minimal API / Swashbuckle style
var generator = new JsonSchemaGenerator(JsonSchemaGeneratorOptions.ForOpenApi30());

var userSchema = generator.Generate<CreateUserRequest>()
    .WithoutSchemaKeyword()
    .WithExternalDocs("https://sarmkadan.com/docs/user", "User API reference");

// Access the raw JSON for embedding in an OpenAPI document
string json = userSchema.ToJson();

Schema registry (caching)

The generator caches schemas per type automatically:

var generator = new JsonSchemaGenerator();
var schema1 = generator.Generate<MyType>(); // generated
var schema2 = generator.Generate<MyType>(); // returned from cache (same instance)

// Inspect or pre-warm the cache
generator.Registry.Register<MyType>(customSchema);
Console.WriteLine(generator.Registry.Count);

Enum support

public enum OrderStatus { Pending, Processing, Shipped, Delivered, Cancelled }

// Integer enum (default)
var intSchema = JsonSchemaGenerator.Default.Generate<OrderStatus>();

// String enum
var stringSchema = new JsonSchemaGenerator(new JsonSchemaGeneratorOptions
{
    UseStringEnums = true
}).Generate<OrderStatus>();

Type mapping

License

MIT — see LICENSE.

Built by Vladyslav Zaiets · CTO & Software Architect