Purview.ZodSharp.AspNetCore.OpenApi 3.0.0-prerelease.2

Purview.ZodSharp.AspNetCore.OpenApi

OpenAPI integration for Purview.ZodSharp: ASP.NET Core 11 OpenAPI transformers that make the document describe exactly what ZodSharp enforces — constraints, formats, unions, maps and the validation error contract — with one line of setup.

net11.0 only: ASP.NET Core 11 builds documents on the Microsoft.OpenApi 3.x object model.

Installation

dotnet add package Purview.ZodSharp.AspNetCore.OpenApi

Usage

using Microsoft.AspNetCore.OpenApi; // AddZodSharp(this OpenApiOptions) lives here; it is not an implicit using

builder.Services.AddZodSharp(options => options.ScanAssemblies.Add(typeof(Program).Assembly));
builder.Services.AddOpenApi(options => options.AddZodSharp());

var app = builder.Build();
app.MapOpenApi();

Options:

builder.Services.AddOpenApi(options => options.AddZodSharp(zod =>
{
    zod.EmitVendorExtensions = true;       // x-zod-* for rules without a JSON Schema keyword
    zod.DiscriminatedUnionsAsOneOf = true; // oneOf + discriminator for polymorphic types
    zod.DescribeValidationProblems = true; // 400 ZodValidationProblemDetails on validated endpoints
}));

All three default to true (ZodOpenApiOptions). Trimmed and Native AOT apps can register their validators with the generated AddZodSharp{Assembly}Schemas() instead of assembly scanning.

What it describes

The source of truth is ZodSharp's own JSON Schema for a type: the generated BuildJsonSchema() of a [ZodSchema] type, or a runtime schema registered in IZodSchemaFactory. A type ZodSharp does not know is left exactly as ASP.NET Core produced it.

Members ZodSharp rejects when absent (non-nullable references, [Required], [RequiredZod]) are listed in required, and nullability uses type: [x, "null"]. When a DataAnnotation the platform mapped disagrees with ZodSharp, ZodSharp's value is written — it is the validator that enforces the request — and in Development the override is logged at Debug.

Polymorphic types ([JsonPolymorphic]) are described with oneOf and the platform's discriminator. A C# union keeps the platform's anyOf; ZodSharp only constrains each case.

Validation problem responses

Every operation that binds a ZodSharp-validated parameter (a body, an [AsParameters] container, or a union of ZodSharp cases) lists 400 — and 422 when an ErrorType registered in the ErrorTypeRegistry uses it — as application/problem+json with the shared ZodValidationProblemDetails and ZodValidationIssue component schemas. A 400 the endpoint already declares with ProducesValidationProblem() is merged into rather than duplicated.

Documentation

• Homepage
• Documentation

License

MIT — see the package metadata in Purview.ZodSharp.AspNetCore.OpenApi on NuGet.