NoJsonSchema 1.2.0

NoJsonSchema

Generate C# types and a zero-dependency UTF-8 JSON parser/emitter from JSON Schema.

NoJsonSchema takes a JSON Schema Draft 2020-12, Draft-07, or OpenAPI 3.x document and generates C# models plus UTF-8 JSON serialization code at build time.

The generated output consists of:

1. POCO types — class / record / readonly record struct, your choice per type.
2. A per-type Formatter — UTF-8 parser and emitter built on ref byte + Unsafe.Add.
3. A namespace-wide Serializer — generic Deserialize<T> / Serialize<T> with Cache<T> dispatch (one resolve per CLR generic instantiation, then a single static-field load).

JSON Schema  ─►  NoJsonSchema  ─►  C# types + UTF-8 JSON IO  ─►  your app
                  (build-time)        (BCL-only, AOT-safe)

Zero runtime dependencies

The generated .cs files reference nothing except the BCL — no System.Text.Json, no Newtonsoft.Json, no reflection, no third-party packages of any kind. Just System, System.Buffers, System.IO, System.Runtime.CompilerServices.

That means:

• Native AOT works without reflection roots or rd.xml entries.
• Unity / IL2CPP can use the generated code without depending on System.Text.Json, Newtonsoft.Json, or JsonUtility.
• Trimming (PublishTrimmed=true) is safe because the generator doesn't emit anything that survives trim analysis as un-rooted reflection.

The Core library itself (NoJsonSchema.dll) depends on System.Text.Json — but only for reading the schema document at generator time. None of that touches your shipped binary.

Why

NoJsonSchema is for schema-first projects: cases where the JSON contract is shared, published, or generated outside your C# codebase, and your C# models need to follow it.

Typical cases:

• A public JSON Schema or OpenAPI document exists, but there is no C# SDK for it.
• A protocol is defined from a source of truth such as TypeSpec or a shared API specification.
• Your target cares about zero runtime dependencies: Native AOT, Unity / IL2CPP, or trimmed apps.

If your application owns the C# types and only needs a schema as an output, a code-first workflow is usually simpler.

The generated parser/emitter is also built for hot paths:

(Benchmark: Apple M4 / .NET 10, ShortRun. See samples/Bench/.)

API at a glance

To get a feel for the generated API, start with a schema like this (user.json):

{
  "$defs": {
    "Address": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "zip":  { "type": "string" }
      },
      "required": ["city", "zip"]
    },
    "User": {
      "type": "object",
      "properties": {
        "id":      { "type": "integer", "format": "int32" },
        "name":    { "type": "string" },
        "email":   { "type": "string" },
        "joined":  { "type": "string", "format": "date" },
        "address": { "$ref": "#/$defs/Address" }
      },
      "required": ["id", "name"]
    }
  }
}

Generate it with either the source generator (AdditionalFiles, shown below) or the CLI (nojsonschema generate -i user.json -o ./Generated -n MyApp.Models).

NoJsonSchema emits User.g.cs, Address.g.cs, Formatters/UserFormatter.g.cs, Formatters/AddressFormatter.g.cs, and a namespace-wide MyAppModelsSerializer.g.cs. You use it like this:

using MyApp.Models;

// The namespace-wide Serializer is the entry point.
var user = MyAppModelsSerializer.Deserialize<User>(utf8Bytes);
var bytes = MyAppModelsSerializer.SerializeToUtf8Bytes(user);

// IBufferWriter<byte> overload too (zero extra copy).
MyAppModelsSerializer.Serialize(myBufferWriter, user);

The CLI / source generator stamps a static {Namespace}Serializer class into the same namespace as the POCOs. Use that — the per-type XxxFormatter is internal-by-design (no public surface to lock in).

Installation

Choose one of three workflows:

• Use the source generator when schemas should be compiled into your project automatically.
• Use the CLI when you want to vendor generated files or generate many schemas at once.
• Use the library API when you are building custom tooling.

Source generator

Use the source generator when you want NoJsonSchema to generate the API automatically during your build.

dotnet add package NoJsonSchema
dotnet add package NoJsonSchema.SourceGenerator

Add your schema to the project file as an AdditionalFiles item:

<ItemGroup>
  <AdditionalFiles Include="schemas/my-schema.json">
    <NoJsonSchemaNamespace>MyApp.Models</NoJsonSchemaNamespace>
  </AdditionalFiles>
</ItemGroup>

On the next build, the generated types and namespace-wide serializer appear under that namespace.

For the CLI or library workflows, see the sections below.

Standalone CLI (good for vendored / bulk generation)

dotnet tool install -g NoJsonSchema.Cli

nojsonschema generate -i schema.json -o ./Generated -n MyApp.Models

The CLI accepts file paths or http(s) URLs — point it at a remote schema directly:

nojsonschema generate \
  -i https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/main/debugAdapterProtocol.json \
  -o ./Dap -n Dap

Usage: generate [options...] [-h|--help] [--version]

Generate C# code from a JSON Schema.

