Patchly 0.4.0

🩹 Patchly

The null vs "I didn't send this" problem — solved.

{ "firstName": "Mark", "age": null }

☝️ firstName → update it. age → clear it. lastName → not sent, don't touch it.

Every PATCH endpoint needs this. Nullable DTOs can't do it. Patchly can.

dotnet add package Patchly

⚡ 30-Second Overview

1. Define your patch DTO:

[PatchDocument]
public partial class CustomerPatch
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
    public int? Age { get; set; }
}

2. Use it in your endpoint:

[HttpPatch("{id}")]
public IActionResult Patch(int id, CustomerPatch patch)
{
    var customer = _repo.Get(id);

    if (patch.Provided.FirstName)
        customer.FirstName = patch.FirstName;

    if (patch.Provided.Age)
        customer.Age = patch.Age;  // could be null — that's intentional

    _repo.Save(customer);
    return Ok(customer);
}

3. Register in your web app (for OpenAPI & minimal APIs):

builder.Services.AddPatchly();

4. That's it. No middleware. No reflection. It just works.

🤔 Why Does This Exist?

Every .NET developer building PATCH endpoints hits the same wall: how do you tell the difference between "the client sent null" and "the client didn't send this field at all"?

The existing options all suck:

Patchly gives you null vs absent tracking with a clean OpenAPI schema and zero ceremony.

✅ What You Get

📊 How It Compares

📦 Installation

dotnet add package Patchly

Requirements: .NET 6+ · C# 9+ (C# 12+ for required keyword)

Patchly uses System.Text.Json, which ships in-box with .NET 6+. No additional dependencies.

🔧 How It Works Under the Hood

Patchly source-generates three things for each [PatchDocument] class:

1. 🔄 A JsonConverter that tracks which properties were present in the JSON during deserialization
2. ✅ A Provided accessor with per-property booleans (patch.Provided.FirstName)
3. 🔗 A WasProvided(string) method for generic/dynamic scenarios

When deterministic mode is enabled, Patchly also generates a State accessor and GetState(string) for explicit tri-state semantics (Omitted, Null, Value).

📡 On the Wire

The client sends plain JSON — only the fields it wants to change:

{ "firstName": "Mark", "age": null }

• firstName → updated to "Mark"
• age → explicitly set to null
• lastName → not sent, left unchanged

🖥️ In Your Endpoint

Works with controllers:

[HttpPatch("{id}")]
public IActionResult Patch(int id, CustomerPatch patch)
{
    var customer = _repo.Get(id);

    if (patch.Provided.FirstName)
        customer.FirstName = patch.FirstName;

    if (patch.Provided.Age)
        customer.Age = patch.Age;  // could be null — that's intentional

    _repo.Save(customer);
    return Ok(customer);
}

And minimal APIs:

builder.Services.AddPatchly();

// ...

app.MapPatch("/customers/{id}", (int id, CustomerPatch patch) =>
{
    var customer = repo.Get(id);

    if (patch.Provided.FirstName)
        customer.FirstName = patch.FirstName;

    if (patch.Provided.Age)
        customer.Age = patch.Age;

    repo.Save(customer);
    return Results.Ok(customer);
});

💡 The Provided accessor is IntelliSense-discoverable — no magic strings. For generic/dynamic scenarios, WasProvided(string) and ProvidedProperties are also available via the IPatchDocument interface.

📋 OpenAPI Support

Call AddPatchly() at startup to get correct OpenAPI schemas for your patch types:

builder.Services.AddPatchly();
builder.Services.AddOpenApi();

This inserts the Patchly type info resolver into the JSON serialization pipeline, giving the OpenAPI schema generator full visibility into your patch document properties:

{
  "CustomerPatch": {
    "type": "object",
    "properties": {
      "firstName": { "type": "string", "nullable": true },
      "lastName": { "type": "string", "nullable": true },
      "age": { "type": "integer", "format": "int32", "nullable": true }
    }
  }
}

NSwag, Kiota, and other generators produce a clean, idiomatic client.

Without AddPatchly(), the [JsonConverter] attribute on generated classes causes JsonSchemaExporter to produce empty schemas ({ }). This is a known .NET limitation — types with custom converters cannot describe their schema to the exporter. The converter still works for deserialization — only the schema is affected.

MVC controllers use separate JSON options. To configure the resolver for MVC:

builder.Services.Configure<Microsoft.AspNetCore.Mvc.JsonOptions>(o =>
    o.JsonSerializerOptions.TypeInfoResolverChain.Insert(0, PatchlyJsonTypeInfoResolver.Default));

Buffered-path types (init-only properties or [JsonConstructor]) produce empty OpenAPI schemas. This is the same .NET limitation — these types use a converter-based resolver path that cannot be introspected by JsonSchemaExporter.

Do not add Patchly converters directly to options.Converters when the resolver is active — this would override the resolver and produce empty schemas.

📲 Client-Side Behaviour

How the client sends partial updates depends on which client generator you use.

Kiota (recommended)

Kiota's backing store tracks which properties your code actually sets and only serializes those — including explicit nulls. Works perfectly with Patchly out of the box:

var patch = new CustomerPatch();
patch.FirstName = "Mark";
patch.Age = null;  // explicitly clear age
await client.Customers[id].PatchAsync(patch);
// Sends: { "firstName": "Mark", "age": null }
// lastName is NOT sent — Kiota knows it was never touched

