Purview.Results.ZodSharp.AspNetCore 1.0.0-prerelease.2

Purview.Results.ZodSharp.AspNetCore

Renders a result failure that carries ZodSharp validation errors as an ASP.NET Core HttpValidationProblemDetails response, produced by the same mapper the ZodSharp exception handler uses — so a validation failure carried by a result and the same failure thrown as a ZodException produce identical responses.

Installation

dotnet add package Purview.Results.ZodSharp.AspNetCore

Quick start

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddZodSharpProblemDetails();
builder.Services.AddResultsHttp();

// Every validation-carrying failure becomes one validation problem, except the codes and categories that a
// rule answers with something else.
builder.Services.AddResultsZodSharpHttp(options => options
    .MapCode("tenant_not_found", StatusCodes.Status404NotFound)
    .MapCategory("invalid_value", StatusCodes.Status422UnprocessableEntity)
);

var app = builder.Build();

app.MapPost("/reconcile", (ReconciliationRequest request) => Reconcile(request)).WithResultsHttp();

AddResultsZodSharpHttp registers the mapping as a failure mapper, so a mapping the host registered for a specific error case always wins, a mapping registered for the error type wins, and a host failure mapper registered before it wins too.

Answering by validation error code or category

A rule applies when any of the failure's errors carries its code or category, so a registered code rule is always reachable whatever else the schema reported. Matching walks the code rules first, then the category rules, each in registration order, and finally the default validation problem — a code is narrower than a category, so it wins however the two were registered. A factory that wants stricter semantics returns null to decline the failure, and matching continues:

options
    // A code rule that only answers a failure whose every error is that code.
    .MapCode("tenant_not_found", (errors, context) =>
        errors.All(error => error.Code == "tenant_not_found")
            ? TypedResults.NotFound()
            : null)
    // A category rule that answers the failures the code rule declined.
    .MapCategory("invalid_value", StatusCodes.Status422UnprocessableEntity);

A factory receives the failure's full error set, so a rule never hides the other problems the caller has to fix, and the int statusCode overloads still render every error as an HttpValidationProblemDetails. A code or category registered twice with different behaviour is rejected at configuration time.

API

The status code resolved by ZodProblemDetailsOptions.StatusCodeSelector wins; statusCode (or defaultStatusCode, or a rule's statusCode) is only used when the resolved error type does not define one. The trace identifier is included when ResultsHttpOptions.IncludeTraceId is true (the default).

Examples

src/examples/Examples.AspNetCore.Zod is a runnable minimal-API example where a TenantInputInvalid failure carrying ZodSharp errors becomes a 400 validation problem, while the host's own TenantAlreadyExists mapping still returns 409.

dotnet run --project src/examples/Examples.AspNetCore.Zod --urls http://localhost:5216

The repository README lists the Basic, ZodSharp and ASP.NET Core examples too.

Related packages

Agent skills

This package ships the purview-results-zodsharp-problems agent skill under .agents/. Repositories that import Purview.BuildSdk get it mirrored into their own .agents/ folder on the next restore or build, so AI agents working there receive the guidance automatically.

License

MIT — see LICENSE.md.