Purview.Results.ZodSharp.AspNetCore 1.0.0.1

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, categories and origins
// 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, category or origin

The three axes are the identity a ValidationError carries: code is the specific rule that failed, category is a broad grouping many codes share, and origin is the structured origin a rule owns ("value_object" for a type-level rule, "array" for a collection rule). Use MapOrigin when the answer is keyed by the kind of rule rather than one code — for example to render every "value_object" failure as 422.

A rule applies when any of the failure's errors carries its code, category or origin, so a registered rule is always reachable whatever else the schema reported. Matching walks the code rules first, then the category rules, then the origin rules, each in registration order, and finally the default validation problem — a code is narrower than a category, which is narrower than an origin, so a code wins however the rules 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)
    // An origin rule: every type-level rule failure, whatever its code.
    .MapOrigin("value_object", 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, category or origin 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/src/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/src/Examples.AspNetCore.Zod --urls http://localhost:5216

The repository README lists the Basic, ZodSharp and ASP.NET Core examples too. The value-objects composition example shows a type-level [ZodRule] whose Origin = "value_object" is answered by MapOrigin.

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.