Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 155 additions & 0 deletions .config/purview-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
# The purview.dev catalogue record for this project (ADR 0013 in purview-dev/purview-dev).
# The site reads this file from the default branch of this repository, so the record
# changes in the same pull request as the thing it describes.
#
# `$schema` is an editor hint and nothing more: the enforcing validation is the site's
# loader, which `just check-projects` runs there.
$schema: https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts

id: zodsharp
name: ZodSharp
shortDescription: Zero-allocation schema validation for C# — a Zod port.
description: >-
A high-performance schema validation library for C#, ported from
TypeScript Zod by way of the guinhx/ZodSharp C# port. Struct-based rules,
a fluent API, JSON Schema export and import, source-generated validators,
and zero-allocation validation on every valid input path. Integrates with
System.Text.Json, Newtonsoft.Json, and ASP.NET Core ProblemDetails.
origin: >-
Schema validation was repeatedly needed at application boundaries, but existing approaches
did not combine a fluent Zod-style model with predictable, allocation-conscious execution.
useWhen: >-
You want composable C# schemas, compile-time validator generation, or JSON Schema interop with
tight control over validation behaviour and allocations.
avoidWhen: >-
Data annotations or an existing validation library already cover your requirements, or Zod-style
schemas would add an unnecessary second validation model.
repository: purview-dev/zodsharp
category: validation
status: stable
featured: true
order: 30
docs:
source: github-path
path: docs/wiki
rootPage: Getting-Started.md
exclude:
- _Sidebar.md
- Home.md
- index.md
# Two views of the same documentation (ADR 0009): the published release a
# reader can install today (`live`, the canonical /docs/zodsharp/ URLs) and
# the line that has not shipped yet (`prerelease`, /docs/zodsharp/prerelease/).
# `main` is ahead of the latest release, so the pinned tag is the honest
# source for the live docs. Promotion is automatic: the prerelease channel
# stops being published as soon as a stable release catches up with the
# prerelease line, and returns with the next prerelease.
channels:
live:
ref: latest-stable
prerelease:
ref: default
# The documentation was reorganised into topic folders, which makes each page's folder part of its published URL.
# Every page that moved keeps its old flat URL working: the site writes a meta-refresh redirect for each pair once
# the default channel publishes that page's new address (and only while the old slug is no longer a page), so these
# entries stay dormant while `live` still reads a tag that predates the move and activate per page at promotion.
redirects:
core-concepts: concepts/core-concepts
composition-and-transforms: concepts/composition-and-transforms
string-validation: schemas/string-validation
number-validation: schemas/number-validation
object-validation: schemas/object-validation
arrays-and-other-schemas: schemas/arrays-and-other-schemas
unions-and-discriminated-unions: schemas/unions-and-discriminated-unions
validation-rules-reference: schemas/validation-rules-reference
custom-rules: schemas/custom-rules
value-objects-integration: schemas/value-objects-integration
compiled-validators-and-caching: schemas/compiled-validators-and-caching
source-generator: generator/source-generator
source-generator-dataannotations: generator/source-generator-dataannotations
source-generator-diagnostics: generator/source-generator-diagnostics
jsonschema-export: serialization/jsonschema-export
jsonschema-import: serialization/jsonschema-import
systemtextjson-integration: serialization/systemtextjson-integration
newtonsoftjson-integration: serialization/newtonsoftjson-integration
microsoft-extensions-validation: hosting/microsoft-extensions-validation
openapi-integration: hosting/openapi-integration
blazor-integration: hosting/blazor-integration
http-integration: hosting/http-integration
dependency-injection: hosting/dependency-injection
localization: hosting/localization
guarantees-and-limitations: quality/guarantees-and-limitations
performance: quality/performance
trimming-and-aot: quality/trimming-and-aot
cross-platform-interop: quality/cross-platform-interop
contributing: development/contributing
release-flow: development/release-flow
targetFrameworks:
- net8.0
- net9.0
- net10.0
- net11.0
packages:
- id: Purview.ZodSharp
description: Core validation library and source generator.
primary: true
- id: Purview.ZodSharp.SystemTextJson
description: System.Text.Json integration and JSON Schema import.
- id: Purview.ZodSharp.NewtonsoftJson
description: Newtonsoft.Json integration and JSON Schema import.
- id: Purview.ZodSharp.AspNetCore
description: ASP.NET Core ProblemDetails integration.
# Published only as prereleases today, but published all the same: the package
# listing must show every package a project ships, not only the ones that have
# reached a stable version.
- id: Purview.ZodSharp.Http
description: HttpClient integration — validates request and response bodies and maps validation problems back to ZodSharp errors.
- id: Purview.ZodSharp.Blazor
description: Blazor EditForm validation on Server, WebAssembly and Auto render modes.
- id: Purview.ZodSharp.AspNetCore.OpenApi
description: OpenAPI transformers for the constraints, formats and error contract ZodSharp enforces.
- id: Purview.ZodSharp.Extensions.Validation
description: Microsoft.Extensions.Validation resolver so minimal APIs and Blazor validate with ZodSharp.
related:
- value-objects
acknowledgments:
- name: Zod
url: https://github.com/colinhacks/zod
description: The original JavaScript/TypeScript schema validation library.
- name: ZodSharp (guinhx)
url: https://github.com/guinhx/ZodSharp
description: The C# port of Zod, and the fork this project is based on.
useCases:
- audience: developer
title: Validate input without exceptions or allocations
scenario: >-
You need to validate values at an application boundary and prefer a result you can inspect
over exception-driven control flow.
code: |
var nameSchema = Z.String().Min(3).Max(50);
var result = nameSchema.Validate("John");

if (result.IsSuccess)
Console.WriteLine($"Valid name: {result.Value}");
language: csharp
outcome: >-
Validate/SafeParse return a ValidationResult<T> with no exceptions, while Parse still throws
ZodException when you want that behaviour.
evidence: >-
Validation is zero-allocation on every valid input path, so the performance claim is a
property of the code rather than an aspiration.
docsPage: fluent-schema-api
- audience: team-lead
title: Return standard ProblemDetails for invalid requests
scenario: >-
You want failed validation in ASP.NET Core to surface as standard ProblemDetails payloads
rather than a bespoke error shape that clients must learn.
code: |
dotnet add package Purview.ZodSharp.AspNetCore
language: bash
outcome: >-
The AspNetCore adapter converts failed validation results into the standard ProblemDetails /
HttpValidationProblemDetails payloads.
evidence: >-
One adapter package, and API consumers keep the error contract they already expect.
docsPage: aspnetcore-integration
Loading