Getting Started

Getting Started

Install

dotnet add package Purview.ZodSharp

Add the integration packages you need:

# System.Text.Json integration + JSON Schema import
dotnet add package Purview.ZodSharp.SystemTextJson

# Newtonsoft.Json integration + JSON Schema import
dotnet add package Purview.ZodSharp.NewtonsoftJson

# ASP.NET Core ProblemDetails integration
dotnet add package Purview.ZodSharp.AspNetCore

• Purview.ZodSharp — core library, source generator, and JSON Schema export.
• Purview.ZodSharp.SystemTextJson — System.Text.Json deserialize-and-validate, validating converters, and JSON Schema import.
• Purview.ZodSharp.NewtonsoftJson — Newtonsoft.Json deserialize-and-validate, validating converters, and JSON Schema import.
• Purview.ZodSharp.AspNetCore — failed validation results converted to standard ProblemDetails / HttpValidationProblemDetails payloads.

Tip

JSON Schema import (Z.FromJsonSchema) is provided by whichever JSON integration package you reference, so pick one. Export (Z.ToJsonSchema) lives in the core package.

First schema

using ZodSharp;

var nameSchema = Z.String().Min(3).Max(50);
var result = nameSchema.Validate("John");

if (result.IsSuccess)
    Console.WriteLine($"Valid name: {result.Value}");

Validate, SafeParse, and Parse

• Validate returns a ValidationResult<T> — no exceptions.
• SafeParse is an alias of Validate.
• Parse throws ZodException on failure.

var value = nameSchema.Parse("AB"); // throws ZodException

var result = nameSchema.SafeParse("AB"); // non-throwing
if (!result.IsSuccess)
{
    foreach (var error in result.Errors)
        Console.WriteLine($"  - {string.Join(".", error.Path)}: {error.Message}");
}

Object validation

var userSchema = Z.Object()
    .Field("name", Z.String().Min(1))
    .Field("age", Z.Number().Min(0).Max(120).Int())
    .Field("email", Z.String().Email())
    .Build();

var userData = new Dictionary<string, object?>
{
    { "name", "John Doe" },
    { "age", 30.0 },
    { "email", "[email protected]" }
};

var result = userSchema.Validate(userData);

Source-generated validators

Mark a class, struct, or record with [ZodSchema] and a zero-allocation static validator is generated at compile time:

using System.ComponentModel.DataAnnotations;
using ZodSharp;

[ZodSchema]
public class User
{
    [Required]
    [StringLength(50, MinimumLength = 3)]
    public string Name { get; set; } = string.Empty;

    [Range(0, 120)]
    public int Age { get; set; }

    [EmailAddress]
    public string? Email { get; set; }
}

var result = UserSchema.Validate(user);
var validated = UserSchema.Parse(user); // throws on failure

See the Source Generator and Source Generator DataAnnotations pages for the full feature set.

JSON integration

// System.Text.Json or Newtonsoft.Json
var json = """{ "name": "John", "age": 30 }""";
var result = userSchema.DeserializeAndValidate(json);

// JSON Schema export (core)
var jsonSchema = Z.ToJsonSchema(userSchema, new ToJsonSchemaOptions { Title = "User" });

// JSON Schema import (requires an integration package)
var imported = Z.FromJsonSchema(jsonSchemaString);

See System.Text.Json Integration, Newtonsoft.Json Integration, JSON Schema Export, and JSON Schema Import.

Next pages

• Core Concepts
• Fluent Schema API
• Source Generator
• Dependency Injection
• Cross-Platform Interop
• Performance