Options:
  -i, --input <string>                Path or http(s) URL of the JSON Schema. [Required]
  -o, --output <string>               Directory to write generated .cs files into. [Required]
  -n, --namespace <string>            Namespace for generated types. [Default: @"Generated"]
  --root-type <string?>               Optional root type name override. [Default: null]
  --type-style <TypeStyle>            Type style for objects (Class | Record | ReadonlyRecordStruct). [Default: Class]
  --allof-strategy <AllOfStrategy>    How to represent allOf composition (Inherit | Flatten). [Default: Inherit]
  --strict-extra                      Treat unknown JSON properties as errors.
  --value-object <string[]?>          Comma-separated list of $defs entries to emit as readonly record struct (primary-ctor) value objects. [Default: null]
  --use-required                      Emit the C# 11 'required' modifier on non-nullable required properties (otherwise '= null!' is used to suppress CS8618).
  --include-type <string[]?>          Comma-separated whitelist of $defs / components.schemas entries to generate (transitive deps included automatically). Default is everything. [Default: null]

Library (custom tooling, MSBuild target, Roslyn integration)

dotnet add package NoJsonSchema

var pipeline = new NoJsonSchema.Core.GeneratorPipeline();
var result = pipeline.Generate(File.ReadAllText("schema.json"), new GenerationOptions
{
    Namespace = "MyApp.Models",
});
foreach (var f in result.Files)
    File.WriteAllText(Path.Combine("./Generated", f.FileName), f.SourceText);

Configuration

All knobs are surfaced through three equivalent channels — MSBuild metadata on the AdditionalFiles entry (source generator), CLI flags (nojsonschema), and GenerationOptions properties (library).

Per-type metadata example

<AdditionalFiles Include="schemas/dap.json">
  <NoJsonSchemaNamespace>Dap</NoJsonSchemaNamespace>
  <NoJsonSchemaValueObjects>Checksum;Source</NoJsonSchemaValueObjects>
  <NoJsonSchemaIncludeTypes>InitializeRequest;StoppedEvent;StackTraceResponse</NoJsonSchemaIncludeTypes>
</AdditionalFiles>

CLI reference

The nojsonschema tool has two subcommands. Both accept either a local file path or an http(s) URL for --input.

nojsonschema generate

Generate C# types + UTF-8 parser/emitter from a schema.

nojsonschema generate -i <schema> -o <out-dir> [options...]

Examples

# Vanilla: local schema → ./Generated under "MyApp.Models"
nojsonschema generate -i schema.json -o Generated -n MyApp.Models

# Remote schema with --include-type whitelist (trim 192-def DAP to 13 files)
nojsonschema generate \
  -i https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/main/debugAdapterProtocol.json \
  -o ./Dap -n Dap \
  --include-type Capabilities,InitializeRequest,StoppedEvent

# Mix: most types as classes, but Checksum/Source as readonly record structs
nojsonschema generate -i dap.json -o ./Dap -n Dap \
  --value-object Checksum,Source \
  --use-required --strict-extra

nojsonschema lint

Parse a schema and print a summary; reports structural problems without generating code.

nojsonschema lint -i <schema>

Output:

$ nojsonschema lint -i https://json.schemastore.org/package.json
file:        https://json.schemastore.org/package.json
$schema:     http://json-schema.org/draft-07/schema#
$id:         https://json.schemastore.org/package.json
root kind:   Object
definitions: 29
properties:  61 (on root)

Exit codes: 0 on success, 1 on any failure (network / IO / parse / schema validation).

Supported schema subset

NoJsonSchema intentionally supports the schema features most common in SDK-style models:

format strings the IR doesn't recognise fall back to the base type (e.g. unknown string format → string).

Generated output

The generator emits one file per type, one formatter per type, and one public serializer class per namespace:

Generated/
  User.g.cs                          ← POCO
  Address.g.cs
  Formatters/
    UserFormatter.g.cs               ← per-type UTF-8 parser/emitter (internal static class)
    AddressFormatter.g.cs
  MyAppModelsSerializer.g.cs         ← public entry point: Cache<T> + Deserialize<T> / Serialize<T>
  _IsExternalInitShim.g.cs           ← `init` setter polyfill for netstandard
  _SetsRequiredMembersShim.g.cs      ← only when --use-required and TFM < net7

Hot-path details (commentary lives in Emit/SerializerTemplate.cs):

• Tokenizer / Writer are ref structs with a ref byte head field on net7+ (Span<byte> + slicing on netstandard 2.1). Unsafe.Add / Unsafe.CopyBlockUnaligned instead of span-indexed access — per-byte bounds checks are elided on the hot path.
• Vectorized scanning (net8+): whitespace skipping uses IndexOfAnyExcept and the string-terminal search (" / \ / control char) uses a cached SearchValues<byte> — both AVX2/AVX-512-accelerated in the BCL. A scalar single-byte fast-exit guards the common case so compact input — and the redundant skips after a peek — pay no call cost.
• WriteString fast path: bulk Encoding.UTF8.GetBytes(chars, span) for ASCII-safe runs, escape only on demand.
• Property dispatch is bucketed by UTF-8 byte length — switch (__name.Length) then SequenceEqual within bucket. Mismatches short-circuit fast.
• Generic dispatch routes through a per-T static Cache<T> with two delegate fields. The typeof(T) == resolution runs once per CLR generic instantiation; subsequent calls are a single static-field load + one delegate invocation. The Cache + delegate types are private-nested in the Serializer, so multiple generated namespaces in the same assembly don't collide.
• Throw* helpers are [DoesNotReturn] [MethodImpl(NoInlining)] so callers stay inlineable.

Compatibility

License

MIT