NSwag

NSwag generates plain DTOs with no change tracking, so by default System.Text.Json serializes all properties. Configure your serializer to skip nulls:

var options = new JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

This covers most cases. The trade-off is you can't explicitly send null to clear a field. For that edge case, construct the request manually:

var body = new JsonObject
{
    ["firstName"] = "Mark",
    ["age"] = null
};

🏗️ Nested Patch Documents

When a property's type is itself a [PatchDocument], tracking works independently at each level:

[PatchDocument]
public partial class AddressPatch
{
    public string? Line1 { get; set; }
    public string? City { get; set; }
}

[PatchDocument]
public partial class CustomerPatch
{
    public string? FirstName { get; set; }
    public AddressPatch? Address { get; set; }
}

{ "address": { "line1": "123 Main St" } }

patch.Provided.Address       // ✅ true — address object was sent
patch.Address.Provided.Line1 // ✅ true — line1 was sent within address
patch.Address.Provided.City  // ❌ false — city was not sent
patch.Provided.FirstName     // ❌ false — not sent at all

🎯 Deterministic Semantics Mode

Patchly's default behavior already lets you distinguish omitted fields using Provided/WasProvided. Deterministic mode adds an explicit tri-state API for clearer handler logic.

[PatchDocument(SemanticsMode = PatchSemanticsMode.DeterministicV1)]
public partial class CustomerPatch
{
    public string? FirstName { get; set; }
    public List<string>? Tags { get; set; }
}

switch (patch.State.FirstName)
{
    case PatchValueState.Omitted: break;               // leave unchanged
    case PatchValueState.Null: customer.FirstName = null; break; // clear
    case PatchValueState.Value: customer.FirstName = patch.FirstName; break; // set
}

Deterministic V1 collection behavior is replace-based:

• Omitted collection field → no change
• null → clear
• [] or non-empty array → replace with payload value

🗺️ Patch Mapping

For projects with many patch endpoints, Patchly provides a structured mapping pattern that centralizes patch-to-entity logic with DI integration.

1. Define a map:

public class CustomerPatchMap : PatchMap<CustomerPatch, Customer>
{
    public override void Apply(CustomerPatch patch, Customer target)
    {
        if (patch.Provided.FirstName) target.GivenName = patch.FirstName;
        if (patch.Provided.Age)       target.Age = patch.Age ?? 0;
    }
}

2. Register all maps at startup:

builder.Services.AddPatchlyMaps();

3. Inject IPatchApplier in your endpoints:

[HttpPatch("{id}")]
public IActionResult Patch(int id, CustomerPatch patch, [FromServices] IPatchApplier patchApplier)
{
    var customer = _repo.Get(id);
    patchApplier.Apply(patch, customer);
    _repo.Save(customer);
    return Ok(customer);
}

The source generator discovers all PatchMap<,> subclasses and generates:

• PatchApplier — the IPatchApplier implementation that dispatches to the correct map
• AddPatchlyMaps() — registers all maps and the applier with DI

Maps can take constructor dependencies (loggers, services, etc.) since they're resolved from the container. One map per (TPatch, TTarget) pair — the generator emits a compile error (PATCH020) if duplicates are found.

🚀 Native AOT Support

Patchly works with Native AOT (PublishAot=true) on .NET 8+.

For web apps, AddPatchly() handles everything:

builder.Services.AddPatchly();

This inserts PatchlyJsonTypeInfoResolver at position 0 in the minimal API JSON options resolver chain.

For non-web apps or manual configuration, add the resolver to your options before your JsonSerializerContext:

var options = new JsonSerializerOptions
{
    TypeInfoResolver = JsonTypeInfoResolver.Combine(
        PatchlyJsonTypeInfoResolver.Default,
        AppJsonContext.Default)
};

Important: The Patchly resolver handles [PatchDocument] types only. Property-level types (e.g., string, int?, List<string>) must be covered by your JsonSerializerContext. Non-AOT apps don't need any of this — the existing [JsonConverter] attribute continues to work automatically.

🎛️ Supported JSON Attributes

Patchly respects standard System.Text.Json attributes on your properties:

The generated converter also works with all JsonSerializerOptions configuration: naming policies, PropertyNameCaseInsensitive, DefaultIgnoreCondition, and JsonSerializerDefaults.Web.

init-only properties and [JsonConstructor] constructors can be mixed freely. A class can have a [JsonConstructor] without a parameterless constructor. Records remain unsupported (PATCH003).

🔗 IPatchDocument Interface

All generated patch documents implement IPatchDocument, which exposes:

• bool WasProvided(string propertyName) — check by C# property name (case-insensitive)
• PatchValueState GetState(string propertyName) — tri-state semantics (Omitted, Null, Value)
• IReadOnlySet<string> ProvidedProperties — the set of C# property names that were present in the JSON

Use IPatchDocument for generic constraints:

public void ApplyPatch<T>(T patch, Action<T> apply) where T : IPatchDocument
{
    if (patch.ProvidedProperties.Any())
        apply(patch);
}

🛡️ Diagnostics

The source generator catches problems at compile time so you don't have to debug them at runtime. See Diagnostics Reference for detailed explanations and rationale.

Errors

Warnings

Info