Purview.ZodSharp.SystemTextJson 3.0.0-prerelease.2

Purview.ZodSharp.SystemTextJson

System.Text.Json integration for Purview.ZodSharp . Deserialize-and-validate JSON in a single pass, create validating JsonConverter<T> instances, and import JSON Schema definitions (Z.FromJsonSchema).

Installation

dotnet add package Purview.ZodSharp.SystemTextJson

Deserialize and validate

using ZodSharp;

var userSchema = Z.Object()
    .Field("name", Z.String().Min(3))
    .Field("age", Z.Number().Min(0).Int())
    .Build();

var json = """{ "name": "John", "age": 30 }""";

var result = userSchema.DeserializeAndValidate(json);
if (result.IsSuccess)
    Console.WriteLine($"Valid: {result.Value}");

Async stream overload:

await using var stream = File.OpenRead("user.json");
var result = await userSchema.DeserializeAndValidateAsync(stream);

In a trimmed, Native AOT or Blazor WebAssembly app, pass the contract from a source-generated JsonSerializerContext (the JsonTypeInfo<T> overloads); the overloads above resolve it reflectively and are annotated so the build warns.

var result = schema.DeserializeAndValidate(json, AppJsonContext.Default.User);

Service-aware rules (an async uniqueness check that resolves a repository) run when a generated validator is given the caller's services:

var result = await new UserSchemaValidator().DeserializeAndValidateAsync(
    stream, AppJsonContext.Default.User, services, cancellationToken);
var written = await new UserSchemaValidator().ValidateAndSerializeAsync(
    user, output, AppJsonContext.Default.User, services, cancellationToken);

For HttpClient request and response bodies, see Purview.ZodSharp.Http, which builds on these.

Validating converter

var converter = userSchema.CreateValidatingConverter();
var options = new JsonSerializerOptions { Converters = { converter } };
var value = JsonSerializer.Deserialize<User>(json, options);

Errors

A failure to read the JSON (malformed text, a null document, a value the serializer cannot convert, or a NotSupportedException/InvalidOperationException thrown while deserializing) is reported as one error with code invalid_json (SystemTextJsonExtensions.InvalidJsonCode), category invalid_type and the fixed message "The JSON value could not be converted to {expected}.". The serializer's path becomes the error's FullPath ($.items[1].age becomes items[1].age) and its line and byte position become the line and position parameters. The serializer's own message is never surfaced, because it names CLR types and can quote the input.

The validating converter throws ZodJsonValidationException (namespace ZodSharp.Json, a JsonException) carrying the schema's full Errors, located under the converter's JSON path; its message still starts with "Validation failed: ", so existing catch (JsonException) blocks keep working. DeserializeAndValidate unwraps it into the result.

UTC DateTimeOffset contract

The default PreserveOffset schema is exact and needs no converter. When the generated JSON Schema uses DateTimeOffsetSerialization.Utc, add the matching converter so the serializer writes UTC and rejects a value without an explicit Z/zero offset (or with a non-zero offset) on read:

using ZodSharp.Json.Serialization.SystemTextJson;

var options = new JsonSerializerOptions
{
    Converters = { new UtcDateTimeOffsetConverter() },
};

PreserveOffsetDateTimeOffsetConverter is available to opt a type or property back out of a project-wide UTC converter. See JSON Schema Export.

Import from JSON Schema

using ZodSharp;
using ZodSharp.JsonSchema.SystemTextJson;

var schema = Z.FromJsonSchema(jsonSchemaString);
var result = schema.Validate(data);

This lets you share schemas defined in TypeScript/Zod with your .NET backend. (Export via Z.ToJsonSchema lives in the core package.)

Documentation

• Homepage
• Documentation

License

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