NJsonSchema for .NET: Schema Validation, Generation, and Code Output

NJsonSchema's Contract and .NET Integration

NJsonSchema addresses a specific problem in .NET contract workflows: keeping a JSON Schema and an application model synchronized without maintaining the schema by hand. It can read an existing schema from a file or string, validate JSON data against it, derive a schema from an existing .NET class through reflection, and generate C# or TypeScript from a schema. Its primary audience is .NET developers building API contracts, data models, validation layers, or generated clients. NSwag also uses NJsonSchema within its Swagger toolchain, which indicates that NJsonSchema is designed to work as a library component rather than only as a standalone application.

The core package is `NJsonSchema`. Related packages divide optional responsibilities. `NJsonSchema.Annotations` controls serialization, `NJsonSchema.Yaml` reads and writes JSON Schemas in YAML, `NJsonSchema.CodeGeneration` supplies code-generation base classes, and separate packages generate C# or TypeScript. A project may therefore need more than one package depending on its contract pipeline. The README states support for .NET Standard 2.0. It identifies v11.6.1 as the latest listed release, published on 2026-04-20. The repository is not archived, and the last push was on 2026-10-01.

Type Reflection and Schema Validation Flow

The documented workflow has three main entry points. `JsonSchema.FromType<T>()` creates a schema by reflecting over a .NET type. `JsonSchema.FromSampleJson()` derives a schema from sample JSON data. `JsonSchema.FromJsonAsync()` reads an existing schema, after which `Validate` checks JSON data against it. A generated schema can be serialized with `ToJson()` and parsed again, allowing an application to emit a contract, persist it, and consume it through the same object model.

The README's `Person` example shows how data annotations influence generated schema. `[Required]` on `FirstName` and `LastName` produces required properties with a minimum string length. `[Range(2, 5)]` becomes an integer schema with `minimum` and `maximum` constraints. `DateTime` maps to the `date-time` format, an enum becomes a referenced definition with enum values and names, and a `Collection<Car>` becomes an array whose items reference the `Car` definition. Reference types such as `Company` are represented through `oneOf` branches in the example, while reference properties can permit both `null` and the referenced type.

References are a primary capability. The README lists relative, URL, and file references through `$ref`. This is useful for contracts divided across files or hosted at a URL. JSON handling is delegated to Json.NET, while Namotion.Reflection supplies additional .NET reflection APIs. NJsonSchema is therefore not intended to replace the serialization layer in an application. Its role is to model, validate, and generate the JSON Schema contract around that data.

NuGet Installation and First Schema Use

The README does not provide a `dotnet add package` command or another installation command. It directs users to the NuGet package pages for `NJsonSchema` and its companion packages. Use the package manager configured by the target .NET project, select the core package for schema parsing, validation, and generation, and add YAML or code-generation packages only when the application needs those features.

After adding the package, the first documented use is to generate a schema from a .NET type and inspect its serialized form. The following example is taken from the README's usage section. It creates a `Person` schema, serializes it, validates a JSON string, prints each error path and kind, and then reads the serialized schema asynchronously.

var schema = JsonSchema.FromType<Person>();
var schemaData = schema.ToJson();
var errors = schema.Validate("{...}");

foreach (var error in errors)
    Console.WriteLine(error.Path + ": " + error.Kind);

schema = await JsonSchema.FromJsonAsync(schemaData);

The validation string is abbreviated in the README as `"{...}"`, so it is not a complete JSON document and should be replaced by application data when following the tutorial. The expected output is a schema object in `schemaData` and a collection of validation errors. A generated schema should be inspected before being published, particularly when the contract controls API requests, responses, or generated client types.

Reference Resolution and Contract Boundary Risks

The most significant documented technical feature is support for schemas assembled through `$ref`, including relative, URL, and file references. This matters when an API contract is divided into reusable definitions or when related schema files are maintained separately. It also creates an operational dependency: NJsonSchema must be able to access every referenced schema through the configured location. The README does not document caching behavior, retry behavior, authentication for URL references, or a policy for failed reference resolution, so applications should not infer those guarantees.

Generation from .NET types has another boundary. The emitted schema reflects what the library derives from CLR types and recognized attributes. The README says that many attributes and annotations are supported and that `NJsonSchema.Annotations` can control serialization. It does not claim universal equivalence with every serializer configuration. Json.NET reads and writes JSON data, but the README does not provide a complete mapping table for custom converters, naming policies, or serializer-specific settings. Those details need direct verification in the target application.

Nullable value types and complex inherited models can also affect schema shape. In the documented example, `Company` receives `oneOf` branches that allow `null`, while `DateTime` receives `date-time`. A different model or serialization configuration may produce different output. Treat generated schemas as contract artifacts that require review rather than assuming that schema generation proves every runtime serializer and validator rule is identical.

C# and TypeScript Generation Trade-offs

NJsonSchema separates code generation from core parsing and validation. `NJsonSchema.CodeGeneration.CSharp` generates C# classes, while `NJsonSchema.CodeGeneration.TypeScript` generates TypeScript interfaces or classes. This is useful when one schema is the source for multiple language outputs. The schema can remain the shared contract while downstream code is regenerated, reducing manual transcription of property names and types.

The trade-off is that generated classes or interfaces are not the same as a complete HTTP client. The README describes generated C# and TypeScript code from JSON Schema. It separately describes NSwag as a Swagger API toolchain that uses NJsonSchema's generator and provides a `types2swagger` command. It does not claim that NJsonSchema itself generates HTTP request builders, authentication handlers, or endpoint operations. Projects that need those service features may find NSwag a closer fit.

For teams choosing between hand-written models and generated models, the deciding question is where the contract lives. If JSON Schema is authoritative and changes across languages, generation can reduce duplication. If the .NET class is authoritative, `FromType<T>()` keeps schema generation close to the model. The README does not document generated-file headers, naming policies, formatting options, or nullable annotation behavior for the code generators. Those details should be checked against the selected package before generated files replace maintained source files.

License, Releases, and Upgrade Work

NJsonSchema uses the MIT license. The repository contains `LICENSE.md`, and the README identifies the project as open source. License acceptance does not remove operational responsibilities. Schema artifacts, generated C# or TypeScript files, and package dependencies still need to fit the application's own review and distribution process.

The listed releases include v11.5.2 on 2025-11-05, v11.6.0 on 2026-04-08, and v11.6.1 on 2026-04-20. The last push was on 2026-10-01. The README does not provide a compatibility matrix for upgrades, migration notes, or a formal deprecation policy. An upgrade therefore requires more than changing a package version. Review changes in generated schemas, validation behavior, reference resolution, and the versions of companion packages used by the build.

Applications that use YAML or generated source should identify which package each build stage requires. A core schema workflow may need only `NJsonSchema`; adding `NJsonSchema.Yaml`, `NJsonSchema.CodeGeneration.CSharp`, or `NJsonSchema.CodeGeneration.TypeScript` adds separate capabilities and dependency considerations. The README does not specify exact transitive dependency versions, so package resolution should be checked in the target project's package metadata.

Editorial conclusion

Adopt NJsonSchema when a .NET application needs schema generation, validation, reference handling, or generated language types as part of its build process. Do not choose it solely for YAML or code generation unless the matching companion package is acceptable. Verify first that attributes, reference styles, nullable value types, and generated API shapes match the intended contract, because the library exposes separate packages for annotations, YAML, and language generators.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. RicoSuter/NJsonSchema on GitHub