{
  "defaultVersion": "1",
  "sourceRevision": "34222bb7277ce1a771ae4412d572b56f5eb98237",
  "versions": [
    {
      "name": "1",
      "label": "1",
      "path": "/",
      "isDefault": true
    }
  ],
  "documents": [
    {
      "id": "validation/index",
      "title": "Validation",
      "description": "Source-generated validation with fluent or attribute rules and first-class application integrations.",
      "module": "validation",
      "version": "1",
      "path": "/validation/",
      "url": "https://valiant.staticnorth.dev/validation/",
      "markdownUrl": "/markdown/validation.md",
      "content": "---\ntitle: \"Validation\"\ndescription: \"Source-generated validation with fluent or attribute rules and first-class application integrations.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Validation you can step through\n\nValiant Validation generates direct validators from compact, strongly typed rules. Author rules with fluent C#, model attributes, native branches, nested contexts, and reusable validators; then connect them to ASP.NET Core, OpenAPI, MediatR, or source-generated Mediator.\n\n```csharp\nusing StaticNorth.Valiant.Validation;\n\n[ValiantValidator]\npublic sealed partial class CreateUserValidator : ValidatorDefinition<CreateUser>\n{\n    public override void Configure(ValidationContext<CreateUser> context)\n    {\n        context.Property(user => user.Name)\n            .Required()\n            .MaxLength(64);\n\n        context.Property(user => user.Age)\n            .GreaterThanOrEqualTo(18);\n    }\n}\n```\n\n## One rule model, several hosts\n\n| Layer | Integration |\n| --- | --- |\n| Domain/application | Inject `IValidator<T>` and call sync or async validation APIs |\n| Minimal APIs | Add `.WithValiantValidation()` to a route |\n| MVC | Register Valiant model validation globally |\n| OpenAPI | Project generated rule metadata into schema constraints and `x-valiant-rules` |\n| Messaging | Add a MediatR or Mediator pipeline behavior |\n\nValidation results preserve property paths, codes, messages, and severity. Errors invalidate the result; warnings and information remain available without making it invalid.\n\n## Documentation map\n\n- [Quick start](https://valiant.staticnorth.dev/validation/quick-start)\n- [Runnable samples](https://valiant.staticnorth.dev/validation/samples)\n- [Authoring rules](https://valiant.staticnorth.dev/validation/guides/authoring-rules)\n- [Composition and control flow](https://valiant.staticnorth.dev/validation/guides/composition-control-flow)\n- [ASP.NET Core and OpenAPI](https://valiant.staticnorth.dev/validation/guides/aspnetcore-openapi)\n- [Mediator pipelines](https://valiant.staticnorth.dev/validation/guides/mediator-pipelines)\n- [Validation check catalog](https://valiant.staticnorth.dev/validation/reference/validation-checks)\n- [Runtime and generation](https://valiant.staticnorth.dev/validation/reference/runtime-generation)\n- [Package guide](https://valiant.staticnorth.dev/validation/reference/packages)\n\nThe [sample catalog](https://valiant.staticnorth.dev/validation/samples) covers every selectable core and ASP.NET\nCore scenario. The same behaviors are covered by sample-focused tests,\nincluding `WebApplicationFactory` tests for every web sample.\n"
    },
    {
      "id": "validation/quick-start",
      "title": "Quick start",
      "description": "Install StaticNorth.Valiant.Validation, generate a validator, and consume its result.",
      "module": "validation",
      "version": "1",
      "path": "/validation/quick-start",
      "url": "https://valiant.staticnorth.dev/validation/quick-start",
      "markdownUrl": "/markdown/validation/quick-start.md",
      "content": "---\ntitle: \"Quick start\"\ndescription: \"Install StaticNorth.Valiant.Validation, generate a validator, and consume its result.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/quick-start\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Quick start\n\n## 1. Install\n\n```bash\ndotnet add package StaticNorth.Valiant.Validation\n```\n\nFor an application integration, install the most specific package instead. For example, `StaticNorth.Valiant.Validation.AspNetCore` carries the core runtime, build, and analyzer assets needed to generate validators.\n\n## 2. Declare a validator\n\n```csharp\nusing StaticNorth.Valiant.Validation;\n\npublic sealed record RegisterUser(string? Name, int Age);\n\n[ValiantValidator]\npublic sealed partial class RegisterUserValidator\n    : ValidatorDefinition<RegisterUser>\n{\n    public override void Configure(ValidationContext<RegisterUser> context)\n    {\n        context.Property(request => request.Name)\n            .Required(\"NameRequired\", \"Enter a name.\")\n            .MaxLength(64);\n\n        context.Property(request => request.Age)\n            .GreaterThanOrEqualTo(18);\n    }\n}\n```\n\nThe declaration must be `partial` and marked with `[ValiantValidator]`. The generator emits `IValidator<RegisterUser>` directly on the class.\n\n## 3. Validate\n\n```csharp\nIValidator<RegisterUser> validator = new RegisterUserValidator();\nValidationResult result = validator.Validate(new RegisterUser(null, 16));\n\nif (!result.IsValid)\n{\n    foreach (var failure in result.Errors)\n    {\n        Console.WriteLine($\"{failure.PropertyName}: {failure.ErrorMessage}\");\n    }\n}\n```\n\nUse `ValidateAsync` for validators that contain async rules. Convenience APIs include `IsValid`, `IsValidAsync`, and `ThrowIfFailed` on the result.\n\n## 4. Register generated validators\n\n```csharp\nusing StaticNorth.Valiant.Validation.DependencyInjection;\n\nbuilder.Services.AddValiantValidators(options =>\n{\n    options.Mode = ValiantValidationMode.Auto;\n    options.FailureBehavior = ValiantFailureBehavior.ValidateAll;\n    options.Lifetime = ValiantValidatorLifetime.Scoped;\n});\n```\n\nInject `IValidator<RegisterUser>` wherever the request is handled.\n\n:::tip Async rule safety\nCall `ValidateAsync` when a validator or reused property validator may perform asynchronous work. The synchronous API does not silently block on async validation.\n:::\n"
    },
    {
      "id": "validation/guides/aspnetcore-openapi",
      "title": "ASP.NET Core and OpenAPI",
      "description": "Validate Minimal API and MVC inputs, produce problem details, and publish rule metadata to OpenAPI.",
      "module": "validation",
      "version": "1",
      "path": "/validation/guides/aspnetcore-openapi",
      "url": "https://valiant.staticnorth.dev/validation/guides/aspnetcore-openapi",
      "markdownUrl": "/markdown/validation/guides/aspnetcore-openapi.md",
      "content": "---\ntitle: \"ASP.NET Core and OpenAPI\"\ndescription: \"Validate Minimal API and MVC inputs, produce problem details, and publish rule metadata to OpenAPI.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/guides/aspnetcore-openapi\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# ASP.NET Core and OpenAPI\n\nInstall the integrations you use:\n\n```bash\ndotnet add package StaticNorth.Valiant.Validation.AspNetCore\ndotnet add package StaticNorth.Valiant.Validation.AspNetCore.OpenApi\n```\n\n## Minimal APIs\n\nRegister validators and attach validation to a route:\n\n```csharp\nbuilder.Services.AddValiantValidators();\n\napp.MapPost(\"/users\", (CreateUser request) => Results.Created())\n    .WithValiantValidation();\n```\n\nThe non-generic overload uses each non-null argument's exact declared parameter type.\n`[ValiantValidator]` discovery emits the validator, its typed invocation bridge, and their registrations\ninto the generated `AddValiantValidators()` method. The normal path therefore needs no per-model\nregistration or runtime assembly scan. The generated method covers default validators discovered in\nthe current compilation. Arguments with the same declared type reuse the validators resolved for that\nrequest while retaining handler-argument execution order.\n\nUse the typed overload to resolve `IValidator<T>` and validate every non-null handler argument\nassignable to `T`:\n\n```csharp\napp.MapPost(\"/users\", (CreateUser request, CancellationToken cancellationToken) =>\n        Results.Created())\n    .WithValiantValidation<CreateUser>();\n```\n\nThe generated parameterless path supports Native AOT. Manually registered raw `IValidator<T>` services\nwithout a generated bridge remain compatible through a JIT-only fallback. For an explicit manual\nregistration in Native AOT, use the typed overload. MVC does not receive this Native AOT guarantee.\n\nErrors return HTTP validation problem details before the handler runs. Warnings and informational\nfailures do not block the handler.\n\n## MVC\n\nRegister the global model-validation filter directly or through MVC builders:\n\n```csharp\nbuilder.Services.AddValiantValidators();\nbuilder.Services.AddValiantMvcValidation();\n\n// Equivalent integration point:\nbuilder.Services.AddControllers().AddValiantValidation();\n```\n\n## Problem details helpers\n\nUse `ValiantProblemDetails` when your endpoint or controller validates manually:\n\n```csharp\nvar result = await validator.ValidateAsync(request, cancellationToken);\nif (!result.IsValid)\n{\n    return Results.ValidationProblem(result.ToValidationProblemDictionary());\n}\n```\n\nHelpers are available for Minimal API `HttpValidationProblemDetails`, MVC `ValidationProblemDetails`, and property-to-message dictionaries.\n\n## OpenAPI\n\n```csharp\nbuilder.Services.AddOpenApi();\nbuilder.Services.AddValiantOpenApi();\n```\n\nOr attach the transformer to a specific OpenAPI document:\n\n```csharp\nbuilder.Services.AddOpenApi(options =>\n    options.AddValiantValidationRules());\n```\n\nValiant projects generated metadata into native constraints where possible—such as required, length, count, and comparison bounds—and preserves richer details in `x-valiant-rules` extensions.\n\n:::info Package references\nEach integration package forwards the core Valiant runtime and generator assets. Add both ASP.NET Core packages when you need request validation and OpenAPI; do not add a redundant direct `StaticNorth.Valiant.Validation` reference.\n:::\n\nThe [Validation sample catalog](https://valiant.staticnorth.dev/validation/samples#aspnet-core-validation) links the\nMinimal API, MVC, problem-details, and OpenAPI startup implementations.\n"
    },
    {
      "id": "validation/guides/authoring-rules",
      "title": "Authoring rules",
      "description": "Fluent rules, attribute rules, custom predicates, severity, and failure metadata.",
      "module": "validation",
      "version": "1",
      "path": "/validation/guides/authoring-rules",
      "url": "https://valiant.staticnorth.dev/validation/guides/authoring-rules",
      "markdownUrl": "/markdown/validation/guides/authoring-rules.md",
      "content": "---\ntitle: \"Authoring rules\"\ndescription: \"Fluent rules, attribute rules, custom predicates, severity, and failure metadata.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/guides/authoring-rules\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Authoring rules\n\n## Fluent definitions\n\nInherit `ValidatorDefinition<T>` and override `Configure`:\n\n```csharp\n[ValiantValidator]\npublic sealed partial class ProductValidator : ValidatorDefinition<Product>\n{\n    public override void Configure(ValidationContext<Product> context)\n    {\n        context.Property(product => product.Name)\n            .Required()\n            .LengthBetween(3, 80);\n\n        context.Property(product => product.Price)\n            .GreaterThan(0m);\n    }\n}\n```\n\nThe instance method also works naturally with constructor-injected dependencies and reusable validators.\n\n## Attribute definitions\n\nDerive from `ValidatorDefinition<T>` to read Valiant validation attributes from the model:\n\n```csharp\n[ValiantValidator]\npublic sealed partial class ProductValidator : ValidatorDefinition<Product>;\n\npublic sealed class Product\n{\n    [Required(\"NameRequired\", \"Enter a product name.\")]\n    [LengthBetween(3, 80)]\n    public string? Name { get; init; }\n\n    [GreaterThan(0)]\n    public decimal Price { get; init; }\n}\n```\n\nThese are attributes from `StaticNorth.Valiant.Validation`, not Data Annotations. Fluent and attribute rules use the same generated checks and metadata.\n\n## Custom predicates\n\nUse `Satisfies` for a rule that is clearer as code:\n\n```csharp\ncontext.Property(order => order.Reference)\n    .Satisfies(\n        value => value is null || value.StartsWith(\"ORD-\", StringComparison.Ordinal),\n        code: \"ReferenceFormat\",\n        message: \"Reference must start with ORD-.\");\n```\n\nAsync predicate overloads are available for work that accepts a cancellation token.\n\n## Conditions\n\nApply a condition to a property chain:\n\n```csharp\ncontext.Property(request => request.InviteCode)\n    .Required()\n    .When(request => request.RequiresInvite);\n```\n\nFor larger branches, use normal C# control flow. See [Composition and control flow](https://valiant.staticnorth.dev/validation/guides/composition-control-flow).\n\n## Codes, messages, and severity\n\nEvery built-in check accepts optional `code`, `message`, and `severity` arguments:\n\n```csharp\ncontext.Property(user => user.DisplayName)\n    .MaxLength(\n        40,\n        code: \"DisplayNameLong\",\n        message: \"Display name is longer than 40 characters.\",\n        severity: ValiantSeverity.Warning);\n```\n\n`ValidationResult.Errors` determine `IsValid`. `Warnings` and `Infos` are preserved separately for callers that want non-blocking feedback.\n"
    },
    {
      "id": "validation/guides/composition-control-flow",
      "title": "Composition and control flow",
      "description": "Native branches, nested objects, collections, reusable root validators, and property validators.",
      "module": "validation",
      "version": "1",
      "path": "/validation/guides/composition-control-flow",
      "url": "https://valiant.staticnorth.dev/validation/guides/composition-control-flow",
      "markdownUrl": "/markdown/validation/guides/composition-control-flow.md",
      "content": "---\ntitle: \"Composition and control flow\"\ndescription: \"Native branches, nested objects, collections, reusable root validators, and property validators.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/guides/composition-control-flow\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Composition and control flow\n\n## Write normal C# branches\n\nValidator configuration supports native `if`/`else`, `switch`, loops, and `foreach`:\n\n```csharp\npublic void Configure(ValidationContext<CreateOrder> context)\n{\n    if (context.Instance.RequiresApproval)\n    {\n        context.Property(order => order.ApproverId).Required();\n    }\n\n    switch (context.Instance.Channel)\n    {\n        case SalesChannel.Store:\n            context.Property(order => order.StoreId).Required();\n            break;\n        case SalesChannel.Web:\n            context.Property(order => order.SessionId).Required();\n            break;\n    }\n}\n```\n\nIn `Debuggable` mode this method executes at runtime, so ordinary breakpoints and step-through debugging work.\n\n## Nested objects\n\nUse `Children` to validate a nested context and retain the complete property path:\n\n```csharp\ncontext.Property(order => order.Customer)\n    .Required()\n    .Children(customer =>\n    {\n        customer.Property(value => value.Name).Required();\n        customer.Property(value => value.Email).MaxLength(200);\n    });\n```\n\n## Collections\n\nUse `ForEach` for element rules. `context.Item` is the current item inside the nested validation context:\n\n```csharp\ncontext.Property(order => order.Lines)\n    .MinCount(1)\n    .ForEach(line =>\n    {\n        line.Property(item => item.Sku).Required();\n        line.Property(item => item.Quantity).GreaterThan(0);\n    });\n```\n\nFailures include indexed paths such as `Lines[0].Sku`.\n\n## Reuse a root validator\n\n```csharp\npublic sealed partial class CheckoutValidator(AddressValidator addressValidator)\n    : ValidatorDefinition<Checkout>\n{\n    public override void Configure(ValidationContext<Checkout> context)\n    {\n        context.UseValidator(addressValidator);\n        context.Property(value => value.AcceptedTerms).Equal(true);\n    }\n}\n```\n\n## Reuse a property validator\n\nCreate a reusable `PropertyValidatorDefinition<TProperty>` and attach it to a property:\n\n```csharp\ncontext.Property(order => order.ShippingAddress)\n    .Required()\n    .UseValidator(addressPropertyValidator);\n```\n\nProperty validators skip null values. Add `Required()` or `NotNull()` when absence itself is invalid. Attribute-authored models can use `[UseValidator<TValidator>]`.\n\n## Failure behavior\n\nConfigure collection globally, then override it at validator or property-chain scope:\n\n```csharp\nservices.AddValiantValidators(options =>\n    options.FailureBehavior = ValiantFailureBehavior.ValidateAll);\n```\n\nUse `FailFast` to stop within the configured scope after the first failure; use `ValidateAll` to collect all applicable failures. Narrower configuration overrides the global option.\n"
    },
    {
      "id": "validation/guides/mediator-pipelines",
      "title": "Mediator pipelines",
      "description": "Validate requests automatically in MediatR and source-generated Mediator pipelines.",
      "module": "validation",
      "version": "1",
      "path": "/validation/guides/mediator-pipelines",
      "url": "https://valiant.staticnorth.dev/validation/guides/mediator-pipelines",
      "markdownUrl": "/markdown/validation/guides/mediator-pipelines.md",
      "content": "---\ntitle: \"Mediator pipelines\"\ndescription: \"Validate requests automatically in MediatR and source-generated Mediator pipelines.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/guides/mediator-pipelines\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Mediator pipelines\n\n## MediatR\n\nInstall `StaticNorth.Valiant.Validation.MediatR`, register generated validators, and add the behavior through MediatR configuration:\n\n```csharp\nbuilder.Services.AddValiantValidators();\n\nbuilder.Services.AddMediatR(configuration =>\n{\n    configuration.RegisterServicesFromAssemblyContaining<CreateUserCommand>();\n    configuration.AddValiantValidation();\n});\n```\n\nThe package targets MediatR 12.5.0, the final free MediatR release.\n\n## Source-generated Mediator\n\nInstall `StaticNorth.Valiant.Validation.Mediator`:\n\n```csharp\nbuilder.Services.AddValiantValidators();\nbuilder.Services.AddMediator(options =>\n{\n    options.Assemblies = [typeof(CreateUserCommand).Assembly];\n});\nbuilder.Services.AddValiantMediatorValidation();\n```\n\nFor Native AOT, list the behavior in the source-generated pipeline:\n\n```csharp\nbuilder.Services.AddMediator(options =>\n{\n    options.Assemblies = [typeof(CreateUserCommand).Assembly];\n    options.PipelineBehaviors = [typeof(ValiantValidationBehavior<,>)];\n});\n```\n\n:::warning Choose one Mediator registration path\nDo not call `AddValiantMediatorValidation()` when `ValiantValidationBehavior<,>` is already present in `PipelineBehaviors`.\n:::\n\nBoth integrations resolve all registered `IValidator<TRequest>` instances, run them before the next handler, and surface validation failure instead of invoking the handler.\n"
    },
    {
      "id": "validation/reference/packages",
      "title": "Package guide",
      "description": "Choose the smallest Valiant Validation package set for your application.",
      "module": "validation",
      "version": "1",
      "path": "/validation/reference/packages",
      "url": "https://valiant.staticnorth.dev/validation/reference/packages",
      "markdownUrl": "/markdown/validation/reference/packages.md",
      "content": "---\ntitle: \"Package guide\"\ndescription: \"Choose the smallest Valiant Validation package set for your application.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/reference/packages\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Package guide\n\nInstall the most specific package for each integration you use. Integration packages carry the core validation runtime, build, and analyzer assets, so a separate `StaticNorth.Valiant.Validation` reference is unnecessary.\n\n| Package | Use it for | Target |\n| --- | --- | --- |\n| `StaticNorth.Valiant.Validation` | Core validators without a host integration | .NET 8 and .NET Standard 2.0 |\n| `StaticNorth.Valiant.Validation.AspNetCore` | Minimal APIs, MVC, and problem details | .NET 8 |\n| `StaticNorth.Valiant.Validation.AspNetCore.OpenApi` | Native ASP.NET Core OpenAPI schema rules | .NET 10 |\n| `StaticNorth.Valiant.Validation.MediatR` | MediatR 12.5 pipeline validation | .NET 8 |\n| `StaticNorth.Valiant.Validation.Mediator` | Source-generated Mediator pipeline validation | .NET 8 |\n\n## Common combinations\n\n```xml\n<!-- Minimal API validation only -->\n<PackageReference Include=\"StaticNorth.Valiant.Validation.AspNetCore\" Version=\"...\" />\n```\n\n```xml\n<!-- Minimal API validation plus OpenAPI rule metadata -->\n<PackageReference Include=\"StaticNorth.Valiant.Validation.AspNetCore\" Version=\"...\" />\n<PackageReference Include=\"StaticNorth.Valiant.Validation.AspNetCore.OpenApi\" Version=\"...\" />\n```\n\n```xml\n<!-- Application-layer validation with MediatR -->\n<PackageReference Include=\"StaticNorth.Valiant.Validation.MediatR\" Version=\"...\" />\n```\n\nReference more than one integration package when the application uses more than one integration. Do not add the core package solely to make source generation work.\n"
    },
    {
      "id": "validation/reference/runtime-generation",
      "title": "Runtime and generation",
      "description": "Validator APIs, modes, failure behavior, DI lifetime, generator scope, and diagnostics.",
      "module": "validation",
      "version": "1",
      "path": "/validation/reference/runtime-generation",
      "url": "https://valiant.staticnorth.dev/validation/reference/runtime-generation",
      "markdownUrl": "/markdown/validation/reference/runtime-generation.md",
      "content": "---\ntitle: \"Runtime and generation\"\ndescription: \"Validator APIs, modes, failure behavior, DI lifetime, generator scope, and diagnostics.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/reference/runtime-generation\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Runtime and generation\n\n## Validator API\n\nGenerated validators implement `IValidator<T>`:\n\n```csharp\nValidationResult Validate(T instance);\nValueTask<ValidationResult> ValidateAsync(T instance, CancellationToken cancellationToken = default);\nbool IsValid(T instance);\nValueTask<bool> IsValidAsync(T instance, CancellationToken cancellationToken = default);\n```\n\nUse async APIs whenever a validator graph can contain async predicates or async property validators.\n\n## Options\n\n| Option | Values | Default |\n| --- | --- | --- |\n| `Mode` | `Auto`, `Debuggable`, `Fast` | `Auto` |\n| `FailureBehavior` | `ValidateAll`, `FailFast` | `ValidateAll` |\n| `Lifetime` | `Scoped`, `Transient`, `Singleton` | `Scoped` |\n\n`Auto` uses the runtime, debuggable backend in Debug builds and generated fast code otherwise. `Debuggable` lets you step through `Configure`; `Fast` always uses direct generated checks.\n\nChoose validator lifetime based on constructor dependencies. A singleton validator must not capture scoped services.\n\n## Result model\n\n`ValidationResult` exposes all failures as well as `Errors`, `Warnings`, and `Infos`. Only error severity makes `IsValid` false. Each `ValidationFailure` includes `PropertyName`, `ErrorCode`, `ErrorMessage`, and `Severity`.\n\nResults are immutable and do not need disposal. In `Fast` mode, simple validators\nwith at most six checks and fixed default failure content reuse results after\neach failure combination is first seen. All checks still run on every call.\nReuse is bounded to 63 nonempty combinations per validator type. Custom diagnostic\nexpressions, culture-dependent messages, composition, async checks, and larger\nvalidators keep the owned-result path.\n\n## Generator scope\n\n`[ValiantValidator]` is the discovery hook. Only marked validator declarations enter the incremental pipeline. Generated output can include:\n\n- direct sync/async `IValidator<T>` methods;\n- metadata used by OpenAPI and integrations;\n- generated DI registration through `AddValiantValidators`;\n- composition code for root and property validators.\n\nThe marker accepts generic and `typeof(...)` compatibility forms. Prefer an ordinary `[ValiantValidator]` declaration that inherits `ValidatorDefinition<T>`; it is the recommended authoring surface for both fluent and attribute-based validation.\n\n## Authoring constraints\n\n- Validator and generated containing types must be `partial`.\n- Attribute rules must be Valiant validation attributes.\n- Generator-readable expressions produce direct fast-path code; unsupported declaration shapes are compile-time diagnostics rather than runtime surprises.\n- Property validators skip null property values unless presence is checked separately.\n"
    },
    {
      "id": "validation/reference/validation-checks",
      "title": "Validation check catalog",
      "description": "Every built-in Valiant validation check, grouped by supported value shape.",
      "module": "validation",
      "version": "1",
      "path": "/validation/reference/validation-checks",
      "url": "https://valiant.staticnorth.dev/validation/reference/validation-checks",
      "markdownUrl": "/markdown/validation/reference/validation-checks.md",
      "content": "---\ntitle: \"Validation check catalog\"\ndescription: \"Every built-in Valiant validation check, grouped by supported value shape.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/reference/validation-checks\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Validation check catalog\n\nAll checks accept optional `code`, `message`, and `severity`. Nullable value checks generally skip `null`; combine them with `Required()` or `NotNull()` when null is invalid.\n\n## General values\n\n| Check | Purpose |\n| --- | --- |\n| `NotNull()` / `Null()` | Require presence or absence |\n| `Required()` | Require a non-null value and, for strings/collections, non-empty content |\n| `NotEmpty()` / `Empty()` | Require content or emptiness |\n| `Equal(value)` / `NotEqual(value)` | Compare with an expected value |\n| `Satisfies(predicate)` | Apply a custom sync or async predicate |\n| `UseValidator(validator)` | Delegate to a reusable property validator |\n\n## Comparable values\n\n`GreaterThan`, `GreaterThanOrEqualTo`, `LessThan`, `LessThanOrEqualTo`, `InclusiveBetween`, and `ExclusiveBetween` support compatible comparable values and nullable counterparts.\n\n```csharp\ncontext.Property(product => product.Price)\n    .GreaterThan(0m)\n    .LessThanOrEqualTo(10_000m);\n```\n\n## Strings and length-bearing values\n\n| Check | Purpose |\n| --- | --- |\n| `LengthBetween(min, max)` | Inclusive length range |\n| `MinLength(min)` | Minimum length |\n| `MaxLength(max)` | Maximum length |\n\n## Collections\n\n| Check | Purpose |\n| --- | --- |\n| `Count(count)` | Exact item count |\n| `CountBetween(min, max)` | Inclusive item-count range |\n| `MinCount(min)` / `MaxCount(max)` | Count bounds |\n| `Contains(item)` / `Excludes(item)` | Membership |\n| `All(predicate)` / `Any(predicate)` / `None(predicate)` | Element predicates |\n| `ForEach(configure)` | Validate every item with a nested context |\n\n## Dictionaries\n\n`HasKey(key)` and `HasValue(value)` validate dictionary membership.\n\n## Enums\n\n| Check | Input |\n| --- | --- |\n| `DefinedEnum()` | Enum or nullable enum value |\n| `EnumName(enumType)` | String name |\n| `EnumValue(enumType)` | Supported integral value or nullable counterpart |\n\n## Attribute equivalents\n\nAttribute-authored validators support the corresponding Valiant attributes for declarative checks, including required/nullability, equality, enum, length/count, collection membership, dictionary, and comparison rules. Rules that require executable delegates—custom predicates, native control flow, and inline `ForEach` contexts—belong in a fluent `ValidatorDefinition<T>`.\n"
    },
    {
      "id": "validation/samples",
      "title": "Samples",
      "description": "Run the core validation and ASP.NET Core integration samples.",
      "module": "validation",
      "version": "1",
      "path": "/validation/samples",
      "url": "https://valiant.staticnorth.dev/validation/samples",
      "markdownUrl": "/markdown/validation/samples.md",
      "content": "---\ntitle: \"Samples\"\ndescription: \"Run the core validation and ASP.NET Core integration samples.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/validation/samples\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Validation samples\n\nValidation has separate console and ASP.NET Core sample projects. Each runnable\nchoice owns its description on its `Sample` or `Startup` class; `Program.cs`\nonly selects which one to execute.\n\n## Core validation\n\nRun the console project:\n\n```bash\ndotnet run --project validation/samples/StaticNorth.Valiant.Validation.Samples\n```\n\nSelect one delegate in\n[`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/validation/samples/StaticNorth.Valiant.Validation.Samples/Program.cs):\n\n| Delegate | Demonstrates | Source |\n| --- | --- | --- |\n| `Basic.Sample.RunAsync` | A minimal fluent validator, generated registration, validation, and failure output | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/Basic) |\n| `AttributeValidation.Sample.RunAsync` | Validation attributes on the model with the generated validator contract | [`AttributeValidation`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/AttributeValidation) |\n| `DependencyInjection.Sample.RunAsync` | Generated registrations, configurable lifetime and defaults, concrete non-default validators, property validators, and metadata providers | [`DependencyInjection`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/DependencyInjection) |\n| `SyncAndAsyncValidation.Sample.RunAsync` | Sync and async APIs, boolean helpers, and the guard against synchronously invoking an asynchronous validator | [`SyncAndAsyncValidation`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/SyncAndAsyncValidation) |\n| `Severity.Sample.RunAsync` | Error, warning, and information severities, including valid warning-only and information-only results | [`Severity`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/Severity) |\n| `CompositionAndPaths.Sample.RunAsync` | Whole-model composition, reusable property validators, child contexts, collection items, and nested/indexed paths | [`CompositionAndPaths`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/CompositionAndPaths) |\n| `FailureHandling.Sample.RunAsync` | Per-property fail-fast behavior, result helpers, and `ThrowIfFailed()` | [`FailureHandling`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/FailureHandling) |\n| `ControlFlowAndCollections.Sample.RunAsync` | Collection and dictionary rules, conditions, switches, indexed validation, and native loops | [`ControlFlowAndCollections`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/ControlFlowAndCollections) |\n\nThe\n[`Catalog`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.Samples/Catalog)\nfolder is shared support code for the advanced scenarios, not an additional\nselectable sample.\n\n## ASP.NET Core validation\n\nRun the web project:\n\n```bash\ndotnet run --project validation/samples/StaticNorth.Valiant.Validation.AspNetCore.Samples\n```\n\nSelect one startup in\n[`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/validation/samples/StaticNorth.Valiant.Validation.AspNetCore.Samples/Program.cs):\n\n| Startup | Demonstrates | Source |\n| --- | --- | --- |\n| `MinimalApi.Startup` | Typed and all-parameter Minimal API filters that reject invalid requests before the handler runs | [`MinimalApi`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.AspNetCore.Samples/MinimalApi) |\n| `Mvc.Startup` | Automatic MVC validation without a validator dependency or manual validation branch in the controller | [`Mvc`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.AspNetCore.Samples/Mvc) |\n| `ProblemDetails.Startup` | Manual validation converted to HTTP and MVC validation problem-details responses | [`ProblemDetails`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.AspNetCore.Samples/ProblemDetails) |\n| `OpenApi.Startup` | Generated Valiant validation metadata projected into the application's OpenAPI document | [`OpenApi`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.AspNetCore.Samples/OpenApi) |\n\nThe\n[`Orders`](https://github.com/static-north-dev/valiant/tree/main/validation/samples/StaticNorth.Valiant.Validation.AspNetCore.Samples/Orders)\nfolder contains the shared request models and validator; it is not a startup\nchoice.\n\nThe web scenarios are also exercised through `WebApplicationFactory`, so the\nsampled registration and HTTP behavior stay covered by the validation test\nproject. See [ASP.NET Core and OpenAPI](https://valiant.staticnorth.dev/validation/guides/aspnetcore-openapi) for\nconsumer setup.\n"
    },
    {
      "id": "endpoints/index",
      "title": "Endpoints",
      "description": "Endpoint-per-class Minimal APIs with generated registration, groups, conventions, and rich query binding.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/",
      "url": "https://valiant.staticnorth.dev/endpoints/",
      "markdownUrl": "/markdown/endpoints.md",
      "content": "---\ntitle: \"Endpoints\"\ndescription: \"Endpoint-per-class Minimal APIs with generated registration, groups, conventions, and rich query binding.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Minimal APIs, organized by feature\n\nValiant Endpoints gives every ASP.NET Core Minimal API endpoint a small class and generates deterministic route registration. Group vertical slices, apply conventions once, exclude features at startup, and bind query shapes that ASP.NET Core does not handle by default.\n\n```csharp\nusing StaticNorth.Valiant.Endpoints;\nusing StaticNorth.Valiant.Endpoints.AspNetCore;\n\n[ValiantEndpoint<TodosEndpointGroup>]\ninternal sealed class ListTodosEndpoint : IEndpoint\n{\n    public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) =>\n        builder.MapGet(\"/\", () => Results.Ok());\n}\n```\n\n```csharp\nbuilder.Services.AddValiantEndpoints();\n\nvar app = builder.Build();\napp.MapValiantEndpoints();\n```\n\n## What it covers\n\n| Capability | API |\n| --- | --- |\n| Generated discovery | `[ValiantEndpoint]`, `[ValiantEndpoint<TGroup>]`, `[ValiantEndpointGroup]` |\n| Route organization | `IEndpoint`, `IEndpointGroup`, standalone and grouped routes |\n| Shared policy | Group and endpoint configuration hooks over the returned route builders |\n| Feature switches | Separate startup predicates for generated groups and endpoints |\n| Multiple assemblies | Explicit registration and mapping overloads |\n| Query compatibility | Arrays, nested objects, JSON opt-in, parser, serializer, and structured errors |\n| Request binding | Opt-in generated `BindAsync`, `[AsParameters]` repair, and complex `[FromQuery]` shims; native ASP.NET Core binding by default |\n\n## Documentation map\n\n- [Quick start](https://valiant.staticnorth.dev/endpoints/quick-start)\n- [Runnable samples](https://valiant.staticnorth.dev/endpoints/samples)\n- [Groups and conventions](https://valiant.staticnorth.dev/endpoints/guides/groups-conventions)\n- [Conditional registration](https://valiant.staticnorth.dev/endpoints/guides/conditional-registration)\n- [Request binding](https://valiant.staticnorth.dev/endpoints/guides/request-binding)\n- [Query parameter reference](https://valiant.staticnorth.dev/endpoints/reference/query-parameters)\n- [Registration, generation, and diagnostics](https://valiant.staticnorth.dev/endpoints/reference/registration-generation)\n\nThe [sample catalog](https://valiant.staticnorth.dev/endpoints/samples) covers every selectable startup in the\nrunnable endpoint-per-class host, including generated binding and intentional\nconditional exclusions.\n"
    },
    {
      "id": "endpoints/quick-start",
      "title": "Quick start",
      "description": "Install StaticNorth.Valiant.Endpoints.AspNetCore and map your first generated endpoint.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/quick-start",
      "url": "https://valiant.staticnorth.dev/endpoints/quick-start",
      "markdownUrl": "/markdown/endpoints/quick-start.md",
      "content": "---\ntitle: \"Quick start\"\ndescription: \"Install StaticNorth.Valiant.Endpoints.AspNetCore and map your first generated endpoint.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/quick-start\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Quick start\n\n## 1. Install\n\n```bash\ndotnet add package StaticNorth.Valiant.Endpoints.AspNetCore\n```\n\nThis is the consumer package. It includes the shared endpoint contracts and bundles the source generator; do not add separate `StaticNorth.Valiant.Endpoints` or generator references.\n\n## 2. Create an endpoint\n\n```csharp\nusing StaticNorth.Valiant.Endpoints;\nusing StaticNorth.Valiant.Endpoints.AspNetCore;\n\n[ValiantEndpoint]\ninternal sealed class HealthEndpoint : IEndpoint\n{\n    public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder)\n    {\n        return builder.MapGet(\"/health\", () => Results.Ok(new { status = \"ready\" }));\n    }\n}\n```\n\n`[ValiantEndpoint]` makes it a standalone endpoint on the root route builder.\n\n## 3. Register and map\n\n```csharp\nusing StaticNorth.Valiant.Endpoints.AspNetCore.DependencyInjection;\n\nbuilder.Services.AddValiantEndpoints();\n\nvar app = builder.Build();\napp.MapValiantEndpoints();\napp.Run();\n```\n\nRegistration discovers generated registrar metadata from the calling and entry assemblies. Mapping resolves those registrars and invokes each generated route plan.\n\n## 4. Put endpoints in a group\n\n```csharp\n[ValiantEndpointGroup]\ninternal sealed class TodosEndpointGroup : IEndpointGroup\n{\n    public static RouteGroupBuilder CreateGroup(IEndpointRouteBuilder builder) =>\n        builder.MapGroup(\"/api/todos\").WithTags(\"Todos\");\n}\n\n[ValiantEndpoint<TodosEndpointGroup>]\ninternal sealed class GetTodoEndpoint : IEndpoint\n{\n    public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) =>\n        builder.MapGet(\"/{id:guid}\", (Guid id) => Results.Ok(id));\n}\n```\n\nEvery endpoint group must implement `CreateGroup`; Valiant does not derive group routes from type names.\n\nNext: centralize tags, filters, OpenAPI, and naming in [Groups and conventions](https://valiant.staticnorth.dev/endpoints/guides/groups-conventions).\n"
    },
    {
      "id": "endpoints/guides/conditional-registration",
      "title": "Conditional registration",
      "description": "Include or exclude generated endpoint groups and endpoints at application startup.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/guides/conditional-registration",
      "url": "https://valiant.staticnorth.dev/endpoints/guides/conditional-registration",
      "markdownUrl": "/markdown/endpoints/guides/conditional-registration.md",
      "content": "---\ntitle: \"Conditional registration\"\ndescription: \"Include or exclude generated endpoint groups and endpoints at application startup.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/guides/conditional-registration\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Conditional registration\n\nConfigure generated groups and endpoints independently:\n\n```csharp\nbuilder.Services.AddValiantEndpoints(options =>\n{\n    options.MapEndpointGroupsWhen = group =>\n        group.GroupType != typeof(ExperimentalEndpointGroup) ||\n        builder.Environment.IsDevelopment();\n\n    options.MapEndpointWhen = endpoint =>\n        endpoint.EndpointType != typeof(DeprecatedEndpoint);\n});\n```\n\nEach predicate receives generated registration metadata while `MapValiantEndpoints()` runs at startup. Both policies allow every generated registration by default. Assigning either property again replaces its previously configured predicate.\n\nSee the\n[runnable conditional-registration sample](https://valiant.staticnorth.dev/endpoints/samples#conditional-registration)\nfor allowed and rejected group and standalone endpoint routes.\n\n`EndpointGroupRegistration` exposes:\n\n- `GroupType`;\n- generated mapping `Order`.\n\n`EndpointRegistration` exposes:\n\n- `EndpointType`;\n- the optional containing `Group`;\n- generated mapping `Order`;\n- `IsGrouped`;\n- the pre-mapping `QueryParameters` snapshot.\n\nThe query snapshot reports whether binding support was generated, whether runtime binding filters are enabled, and the parsing options known before `IEndpoint.Map(...)` executes. It cannot include route patterns, HTTP methods, tags, authorization, or endpoint-authored `.WithQueryParsingOptions(...)` metadata because those are created during mapping.\n\nFor a group inferred from referenced generated endpoints, `Order` is the lowest generated child order used to place that group. Previously compiled generated registrars did not carry order metadata, so the compatibility bridge reports `0` for those legacy registrations.\n\n## Exclude a whole group\n\n```csharp\noptions.MapEndpointGroupsWhen = group =>\n    group.GroupType != typeof(AdminEndpointGroup);\n```\n\nReturning `false` for a group skips:\n\n- group creation;\n- all generated endpoints assigned to that group;\n- the `ConfigureEndpointGroup` hook.\n\nThe endpoint predicate is not evaluated for endpoints in an excluded group.\n\n## Exclude individual endpoints\n\n```csharp\noptions.MapEndpointWhen = endpoint =>\n    endpoint.EndpointType != typeof(DeleteAccountEndpoint);\n```\n\nReturning `false` for an endpoint excludes only that grouped or standalone endpoint. Other endpoints in its group still map normally.\n\n## Combine feature flags, environment, and metadata\n\n```csharp\nvar disabled = new HashSet<Type>\n{\n    typeof(LegacyReportsEndpoint),\n    typeof(PreviewEndpointGroup)\n};\n\nbuilder.Services.AddValiantEndpoints(options =>\n{\n    options.MapEndpointGroupsWhen = group =>\n        !disabled.Contains(group.GroupType) &&\n        (!group.GroupType.Name.StartsWith(\"Internal\", StringComparison.Ordinal) ||\n         builder.Environment.IsDevelopment());\n\n    options.MapEndpointWhen = endpoint =>\n        !disabled.Contains(endpoint.EndpointType) &&\n        (!endpoint.EndpointType.Name.StartsWith(\"Internal\", StringComparison.Ordinal) ||\n         builder.Environment.IsDevelopment());\n});\n```\n\nYou can also inspect custom attributes on each `Type`, configuration, license state, or a precomputed feature snapshot. Keep the predicates fast and deterministic because they run synchronously during route construction.\n\n## Configure parsing conditionally\n\nUse a separate rule when selected endpoint registrations need different parsing:\n\n```csharp\noptions.ConfigureEndpointWhen(\n    endpoint => endpoint.Group?.GroupType == typeof(SearchEndpointGroup),\n    endpointOptions => endpointOptions.QueryParameters.Parsing =\n        new QueryParsingOptions\n        {\n            SupportedArrayFormats = [QueryArrayFormat.CommaSeparated],\n            SupportedObjectFormats = [QueryObjectFormat.Flat]\n        });\n```\n\nAll rule predicates observe the same initial pre-mapping snapshot. Matching actions run in registration order before `MapEndpointWhen` evaluates the final descriptor. Parsing precedence is:\n\n1. Explicit `[ValiantQueryParsing]` properties.\n2. Endpoint-authored `.WithQueryParsingOptions(...)`.\n3. Conditional registration configuration.\n4. Global `ValiantEndpointOptions.QueryParameters.Parsing`.\n\n`EnableBinding` remains a compilation-wide generator decision. Set `options.QueryParameters.EnableBinding = true` directly in the `AddValiantEndpoints` setup lambda when generated binding is required. Conditional parsing rules cannot generate or remove `BindAsync` and direct `TryParse` members.\n\n## Migrate from `ShouldMap`\n\nSplit the old shared predicate by registration kind:\n\n```csharp\n// Before\noptions.ShouldMap = type => !disabled.Contains(type);\n\n// After\noptions.MapEndpointGroupsWhen = group => !disabled.Contains(group.GroupType);\noptions.MapEndpointWhen = endpoint => !disabled.Contains(endpoint.EndpointType);\n```\n\n:::warning Startup decision, not request routing\nThe predicates are evaluated once when endpoints are mapped. They do not change routes after startup and are not a substitute for authorization or per-request feature evaluation.\n:::\n\n:::info Generated registrations only\nRoutes mapped directly with ASP.NET Core are outside Valiant's generated mapping policy. Apply application-specific conditions to those routes directly.\n:::\n"
    },
    {
      "id": "endpoints/guides/groups-conventions",
      "title": "Groups and conventions",
      "description": "Create route groups, order registration, and apply global conventions.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/guides/groups-conventions",
      "url": "https://valiant.staticnorth.dev/endpoints/guides/groups-conventions",
      "markdownUrl": "/markdown/endpoints/guides/groups-conventions.md",
      "content": "---\ntitle: \"Groups and conventions\"\ndescription: \"Create route groups, order registration, and apply global conventions.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/guides/groups-conventions\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Groups and conventions\n\n## Create groups\n\nEvery endpoint group implements `CreateGroup` and explicitly chooses its route and group-level metadata:\n\n```csharp\n[ValiantEndpointGroup(Order = 10)]\ninternal sealed class OrdersEndpointGroup : IEndpointGroup\n{\n    public static RouteGroupBuilder CreateGroup(IEndpointRouteBuilder builder) =>\n        builder\n            .MapGroup(\"/api/orders\")\n            .WithTags(\"Orders\")\n            .RequireAuthorization();\n}\n```\n\n## Global conventions\n\n```csharp\nbuilder.Services.AddValiantEndpoints(options =>\n{\n    options.ConfigureEndpointGroup = (group, registration) =>\n    {\n        group.AddEndpointFilter<ExceptionHandlingFilter>();\n        group.WithOpenApi();\n    };\n\n    options.ConfigureEndpoint = (endpoint, registration) =>\n        endpoint.WithName(registration.EndpointType.Name);\n});\n```\n\nThe generated sequence is:\n\n1. Create the group through its required `CreateGroup` implementation.\n2. Associate its `EndpointGroupRegistration`.\n3. Run `ConfigureEndpointGroup`.\n4. Map each included endpoint and apply Valiant binding and parsing conventions.\n5. Run `ConfigureEndpoint` with that endpoint's `EndpointRegistration`.\n\nBoth hooks are actions over the builders returned by `IEndpointGroup.CreateGroup(...)` and `IEndpoint.Map(...)`. The group hook cannot replace the returned builder. Put route prefixes and nested `MapGroup(...)` calls in the group's `CreateGroup` implementation.\n\n`EndpointGroupRegistration` exposes the group type and generated order. `EndpointRegistration` exposes the endpoint type, containing group, generated order, and query-binding snapshot, so global conventions can branch without repeating reflection-based discovery.\n\nSee the\n[runnable configuration sample](https://valiant.staticnorth.dev/endpoints/samples#configuration-hooks)\nfor two grouped routes where a group hook adds a shared response header and an endpoint hook adds a second header only to the selected endpoint.\n\n## Migrating the earlier preview hooks\n\nThe earlier preview exposed three callbacks. Consolidate them as follows:\n\n- Move both `ConfigureAllEndpointGroupsBeforeMapping` and `ConfigureAllEndpointGroupsAfterMapping` conventions into `ConfigureEndpointGroup`.\n- Replace `ConfigureAllEndpointsAfterMapping` with `ConfigureEndpoint`.\n- Replace callback `Type` parameters with `registration.GroupType` or `registration.EndpointType`.\n- Move any callback that returned `group.MapGroup(...)` into `IEndpointGroup.CreateGroup(...)`.\n\n## Ordering\n\nSet `Order` on endpoint and group marker attributes when one generated mapping must precede another:\n\n```csharp\n[ValiantEndpoint<OrdersEndpointGroup>(Order = -100)]\ninternal sealed class SearchOrdersEndpoint : IEndpoint { /* ... */ }\n```\n\nTypes with the same order are sorted by type name, keeping generated output deterministic.\n\n## Standalone endpoints\n\n`[ValiantEndpoint]` without a group maps directly on the supplied root route builder. The same `ConfigureEndpoint` hook and `MapEndpointWhen` registration policy apply; its registration has `Group == null`.\n"
    },
    {
      "id": "endpoints/guides/request-binding",
      "title": "Request binding",
      "description": "Bind complex query objects through generated requests, AsParameters, and FromQuery compatibility shims.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/guides/request-binding",
      "url": "https://valiant.staticnorth.dev/endpoints/guides/request-binding",
      "markdownUrl": "/markdown/endpoints/guides/request-binding.md",
      "content": "---\ntitle: \"Request binding\"\ndescription: \"Bind complex query objects through generated requests, AsParameters, and FromQuery compatibility shims.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/guides/request-binding\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Request binding\n\nValiant query binding is disabled by default, leaving request parameters to native ASP.NET Core binding. Enable generated binding in the same project as the endpoint declarations with a direct assignment:\n\n```csharp\nbuilder.Services.AddValiantEndpoints(options =>\n{\n    options.QueryParameters.EnableBinding = true;\n});\n```\n\nChanging the literal between `true` and `false` adds or removes generated query binding during the normal rebuild. Helper methods, runtime variables, and a host configuration in another assembly are not compile-time opt-ins.\n\n:::caution Compile-time boundary\n\n`EnableBinding` is not a fully dynamic runtime switch. Whole-request `BindAsync` and `[AsParameters]` processing can read runtime options, but a generated direct `TryParse(string, out T)` has no `HttpContext`. If the endpoint compilation contains a recognized literal `true`, another host or later runtime override to `false` cannot remove or neutralize that direct parser. Compile the endpoint project with no recognized `true` assignment when `[ValiantQueryParsing]` must be ignored.\n\n:::\n\nWhen enabled, Valiant connects its configurable query parser to generated endpoints in three binding shapes.\n\n## Whole request binding\n\nMake the request `partial` and place `[FromQuery]` on query members:\n\n```csharp\nreturn builder.MapGet(\"/cars\", static (ListCarsRequest request) =>\n    Results.Ok(request.Filter));\n\npublic sealed partial record ListCarsRequest\n{\n    [FromQuery]\n    public CarFilter? Filter { get; init; }\n}\n\npublic sealed record CarFilter(int? Year, string? Brand);\n```\n\nValiant emits `BindAsync(HttpContext, ParameterInfo)` on `ListCarsRequest` and parses the full query through the configured policy.\nIf the request is nested inside an endpoint or another type, every containing declaration must also be `partial` so generated code can reopen the complete declaration chain.\n\n## `[AsParameters]`\n\nASP.NET Core first constructs the request; a Valiant endpoint filter then reparses the full query and copies `[FromQuery]` values back:\n\n```csharp\nreturn builder.MapGet(\"/cars\", static ([AsParameters] ListCarsRequest request) =>\n    Results.Ok(request.Filter));\n\npublic sealed record ListCarsRequest\n{\n    [FromQuery]\n    public CarFilter? Filter { get; init; }\n}\n\npublic sealed partial record CarFilter(int? Year, string? Brand);\n```\n\nThe complex `[FromQuery]` type must be `partial` in this shape. Valiant generates a `TryParse(string, out T)` shim because ASP.NET Core checks property bindability before endpoint filters run.\nThe same containing-type rule applies when that complex type is nested.\n\nThe Valiant filter runs after native property binding, so it cannot recover from a format that makes ASP.NET Core fail the initial property conversion. For example, comma-separated `?ids=1,2,3` fails before the filter for an `int[] Ids` property. Use generated whole-request binding when every configured format must work without native `[AsParameters]` constraints.\n\n## Direct complex `[FromQuery]`\n\nComplex query types used directly also need to be source-declared and `partial` so the generator can add the compatibility parser.\n\n```csharp\nreturn builder.MapGet(\"/cars\", static ([FromQuery] CarFilter filter) =>\n    Results.Ok(filter));\n\npublic sealed partial record CarFilter(int? Year, string? Brand);\n```\n\nASP.NET Core calls the generated `TryParse` method to bind the value. Configure its JSON policy on the endpoint:\n\n```csharp\n[ValiantEndpoint]\n[ValiantQueryParsing(JsonValues = JsonQueryValues.Disabled)]\npublic sealed class CarsEndpoint : IEndpoint\n{\n    public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) =>\n        builder.MapGet(\"/cars\", static ([FromQuery] CarFilter filter) => Results.Ok(filter));\n}\n```\n\nThe policy is compiled into the generated method, so direct binding does not use an endpoint filter. When the endpoint project is compiled with `options.QueryParameters.EnableBinding = false`, the attribute is ignored and no Valiant query parser is emitted. A later runtime-only override cannot change an already-generated direct parser; see the compile-time boundary above. When binding is enabled, JSON remains enabled when the attribute is absent or parameterless. Explicit `Disabled` returns HTTP 400. `SupportedArrayFormats` and `SupportedObjectFormats` on the attribute do not affect direct parameters. The attribute does not change a user-authored `TryParse`. Conflicting policies for the same generated parser type report `VLE011`.\n\n## Failure response\n\nGenerated binders and the Valiant query-binding filter return HTTP 400 with structured `QueryError` entries when values cannot be converted or a client uses a disabled format. Each entry identifies a `Path`, stable `Code`, human-readable `Message`, and `Kind` (`Validation` or `Configuration`).\n\n## Configure accepted formats\n\n```csharp\nbuilder.Services.AddValiantEndpoints(options =>\n{\n    options.QueryParameters.EnableBinding = true;\n    options.QueryParameters.Parsing = new QueryParsingOptions\n    {\n        SupportedArrayFormats =\n        [\n            QueryArrayFormat.RepeatedKeys,\n            QueryArrayFormat.CommaSeparated\n        ],\n        SupportedObjectFormats =\n        [\n            QueryObjectFormat.Flat,\n            QueryObjectFormat.DotNotation\n        ]\n    };\n});\n```\n\nReplace the global parsing rules for whole-request and `[AsParameters]` binding on one endpoint when needed:\n\n```csharp\nreturn builder.MapGet(\"/search\", Handle)\n    .WithQueryParsingOptions(new QueryParsingOptions\n    {\n        SupportedObjectFormats = [QueryObjectFormat.Flat],\n        EnableJsonQueryValues = true\n    });\n```\n\nThis is a full replacement, not a merge. Other endpoints continue using the global parsing options.\n\nWhen only selected settings differ, use a partial attribute override:\n\n```csharp\n[ValiantEndpoint]\n[ValiantQueryParsing(\n    SupportedArrayFormats =\n    [\n        QueryArrayFormat.RepeatedKeys,\n        QueryArrayFormat.CommaSeparated\n    ],\n    SupportedObjectFormats =\n    [\n        QueryObjectFormat.Flat,\n        QueryObjectFormat.DotNotation\n    ],\n    JsonValues = JsonQueryValues.Disabled)]\npublic sealed partial class SearchEndpoint : IEndpoint\n{\n    // ...\n}\n```\n\nExplicit attribute properties win over `.WithQueryParsingOptions(...)`, which wins over global parsing options and then defaults. Omitted or `null` array properties inherit; `[]` disables every format in that category. The array and object properties affect full-query binding only. Explicit `JsonValues` affects full-query binding and generated direct complex `[FromQuery]`; when omitted, full-query binding inherits while direct JSON remains enabled.\n\nSee the [query parameter reference](https://valiant.staticnorth.dev/endpoints/reference/query-parameters) for all formats and direct parser/serializer APIs.\n"
    },
    {
      "id": "endpoints/reference/query-parameters",
      "title": "Query parameters",
      "description": "Complete parsing and serialization formats, options, supported values, and structured errors.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/reference/query-parameters",
      "url": "https://valiant.staticnorth.dev/endpoints/reference/query-parameters",
      "markdownUrl": "/markdown/endpoints/reference/query-parameters.md",
      "content": "---\ntitle: \"Query parameters\"\ndescription: \"Complete parsing and serialization formats, options, supported values, and structured errors.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/reference/query-parameters\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Query parameter parsing and serialization\n\nInbound parsing and outbound serialization use separate options. An API can accept several client conventions while emitting one stable format.\n\nGenerated endpoint binding is opt-in and disabled by default:\n\n```csharp\nbuilder.Services.AddValiantEndpoints(options =>\n{\n    options.QueryParameters.EnableBinding = true;\n});\n```\n\nThe direct literal assignment must be in the same compilation as the endpoints so the source generator can add the binding members. Direct calls to `QueryStringParser` and `QueryStringSerializer` do not require endpoint binding to be enabled.\n\n`EnableBinding` is a compile-time opt-in, not a fully dynamic runtime switch. Whole-request `BindAsync` and `[AsParameters]` processing can resolve runtime options, but a generated direct `TryParse(string, out T)` has no `HttpContext`. Once a recognized literal `true` causes that parser to be compiled, another host or runtime override to `false` cannot remove or neutralize it. Compile the endpoint project with no recognized `true` assignment when `[ValiantQueryParsing]` must be ignored.\n\n## Defaults\n\n```csharp\nvar parsing = new QueryParsingOptions\n{\n    SupportedArrayFormats = [QueryArrayFormat.RepeatedKeys],\n    SupportedObjectFormats = [QueryObjectFormat.Flat],\n    EnableJsonQueryValues = false\n};\n\nvar serialization = new QuerySerializationOptions\n{\n    ArrayFormat = QueryArrayFormat.RepeatedKeys,\n    ObjectFormat = QueryObjectFormat.Flat\n};\n```\n\n## Array formats\n\n| Value | Example |\n| --- | --- |\n| `RepeatedKeys` | `?ids=1&ids=2&ids=3` |\n| `CommaSeparated` | `?ids=1,2,3` |\n| `Brackets` | `?ids[]=1&ids[]=2&ids[]=3` |\n| `IndexedBrackets` | `?ids[0]=1&ids[1]=2&ids[2]=3` |\n\nEnable every accepted inbound format explicitly:\n\n```csharp\nnew QueryParsingOptions\n{\n    SupportedArrayFormats =\n    [\n        QueryArrayFormat.RepeatedKeys,\n        QueryArrayFormat.CommaSeparated,\n        QueryArrayFormat.Brackets,\n        QueryArrayFormat.IndexedBrackets\n    ]\n};\n```\n\nRepeated and bracket values preserve query order; indexed brackets sort by numeric index. Empty items and disabled formats return structured errors.\n\n## Object formats\n\n| Value | Example |\n| --- | --- |\n| `Flat` | `?brand=tesla&year=2025` |\n| `DotNotation` | `?filter.brand=tesla&filter.year=2025` |\n| `DeepObject` | `?filter[brand]=tesla&filter[year]=2025` |\n\nDuplicate scalar values use the last value. Flat output cannot preserve nested paths; choose dot notation, deep object, or explicitly enabled JSON for nested serialization.\n\n## JSON query values\n\n`QueryStringParser` and generated whole-request binding disable JSON by default. Opt in only for endpoints that intentionally accept URL-encoded JSON objects:\n\n```csharp\nnew QueryParsingOptions { EnableJsonQueryValues = true };\n```\n\nFor a single mapped endpoint using generated whole-request or `[AsParameters]` binding, replace the global parsing policy:\n\n```csharp\nreturn builder.MapGet(\"/search\", Handle)\n    .WithQueryParsingOptions(new QueryParsingOptions\n    {\n        SupportedObjectFormats = [QueryObjectFormat.Flat],\n        EnableJsonQueryValues = true\n    });\n```\n\nFor `[AsParameters]`, the policy is applied after ASP.NET Core has performed native property binding. Formats that fail that initial conversion, such as comma-separated input for an `int[]` property, require generated whole-request binding instead.\n\nFor a partial source-generated override, place `[ValiantQueryParsing]` on the endpoint class:\n\n```csharp\n[ValiantEndpoint]\n[ValiantQueryParsing(\n    SupportedArrayFormats =\n    [\n        QueryArrayFormat.RepeatedKeys,\n        QueryArrayFormat.CommaSeparated\n    ],\n    SupportedObjectFormats =\n    [\n        QueryObjectFormat.Flat,\n        QueryObjectFormat.DotNotation\n    ],\n    JsonValues = JsonQueryValues.Disabled)]\npublic sealed partial class SearchEndpoint : IEndpoint\n{\n    // ...\n}\n```\n\nPrecedence is explicit attribute properties, then the last `.WithQueryParsingOptions(...)` call, then global `QueryParameters.Parsing`, then defaults. Omitted or `null` array properties inherit; `[]` accepts no formats in that category. `SupportedArrayFormats` and `SupportedObjectFormats` affect full-query binding only. `JsonValues` affects full-query binding when explicitly named and always controls generated direct complex `[FromQuery]` parsers.\n\nFor example, direct complex `[FromQuery]` parameters can disable their generated JSON parser with the same attribute:\n\n```csharp\n[ValiantEndpoint]\n[ValiantQueryParsing(JsonValues = JsonQueryValues.Disabled)]\npublic sealed class SearchEndpoint : IEndpoint\n{\n    public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) =>\n        builder.MapGet(\"/search\", static ([FromQuery] SearchRequest request) => Results.Ok(request));\n}\n```\n\nWhen the endpoint project is compiled with `options.QueryParameters.EnableBinding = false`, the whole attribute is ignored and no Valiant query parser is generated. A later runtime-only override cannot change an already-generated direct parser. When binding is enabled, no attribute and `[ValiantQueryParsing]` both leave JSON enabled for the generated direct parser. Explicit `Disabled` returns HTTP 400 without a Valiant direct-query filter. Array and object format properties do not affect direct parameters. User-authored `TryParse` methods remain user-controlled, and conflicting policies for the same generated parser type report `VLE011`.\n\n```http\n?filter=%7B%22brand%22%3A%22tesla%22%2C%22year%22%3A2025%7D\n```\n\n## Direct parsing\n\n```csharp\nvar result = QueryStringParser.Parse<SearchQuery>(\n    \"?ids=1,2,3&filter.brand=tesla\",\n    new QueryParsingOptions\n    {\n        SupportedArrayFormats =\n        [\n            QueryArrayFormat.RepeatedKeys,\n            QueryArrayFormat.CommaSeparated\n        ],\n        SupportedObjectFormats =\n        [\n            QueryObjectFormat.Flat,\n            QueryObjectFormat.DotNotation\n        ]\n    });\n\nif (!result.IsSuccess)\n{\n    foreach (var error in result.Errors)\n    {\n        Console.WriteLine($\"{error.Path} [{error.Code}] {error.Message}\");\n    }\n}\n```\n\nPrimitive arrays and `List<T>` support `string`, `int`, `long`, `Guid`, `bool`, `decimal`, and `DateTime`; nullable primitive scalars are supported. Nested object binding supports at least one level.\n\n## Direct serialization\n\n```csharp\nvar result = QueryStringSerializer.Serialize(\n    new\n    {\n        ids = new[] { 1, 2, 3 },\n        filter = new { brand = \"tesla\", year = 2025 }\n    },\n    new QuerySerializationOptions\n    {\n        ArrayFormat = QueryArrayFormat.CommaSeparated,\n        ObjectFormat = QueryObjectFormat.DotNotation\n    });\n\n// ?ids=1,2,3&filter.brand=tesla&filter.year=2025\n```\n\nThe serializer URL-encodes keys and values, preserves array order, and skips null values. It never negotiates an output format: one array and one object format are selected explicitly.\n\n## Structured errors\n\n`QueryErrorKind.Validation` means the supplied value or target shape is invalid—for example, an invalid `Guid`, empty array element, or unsupported type. `QueryErrorKind.Configuration` means the request used a disabled format or serialization options could not represent the requested shape.\n\n```csharp\npublic sealed class QueryError\n{\n    public string Path { get; }\n    public string Code { get; }\n    public string Message { get; }\n    public QueryErrorKind Kind { get; }\n}\n```\n"
    },
    {
      "id": "endpoints/reference/registration-generation",
      "title": "Registration, generation, and diagnostics",
      "description": "Assembly registration, generated mapping, generator scope, ordering, and diagnostics.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/reference/registration-generation",
      "url": "https://valiant.staticnorth.dev/endpoints/reference/registration-generation",
      "markdownUrl": "/markdown/endpoints/reference/registration-generation.md",
      "content": "---\ntitle: \"Registration, generation, and diagnostics\"\ndescription: \"Assembly registration, generated mapping, generator scope, ordering, and diagnostics.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/reference/registration-generation\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Registration, generation, and diagnostics\n\n## Default discovery\n\n`AddValiantEndpoints()` registers generated route registrars from the calling and entry assemblies. `MapValiantEndpoints()` resolves every registered registrar.\n\n## Explicit assemblies\n\nUse explicit overloads when endpoints live in feature libraries:\n\n```csharp\nbuilder.Services.AddValiantEndpoints(\n    typeof(OrdersEndpoint).Assembly,\n    typeof(BillingEndpoint).Assembly);\n\napp.MapValiantEndpoints();\n```\n\nExplicit assembly selection changes registration only. Endpoint mapping always uses the same `MapValiantEndpoints()` entry point, so generated mapping policy and conventions have one consistent execution path.\n\n## Generator scope\n\nThe incremental generator starts from marker attributes—not an assembly-wide interface scan:\n\n- `[ValiantEndpoint]` or `[ValiantEndpoint<TGroup>]` generates endpoint registration;\n- `[ValiantEndpointGroup]` generates group registration;\n- partial query request/type declarations receive binders only when query binding is explicitly enabled and they are referenced from generated endpoint methods.\n\nThe companion analyzer checks only direct `IEndpoint` and `IEndpointGroup` declarations for missing markers. It intentionally avoids indirect and aliased implementation scans to keep IDE analysis bounded.\n\n`IEndpointGroup.CreateGroup` is a static abstract interface member. The C# compiler requires every endpoint group type to provide a public static implementation.\n\n## Diagnostics\n\n| ID | Meaning |\n| --- | --- |\n| `VLE001` | Marked endpoint does not implement `IEndpoint` |\n| `VLE002` | A declaration implements both endpoint interfaces |\n| `VLE003` | Endpoint marker was applied to a group |\n| `VLE004` | Declared group type does not implement `IEndpointGroup` |\n| `VLE005` | Marked group does not implement `IEndpointGroup` |\n| `VLE006` | Direct endpoint declaration is missing `[ValiantEndpoint]` |\n| `VLE007` | Direct group declaration is missing `[ValiantEndpointGroup]` |\n| `VLE008` | Group marker was applied to an endpoint |\n| `VLE009` | An endpoint uses more than one endpoint marker form |\n| `VLE010` | A query type cannot receive the generated binder |\n\n`VLE010` covers shapes such as non-partial source types, static types, open generics, or containing types that cannot receive generated members.\n"
    },
    {
      "id": "endpoints/samples",
      "title": "Samples",
      "description": "Run the endpoint-per-class, configuration, conditional registration, and query-binding samples.",
      "module": "endpoints",
      "version": "1",
      "path": "/endpoints/samples",
      "url": "https://valiant.staticnorth.dev/endpoints/samples",
      "markdownUrl": "/markdown/endpoints/samples.md",
      "content": "---\ntitle: \"Samples\"\ndescription: \"Run the endpoint-per-class, configuration, conditional registration, and query-binding samples.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/endpoints/samples\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Endpoint samples\n\nThe runnable host has four startup choices. Select one near the top of\n[`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/Program.cs),\nthen run:\n\n```bash\ndotnet run --project endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples\n```\n\n```csharp\nType? startup;\n\n//startup = typeof(Samples.Basic.Startup);\n//startup = typeof(Samples.Configuration.Startup);\n//startup = typeof(Samples.ConditionalRegistration.Startup);\nstartup = typeof(Samples.QueryBinding.Startup);\n```\n\nEndpoint discovery is assembly-wide. Every attributed endpoint in the sample\nproject contributes generated registration code; the selected startup controls\nthe global options and conventions applied when those registrations are mapped.\n\n## Available startups\n\n| Startup | Demonstrates | Source |\n| --- | --- | --- |\n| `Basic.Startup` | Default discovery and mapping for a standalone endpoint and an endpoint group | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/Basic) |\n| `Configuration.Startup` | `ConfigureEndpointGroup`, `ConfigureEndpoint`, and descriptor-based guards using group and endpoint metadata | [`Configuration`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/Configuration) |\n| `ConditionalRegistration.Startup` | Independent `MapEndpointGroupsWhen` and `MapEndpointWhen` policies, including allowed and rejected registrations | [`ConditionalRegistration`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/ConditionalRegistration) |\n| `QueryBinding.Startup` | Generated query binding for arrays, objects, JSON values, and supported query formats | [`QueryBinding`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/QueryBinding) |\n\nEvery startup registers and maps the generated route plan through\n`AddValiantEndpoints()` and `MapValiantEndpoints()`.\n\n## Configuration hooks\n\nThe configuration startup applies one convention to both endpoints in its group\nand a second convention only to `SelectedEndpoint`:\n\n| Route | `X-Valiant-Group` | `X-Valiant-Endpoint` |\n| --- | --- | --- |\n| `/configuration/selected` | `ConfigurationEndpointGroup` | `SelectedEndpoint` |\n| `/configuration/group-only` | `ConfigurationEndpointGroup` | not present |\n\nThe hook receives the builder returned by the user-authored mapping method and\nits generated registration descriptor. See\n[Groups and conventions](https://valiant.staticnorth.dev/endpoints/guides/groups-conventions) for the complete\nmapping sequence.\n\n## Conditional registration\n\nThe conditional startup exercises positive and negative cases for both\npredicates:\n\n| Route | Status | Policy demonstrated |\n| --- | --- | --- |\n| `/conditional/groups/allowed/hello` | `200` | group allowed |\n| `/conditional/groups/blocked/hello` | `404` | group rejected |\n| `/conditional/endpoints/allowed` | `200` | standalone endpoint allowed |\n| `/conditional/endpoints/blocked` | `404` | standalone endpoint rejected |\n\nRejecting a group skips its child registrations, so `MapEndpointWhen` is not\nevaluated for those children. These are startup-time registration decisions,\nnot request-time feature checks. See\n[Conditional registration](https://valiant.staticnorth.dev/endpoints/guides/conditional-registration) for descriptor\ndetails and precedence.\n\n## Query binding\n\nThe query-binding startup opts the compilation into generated binding:\n\n```csharp\nservices.AddValiantEndpoints(options =>\n{\n    options.QueryParameters.EnableBinding = true;\n});\n```\n\nIts `/query/*` routes cover array and object formats, direct JSON query values,\nand an endpoint that explicitly disables JSON parsing. See\n[Request binding](https://valiant.staticnorth.dev/endpoints/guides/request-binding) and the\n[query parameter reference](https://valiant.staticnorth.dev/endpoints/reference/query-parameters) before choosing a\nbinding shape.\n"
    },
    {
      "id": "mapping/index",
      "title": "Mapping",
      "description": "Compile-time object mapping with direct generated code, explicit rules, composition, and DI.",
      "module": "mapping",
      "version": "1",
      "path": "/mapping/",
      "url": "https://valiant.staticnorth.dev/mapping/",
      "markdownUrl": "/markdown/mapping.md",
      "content": "---\ntitle: \"Mapping\"\ndescription: \"Compile-time object mapping with direct generated code, explicit rules, composition, and DI.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/mapping/\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Mapping that stays visible\n\nValiant Mapping turns a small mapper declaration into direct C# assignments. It handles conventional members, immutable targets, nested shapes, collections, enums, explicit transformations, conditional rules, and mapper composition—without runtime assembly scanning.\n\n```csharp\nusing StaticNorth.Valiant.Mapping;\n\n[ValiantMapper]\npublic sealed partial class UserMapper : MapperDefinition<User, UserDto>;\n\nvar dto = new UserMapper().Map(user);\n```\n\nThe generated partial class implements `IMapper<User, UserDto>` and exposes a strongly typed `Map(User source)` method.\n\n## Why use it?\n\n| Capability | What Valiant generates |\n| --- | --- |\n| Convention mapping | Direct reads and assignments for compatible public fields and properties |\n| Immutable targets | Constructor arguments for records and constructor-only models |\n| Shape changes | Flattening, unflattening, enum conversion, and reusable nested/collection mappers |\n| Explicit ownership | `Map`, `Ignore`, conditions, fallbacks, and null policy in `Configure` |\n| Runtime selection | Typed mapper, `IMapper` facade, and `IMapperFactory` through generated DI registration |\n| Deployment | A fast generated backend suited to trimming and Native AOT, plus a debuggable backend |\n\n:::tip Start with conventions\nDeclare the mapper and compile. Add `Configure` only when the source and target shapes intentionally differ. Once `Configure` is present, list every target mapping you own explicitly.\n:::\n\n## Documentation map\n\n- [Quick start](https://valiant.staticnorth.dev/mapping/quick-start) — install, declare, register, and call a mapper.\n- [Runnable samples](https://valiant.staticnorth.dev/mapping/samples) — select and run every maintained Mapping scenario.\n- [Convention mapping](https://valiant.staticnorth.dev/mapping/guides/conventions) — records, constructors, flattening, collections, and enums.\n- [Explicit mapping](https://valiant.staticnorth.dev/mapping/guides/explicit-mapping) — transformations, conditions, ignores, fallbacks, and nulls.\n- [Composition and DI](https://valiant.staticnorth.dev/mapping/guides/composition-dependency-injection) — nested mappers, facade, and factory.\n- [Runtime and diagnostics](https://valiant.staticnorth.dev/mapping/reference) — modes, generated scope, warnings, and limitations.\n\nThe [sample catalog](https://valiant.staticnorth.dev/mapping/samples) covers every executable Mapping scenario and\nlinks each one to its self-contained source folder.\n"
    },
    {
      "id": "mapping/quick-start",
      "title": "Quick start",
      "description": "Install StaticNorth.Valiant.Mapping and generate your first object mapper.",
      "module": "mapping",
      "version": "1",
      "path": "/mapping/quick-start",
      "url": "https://valiant.staticnorth.dev/mapping/quick-start",
      "markdownUrl": "/markdown/mapping/quick-start.md",
      "content": "---\ntitle: \"Quick start\"\ndescription: \"Install StaticNorth.Valiant.Mapping and generate your first object mapper.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/mapping/quick-start\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Quick start\n\n## 1. Install\n\n```bash\ndotnet add package StaticNorth.Valiant.Mapping\n```\n\n`StaticNorth.Valiant.Mapping` contains the runtime API and delivers its source generator as an analyzer. No separate generator package is needed.\n\n## 2. Declare the models and mapper\n\n```csharp\nusing StaticNorth.Valiant.Mapping;\n\npublic sealed class User\n{\n    public required string Name { get; init; }\n    public int Age { get; init; }\n}\n\npublic sealed record UserDto(string Name, int Age);\n\n[ValiantMapper]\npublic sealed partial class UserMapper : MapperDefinition<User, UserDto>;\n```\n\nThe mapper must be `partial`. `MapperDefinition<TSource, TTarget>` identifies the pair and the generator fills in the implementation.\n\n## 3. Map\n\n```csharp\nvar mapper = new UserMapper();\nvar dto = mapper.Map(new User { Name = \"Ada\", Age = 36 });\n```\n\nThe mapper can also be consumed through its interface:\n\n```csharp\nIMapper<User, UserDto> mapper = new UserMapper();\nUserDto dto = mapper.Map(user);\n```\n\n## 4. Register with dependency injection\n\nWhen the project references Microsoft dependency-injection abstractions, Valiant generates `AddValiantMappers`:\n\n```csharp\nusing StaticNorth.Valiant.Mapping.DependencyInjection;\n\nbuilder.Services.AddValiantMappers(options =>\n{\n    options.Mode = ValiantMappingMode.Auto;\n    options.NullHandling = ValiantNullHandling.MapNulls;\n});\n```\n\nThen inject the concrete mapper, `IMapper<User, UserDto>`, the non-generic `IMapper`, or `IMapperFactory`.\n\n:::info Generated discovery\nOnly declarations marked with `[ValiantMapper]` enter the generator pipeline. Valiant does not scan every type in your compilation looking for mapping definitions.\n:::\n\nNext: learn what maps automatically in [Convention mapping](https://valiant.staticnorth.dev/mapping/guides/conventions).\n"
    },
    {
      "id": "mapping/guides/composition-dependency-injection",
      "title": "Composition and dependency injection",
      "description": "Reuse generated mappers and choose between typed, facade, and factory APIs.",
      "module": "mapping",
      "version": "1",
      "path": "/mapping/guides/composition-dependency-injection",
      "url": "https://valiant.staticnorth.dev/mapping/guides/composition-dependency-injection",
      "markdownUrl": "/markdown/mapping/guides/composition-dependency-injection.md",
      "content": "---\ntitle: \"Composition and dependency injection\"\ndescription: \"Reuse generated mappers and choose between typed, facade, and factory APIs.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/mapping/guides/composition-dependency-injection\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Composition and dependency injection\n\n## Reuse another mapper\n\nConstructor-inject the generated mapper and attach it to a member mapping:\n\n```csharp\n[ValiantMapper]\npublic sealed partial class AddressMapper\n    : MapperDefinition<Address, AddressDto>;\n\n[ValiantMapper]\npublic sealed partial class UserMapper(AddressMapper addressMapper)\n    : MapperDefinition<User, UserDto>\n{\n    public override void Configure(MappingContext<User, UserDto> context)\n    {\n        context.Map(source => source.Address, target => target.Address)\n            .UseMapper(addressMapper);\n    }\n}\n```\n\n`UseMapper` can be called on the context or in a fluent mapping chain. It makes nested object and collection-element conversion explicit and keeps each pair independently testable.\n\n## Generated registration\n\n```csharp\nusing StaticNorth.Valiant.Mapping.DependencyInjection;\n\nbuilder.Services.AddValiantMappers();\n```\n\nValiant registers each mapper as its concrete type and as `IMapper<TSource, TTarget>`. It also registers `IMapper` and `IMapperFactory`. Mapper registrations are transient; the facade, factory, and options are singleton services.\n\n## Choose an API\n\n### Typed mapper\n\nUse the typed interface when the pair is known at compile time:\n\n```csharp\npublic sealed class UserHandler(IMapper<User, UserDto> mapper)\n{\n    public UserDto Handle(User user) => mapper.Map(user);\n}\n```\n\n### Non-generic facade\n\nUse `IMapper` when the source arrives as `object` but the target is known or supplied dynamically:\n\n```csharp\nUserDto dto = mapper.Map<UserDto>(source);\n\nif (mapper.TryMap(source, typeof(UserDto), out var value))\n{\n    // value is the mapped object.\n}\n```\n\n### Factory\n\nUse `IMapperFactory` when you need the mapper instance itself:\n\n```csharp\nvar typed = factory.CreateMapper<User, UserDto>();\n\nif (factory.TryCreateMapper(typeof(User), typeof(UserDto), out var mapper))\n{\n    // mapper is the registered IMapper<User, UserDto> instance.\n}\n```\n\nCalls to `CreateMapper`/`Map` for a statically knowable unregistered pair produce analyzer diagnostics. Use the `Try...` APIs when absence is expected.\n"
    },
    {
      "id": "mapping/guides/conventions",
      "title": "Convention mapping",
      "description": "Map compatible members, records, constructors, nested shapes, collections, and enums by convention.",
      "module": "mapping",
      "version": "1",
      "path": "/mapping/guides/conventions",
      "url": "https://valiant.staticnorth.dev/mapping/guides/conventions",
      "markdownUrl": "/markdown/mapping/guides/conventions.md",
      "content": "---\ntitle: \"Convention mapping\"\ndescription: \"Map compatible members, records, constructors, nested shapes, collections, and enums by convention.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/mapping/guides/conventions\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Convention mapping\n\nWith no `Configure` override, Valiant maps public readable source fields and properties to public writable target fields, properties, or constructor parameters.\n\n## Matching members\n\nNames are matched case-insensitively. Compatible values are assigned directly:\n\n```csharp\npublic sealed class Order\n{\n    public Guid Id { get; init; }\n    public decimal Total { get; init; }\n}\n\npublic sealed class OrderDto\n{\n    public Guid Id { get; init; }\n    public decimal Total { get; init; }\n}\n\n[ValiantMapper]\npublic sealed partial class OrderMapper : MapperDefinition<Order, OrderDto>;\n```\n\n## Records and constructors\n\nConstructor parameters are mapped before writable members, so immutable targets work naturally:\n\n```csharp\npublic sealed record OrderDto(Guid Id, decimal Total);\n```\n\nValiant chooses a usable public constructor and reports a compile-time diagnostic when the target cannot be constructed or a required member cannot be supplied.\n\n## Flattening and unflattening\n\nConcatenated member paths can bridge nested and flat shapes:\n\n```csharp\npublic sealed class User\n{\n    public required Address Address { get; init; }\n}\n\npublic sealed class Address\n{\n    public required string City { get; init; }\n}\n\npublic sealed class UserDto\n{\n    public required string AddressCity { get; init; }\n}\n```\n\nThe reverse shape is supported when a flat source member can populate a nested target path. Prefer explicit mapping when concatenated names could be ambiguous.\n\n## Enums\n\nEnums with compatible values map between enum types. Treat cross-domain enum contracts carefully: an explicit transformation is clearer when numeric values can drift independently.\n\n## Nested objects and collections\n\nRegister a mapper for the element or nested pair, then reuse it from the parent mapper:\n\n```csharp\n[ValiantMapper]\npublic sealed partial class LineMapper : MapperDefinition<OrderLine, OrderLineDto>;\n\n[ValiantMapper]\npublic sealed partial class OrderMapper(LineMapper lineMapper)\n    : MapperDefinition<Order, OrderDto>\n{\n    public override void Configure(MappingContext<Order, OrderDto> context)\n    {\n        context.Map(source => source.Lines, target => target.Lines)\n            .UseMapper(lineMapper);\n    }\n}\n```\n\nValiant can apply the reusable mapper to compatible nested values and collection elements. See [Composition and dependency injection](https://valiant.staticnorth.dev/mapping/guides/composition-dependency-injection) for registration details.\n\n:::warning Explicit mode changes ownership\nDeclaring `Configure` disables convention mapping for that mapper. Map or ignore every target member intentionally; diagnostics will identify missing or incompatible targets.\n:::\n"
    },
    {
      "id": "mapping/guides/explicit-mapping",
      "title": "Explicit mapping",
      "description": "Transform, condition, ignore, default, and control null behavior for mapped members.",
      "module": "mapping",
      "version": "1",
      "path": "/mapping/guides/explicit-mapping",
      "url": "https://valiant.staticnorth.dev/mapping/guides/explicit-mapping",
      "markdownUrl": "/markdown/mapping/guides/explicit-mapping.md",
      "content": "---\ntitle: \"Explicit mapping\"\ndescription: \"Transform, condition, ignore, default, and control null behavior for mapped members.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/mapping/guides/explicit-mapping\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Explicit mapping\n\nOverride `Configure` when names differ or a target value needs business-specific shaping:\n\n```csharp\n[ValiantMapper]\npublic sealed partial class UserMapper : MapperDefinition<User, UserDto>\n{\n    public override void Configure(MappingContext<User, UserDto> context)\n    {\n        context\n            .Map(source => source.EmailAddress, target => target.Email)\n            .Map(source => $\"{source.FirstName} {source.LastName}\", target => target.DisplayName)\n            .Ignore(target => target.InternalNote);\n    }\n}\n```\n\n## Conditional chains\n\n`When` applies to every declaration in the same fluent chain:\n\n```csharp\ncontext\n    .Map(source => source.EmailAddress, target => target.Email)\n    .Map(source => source.Phone, target => target.Phone)\n    .When(source => source.IncludeContactDetails);\n```\n\nStart a new statement when rules need different conditions.\n\n## Defaults and fallbacks\n\n`Default` and `Fallback` are aliases. The value is used when a rule is skipped by its condition or ignores a null source value:\n\n```csharp\ncontext.Map(source => source.DisplayName, target => target.DisplayName)\n    .When(source => source.IsVisible)\n    .Fallback(\"Hidden user\");\n```\n\n## Null handling\n\nThe mapper-wide default comes from `ValiantMappingOptions.NullHandling`:\n\n```csharp\nservices.AddValiantMappers(options =>\n    options.NullHandling = ValiantNullHandling.IgnoreSourceNulls);\n```\n\nOverride it per rule:\n\n```csharp\ncontext.Map(source => source.Nickname, target => target.Nickname)\n    .IgnoreNull();\n\ncontext.Map(source => source.AvatarUrl, target => target.AvatarUrl)\n    .MapNull(); // AllowNull() is an alias.\n```\n\n| API | Effect |\n| --- | --- |\n| `IgnoreNull()` | Leave the target value unchanged when the source expression returns `null` |\n| `MapNull()` | Assign `null`, even when mapper options ignore source nulls |\n| `AllowNull()` | Alias for `MapNull()` |\n| `Default(value)` | Use a value when the rule is skipped or a null is ignored |\n| `Fallback(value)` | Alias for `Default(value)` |\n\n## Intentional omissions\n\nUse `Ignore` to document that a writable or required target member is intentionally not populated:\n\n```csharp\ncontext.Ignore(target => target.AuditStamp);\n```\n\nThis is preferable to suppressing an unmapped-member warning because the decision remains beside the rest of the mapping contract.\n\nRun the conditional and null-policy variants from the\n[Mapping sample catalog](https://valiant.staticnorth.dev/mapping/samples).\n"
    },
    {
      "id": "mapping/reference",
      "title": "Runtime, generation, and diagnostics",
      "description": "Mapping modes, generator scope, generated services, diagnostics, and known constraints.",
      "module": "mapping",
      "version": "1",
      "path": "/mapping/reference",
      "url": "https://valiant.staticnorth.dev/mapping/reference",
      "markdownUrl": "/markdown/mapping/reference.md",
      "content": "---\ntitle: \"Runtime, generation, and diagnostics\"\ndescription: \"Mapping modes, generator scope, generated services, diagnostics, and known constraints.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/mapping/reference\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Runtime, generation, and diagnostics\n\n## Runtime options\n\n```csharp\nservices.AddValiantMappers(options =>\n{\n    options.Mode = ValiantMappingMode.Auto;\n    options.NullHandling = ValiantNullHandling.MapNulls;\n});\n```\n\n| Option | Values | Default |\n| --- | --- | --- |\n| `Mode` | `Auto`, `Debuggable`, `Fast` | `Auto` |\n| `NullHandling` | `MapNulls`, `IgnoreSourceNulls` | `MapNulls` |\n\n`Auto` uses the debuggable runtime backend in Debug builds and direct generated mapping in other builds. `Debuggable` executes your `Configure` method at runtime, so breakpoints work; this path uses expression compilation and reflection. `Fast` always uses generated direct mapping code and is the preferred deployment path for trimming and Native AOT.\n\n## Generator scope\n\n`[ValiantMapper]` is the discovery boundary. The incremental generator processes only marked declarations and emits:\n\n- the typed `Map` implementation and `IMapper<TSource, TTarget>` contract;\n- direct member/constructor mapping for the fast backend;\n- mapper registration metadata;\n- `AddValiantMappers` when dependency-injection abstractions are present.\n\nA separate narrowly scoped analyzer checks statically knowable `IMapper` and `IMapperFactory` calls for missing pairs without putting ordinary invocations into the generator graph.\n\n## Diagnostics\n\n| ID | Meaning |\n| --- | --- |\n| `VLM001` | Mapper must be partial |\n| `VLM002` | Mapper shape is unsupported |\n| `VLM003` | Source/target pair cannot be determined |\n| `VLM004` | Mapping declaration syntax is unsupported |\n| `VLM005` | Target cannot be constructed |\n| `VLM006` | Required target member is not mapped |\n| `VLM101` | A target member is not mapped |\n| `VLM102` | A source member exists but its type is incompatible |\n| `VLM104` | More than one default mapper owns the same pair |\n| `VLM105` | `IMapperFactory` call requests an unregistered pair |\n| `VLM106` | `IMapper` facade call requests an unregistered pair |\n\n## Constraints\n\n- Mapper and containing declarations that receive generated members must be `partial`.\n- Each source/target pair has one default generated mapper.\n- Targets need a usable public construction path.\n- `Configure` is intentionally generator-readable; unsupported expression shapes produce `VLM004` instead of silently changing behavior.\n- Use `TryMap` or `TryCreateMapper` for pairs that are optional at runtime.\n"
    },
    {
      "id": "mapping/samples",
      "title": "Samples",
      "description": "Run the convention, explicit, conditional, null, composition, and dependency-injection mapping samples.",
      "module": "mapping",
      "version": "1",
      "path": "/mapping/samples",
      "url": "https://valiant.staticnorth.dev/mapping/samples",
      "markdownUrl": "/markdown/mapping/samples.md",
      "content": "---\ntitle: \"Samples\"\ndescription: \"Run the convention, explicit, conditional, null, composition, and dependency-injection mapping samples.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/mapping/samples\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Mapping samples\n\nSelect one delegate near the top of\n[`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/Program.cs),\nthen run:\n\n```bash\ndotnet run --project mapping/samples/StaticNorth.Valiant.Mapping.Samples\n```\n\n`Program.cs` is intentionally only a selector. Each folder is self-contained,\nand the `Sample` class owns the explanation of the behavior it invokes.\n\n| Delegate | Demonstrates | Source |\n| --- | --- | --- |\n| `Basic.Sample.Run` | The smallest useful mapper: matching members mapped by convention into an immutable constructor target | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/Basic) |\n| `ExplicitMapping.Sample.Run` | A custom source transform, a renamed target member, and an intentionally ignored target member | [`ExplicitMapping`](https://github.com/static-north-dev/valiant/tree/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/ExplicitMapping) |\n| `ConditionalMapping.Sample.Run` | Native `if`/`else`, a chained `When` condition, and the equivalent `Fallback` and `Default` APIs | [`ConditionalMapping`](https://github.com/static-north-dev/valiant/tree/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/ConditionalMapping) |\n| `NullHandling.Sample.Run` | Mapper-wide null policy, `IgnoreNull`, `MapNull`, `AllowNull`, and a fallback for an ignored null | [`NullHandling`](https://github.com/static-north-dev/valiant/tree/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/NullHandling) |\n| `FlatteningAndEnums.Sample.Run` | Convention-based flattening, unflattening, and compatible enum conversion | [`FlatteningAndEnums`](https://github.com/static-north-dev/valiant/tree/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/FlatteningAndEnums) |\n| `Composition.Sample.Run` | Constructor-injected mapper reuse for a nested object and collection elements | [`Composition`](https://github.com/static-north-dev/valiant/tree/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/Composition) |\n| `DependencyInjection.Sample.Run` | Generated registration; typed mapper, non-generic facade, and factory; successful and missing `Try` APIs | [`DependencyInjection`](https://github.com/static-north-dev/valiant/tree/main/mapping/samples/StaticNorth.Valiant.Mapping.Samples/DependencyInjection) |\n\nThe basic and convention samples show what the generator can infer. Samples\nwith a `Configure` override demonstrate behavior supported by both the\ndebuggable runtime backend and the fast generated backend. The dependency\ninjection sample leaves `ValiantMappingMode.Auto` selected, so Debug builds use\nthe debuggable backend and Release builds use generated fast mapping.\n\nContinue with [Convention mapping](https://valiant.staticnorth.dev/mapping/guides/conventions),\n[Explicit mapping](https://valiant.staticnorth.dev/mapping/guides/explicit-mapping), or\n[Composition and dependency injection](https://valiant.staticnorth.dev/mapping/guides/composition-dependency-injection)\nfor the complete contracts and constraints.\n"
    },
    {
      "id": "settings/index",
      "title": "Settings",
      "description": "Generated settings schemas, optional Options binding and validation, and a secure ASP.NET Core explorer.",
      "module": "settings",
      "version": "1",
      "path": "/settings/",
      "url": "https://valiant.staticnorth.dev/settings/",
      "markdownUrl": "/markdown/settings.md",
      "content": "---\ntitle: \"Settings\"\ndescription: \"Generated settings schemas, optional Options binding and validation, and a secure ASP.NET Core explorer.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/settings/\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Settings with a generated contract\n\nValiant Settings turns strongly typed configuration models into deterministic schemas. Use the same generated metadata for Options binding, validation, documentation, tooling, or the built-in ASP.NET Core settings explorer—without reflection-based assembly scanning.\n\n```csharp\nusing StaticNorth.Valiant.Settings;\n\n[ValiantSettings(\"Payments\", configure: true)]\npublic sealed record PaymentSettings\n{\n    public Uri? Endpoint { get; init; }\n\n    [ValiantSecret]\n    public string? ApiKey { get; init; }\n}\n```\n\n## One declaration, several uses\n\n| Capability | Result |\n| --- | --- |\n| Schema | Model, property, nesting, collection, default, nullability, required, and secret metadata |\n| Options | Generated section-aware `Configure<TSettings>` registration on opt-in models |\n| Validation | `IValidateOptions<TSettings>` backed by a generated Valiant validator |\n| UI | Built-in schema explorer and JSON endpoint with safe secret masking |\n| Tooling | `IValiantSettingsSchemaProvider` for custom consumers |\n\n## Documentation map\n\n- [Quick start](https://valiant.staticnorth.dev/settings/quick-start)\n- [Runnable samples](https://valiant.staticnorth.dev/settings/samples)\n- [Schema generation](https://valiant.staticnorth.dev/settings/guides/schema-generation)\n- [Binding and validation](https://valiant.staticnorth.dev/settings/guides/binding-validation)\n- [ASP.NET Core UI](https://valiant.staticnorth.dev/settings/guides/aspnetcore-ui)\n- [Schema API, generation, and diagnostics](https://valiant.staticnorth.dev/settings/reference/schema-api)\n\nThe [sample catalog](https://valiant.staticnorth.dev/settings/samples) covers every selectable core and ASP.NET\nCore scenario for schema metadata, binding, validation, and the safe-by-default\nUI.\n"
    },
    {
      "id": "settings/quick-start",
      "title": "Quick start",
      "description": "Install StaticNorth.Valiant.Settings, generate a schema, and optionally bind Options.",
      "module": "settings",
      "version": "1",
      "path": "/settings/quick-start",
      "url": "https://valiant.staticnorth.dev/settings/quick-start",
      "markdownUrl": "/markdown/settings/quick-start.md",
      "content": "---\ntitle: \"Quick start\"\ndescription: \"Install StaticNorth.Valiant.Settings, generate a schema, and optionally bind Options.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/settings/quick-start\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Quick start\n\n## 1. Choose a package\n\n```bash\n# Schema generation and optional Options binding\ndotnet add package StaticNorth.Valiant.Settings\n\n# Or install a specific integration\ndotnet add package StaticNorth.Valiant.Settings.AspNetCore\ndotnet add package StaticNorth.Valiant.Settings.Validation\n```\n\nSpecific integration packages forward the core runtime, build, and generator assets they depend on. Add multiple integration packages only when the application uses multiple integrations.\n\n## 2. Mark a settings model\n\n```csharp\nusing StaticNorth.Valiant.Settings;\n\n[ValiantSettings(\"Mail\", configure: true)]\npublic sealed record MailSettings\n{\n    public required string Host { get; init; }\n    public int Port { get; init; } = 587;\n\n    [ValiantSecret]\n    public string? Password { get; init; }\n}\n```\n\nThe section path is required. `configure: true` opts this model into generated Options binding; omit it for schema-only metadata.\n\n## 3. Register generated settings\n\n```csharp\nusing StaticNorth.Valiant.Settings.DependencyInjection;\n\nbuilder.Services.AddValiantSettings(builder.Configuration);\n```\n\nThe generated extension binds opted-in models and registers every generated schema provider.\n\n## 4. Consume the options\n\n```csharp\npublic sealed class MailSender(IOptions<MailSettings> options)\n{\n    private readonly MailSettings _settings = options.Value;\n}\n```\n\nOr enumerate schemas:\n\n```csharp\nIEnumerable<IValiantSettingsSchemaProvider> schemas =\n    provider.GetServices<IValiantSettingsSchemaProvider>();\n```\n\nNext: learn how nested models and collections appear in [Schema generation](https://valiant.staticnorth.dev/settings/guides/schema-generation).\n"
    },
    {
      "id": "settings/guides/aspnetcore-ui",
      "title": "ASP.NET Core UI",
      "description": "Map the built-in settings explorer, JSON schema endpoint, runtime values, and secret reveal controls.",
      "module": "settings",
      "version": "1",
      "path": "/settings/guides/aspnetcore-ui",
      "url": "https://valiant.staticnorth.dev/settings/guides/aspnetcore-ui",
      "markdownUrl": "/markdown/settings/guides/aspnetcore-ui.md",
      "content": "---\ntitle: \"ASP.NET Core UI\"\ndescription: \"Map the built-in settings explorer, JSON schema endpoint, runtime values, and secret reveal controls.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/settings/guides/aspnetcore-ui\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# ASP.NET Core UI\n\n`StaticNorth.Valiant.Settings.AspNetCore` provides a compact settings explorer and a JSON document backed by generated schema providers.\n\n```csharp\nusing StaticNorth.Valiant.Settings.AspNetCore;\nusing StaticNorth.Valiant.Settings.DependencyInjection;\n\nbuilder.Services.AddValiantSettings(builder.Configuration);\n\nvar app = builder.Build();\napp.MapValiantSettingsUi();\n```\n\nThe default routes are:\n\n| Route | Purpose |\n| --- | --- |\n| `/_valiant/settings` | Interactive schema explorer |\n| `/_valiant/settings/schemas` | Generated schema JSON document |\n\n## Change the route\n\n```csharp\napp.MapValiantSettingsUi(options =>\n    options.Path = \"/admin/settings\");\n```\n\nThe JSON endpoint follows the prefix at `/admin/settings/schemas`.\n\n## Show current runtime values\n\n```csharp\napp.MapValiantSettingsUi(options =>\n{\n    options.ShowRuntimeValues = true;\n});\n```\n\nRuntime values are resolved dynamically from `IOptions<TSettings>` for registered schemas only. If schema-provider registration is disabled, the UI has no generated catalog to display.\n\n## Protect secrets\n\n`[ValiantSecret]` properties are masked. Valiant also masks common sensitive names such as `Password`, `Secret`, `Token`, `ApiKey`, `ClientSecret`, and `ConnectionString`.\n\nExplicitly permit reveal only when endpoint authorization and hosting policy make it acceptable:\n\n```csharp\nRouteGroupBuilder settings = app.MapValiantSettingsUi(options =>\n{\n    options.ShowRuntimeValues = true;\n    options.AllowSecretReveal = true;\n});\n\nsettings.RequireAuthorization(\"SettingsAdministrators\");\n```\n\nSecret values remain masked until a user selects reveal. The JSON endpoint accepts `?revealSecrets=true` only when `AllowSecretReveal` is enabled.\n\nMasked secret getters are not evaluated. Runtime values are projected through the generated schema: recursive objects beyond the schema boundary become empty objects, and unsupported opaque values become `null`. Options or getter failures return a generic message so exception text cannot expose credentials. Schema responses use `Cache-Control: no-store`, including when secrets are revealed.\n\nDirect callers of `ValiantSettingsSchemaDocumentFactory.Create` must also enable both `revealSecrets` and `canRevealSecrets` to reveal values.\n\n:::danger Treat the explorer as an administrative endpoint\nThe package does not decide your authorization policy. Protect the returned `RouteGroupBuilder`, especially when runtime values or secret reveal are enabled.\n:::\n\nRun the default UI, custom authorization, runtime-value masking, and explicit\nsecret-reveal variants from the [Settings sample catalog](https://valiant.staticnorth.dev/settings/samples#aspnet-core-settings).\n"
    },
    {
      "id": "settings/guides/binding-validation",
      "title": "Binding and validation",
      "description": "Generate Options binding and validate configured settings through Valiant validators.",
      "module": "settings",
      "version": "1",
      "path": "/settings/guides/binding-validation",
      "url": "https://valiant.staticnorth.dev/settings/guides/binding-validation",
      "markdownUrl": "/markdown/settings/guides/binding-validation.md",
      "content": "---\ntitle: \"Binding and validation\"\ndescription: \"Generate Options binding and validate configured settings through Valiant validators.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/settings/guides/binding-validation\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Binding and validation\n\n## Generated Options binding\n\nSet `configure: true` and register settings once:\n\n```csharp\n[ValiantSettings(\"Storage:S3\", configure: true)]\npublic sealed record S3Settings\n{\n    public required string Bucket { get; init; }\n    public string? Region { get; init; }\n}\n\nbuilder.Services.AddValiantSettings(builder.Configuration);\n```\n\nValiant emits the equivalent section-aware `services.Configure<S3Settings>(configuration.GetSection(\"Storage:S3\"))` registration.\n\nSchema providers register by default. Disable them when the application only needs binding and validation:\n\n```csharp\nbuilder.Services.AddValiantSettings(builder.Configuration, options =>\n{\n    options.RegisterSchemaProviders = false;\n});\n```\n\n## Validate Options with Valiant\n\nReference `StaticNorth.Valiant.Settings.Validation` and declare the matching validator:\n\n```csharp\n[ValiantValidator]\npublic sealed partial class S3SettingsValidator\n    : ValidatorDefinition<S3Settings>\n{\n    public override void Configure(ValidationContext<S3Settings> context)\n    {\n        context.Property(settings => settings.Bucket).Required();\n        context.Property(settings => settings.Region).MaxLength(32);\n    }\n}\n```\n\nRegister validators and enable the adapter:\n\n```csharp\nbuilder.Services.AddValiantValidators();\nbuilder.Services.AddValiantSettings(builder.Configuration, options =>\n{\n    options.ValidateWithValiant = true;\n});\n```\n\nGenerated settings registration adds `IValidateOptions<S3Settings>` for configured settings models. It resolves a matching `IValidator<S3Settings>` from DI and translates Valiant errors to normal Options validation failures.\n\n## Require matching validators\n\nBy default, validation succeeds when no validator is registered. Make missing validators a configuration error:\n\n```csharp\nbuilder.Services.AddValiantSettings(builder.Configuration, options =>\n{\n    options.ValidateWithValiant = true;\n    options.RequireValidators = true;\n});\n```\n\nOnly models with `configure: true` receive Options binding and validation adapters. Schema-only models remain metadata contracts.\n"
    },
    {
      "id": "settings/guides/schema-generation",
      "title": "Schema generation",
      "description": "Describe nested settings, collections, defaults, nullability, configuration keys, and secrets.",
      "module": "settings",
      "version": "1",
      "path": "/settings/guides/schema-generation",
      "url": "https://valiant.staticnorth.dev/settings/guides/schema-generation",
      "markdownUrl": "/markdown/settings/guides/schema-generation.md",
      "content": "---\ntitle: \"Schema generation\"\ndescription: \"Describe nested settings, collections, defaults, nullability, configuration keys, and secrets.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/settings/guides/schema-generation\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Schema generation\n\n`[ValiantSettings]` is the generator discovery boundary. It produces a deterministic `ValiantSettingsSchema` for the marked type.\n\n```csharp\n[ValiantSettings(\"Search\")]\npublic sealed record SearchSettings\n{\n    public required Uri Endpoint { get; init; }\n    public SearchRetrySettings Retry { get; init; } = new();\n    public string[] Indexes { get; init; } = [];\n}\n\npublic sealed record SearchRetrySettings\n{\n    public int Attempts { get; init; } = 3;\n    public TimeSpan Delay { get; init; } = TimeSpan.FromSeconds(1);\n}\n```\n\nThe model schema contains its CLR type, display name, section path, and ordered property schemas. Each property records:\n\n- CLR name and configuration key;\n- type display name and normalized kind;\n- required and nullable flags;\n- secret flag and known default value;\n- nested object properties or collection item schema.\n\nPublic instance properties with public getters are included, including inherited properties. The most derived declaration wins when a property is overridden or hidden. Overrides retain an inherited `[ValiantSecret]` marker.\n\n## Property kinds\n\n| Kind | Represents |\n| --- | --- |\n| `String` | Text and string-like configuration values |\n| `Boolean` | Boolean values |\n| `Integer` | Integral numeric values |\n| `Number` | Floating-point and decimal values |\n| `Enum` | Enum values |\n| `Object` | Nested settings object |\n| `Array` | Array or collection with an item schema |\n| `Unknown` | A type without a more specific schema classification |\n\n## Schema-only or configured\n\nSchema generation always occurs. Binding is opt-in:\n\n```csharp\n[ValiantSettings(\"Features\")]\npublic sealed record FeatureCatalog; // schema only\n\n[ValiantSettings(\"Features\", configure: true)]\npublic sealed record BoundFeatureCatalog; // schema + Options binding\n```\n\nThis lets libraries publish metadata without changing the host's service graph.\n\n## Secret metadata\n\n```csharp\n[ValiantSecret]\npublic string? ClientSecret { get; init; }\n```\n\n`ValiantSecret` tells schema consumers that runtime values must be hidden. The ASP.NET Core UI also masks common sensitive names defensively, but explicit attributes are the durable contract for custom tools.\n\n:::info Deterministic output\nGenerated schemas are stable enough for tooling to sort, diff, cache, and render. No runtime type scan is required to discover marked settings models.\n:::\n"
    },
    {
      "id": "settings/reference/schema-api",
      "title": "Schema API, generation, and diagnostics",
      "description": "Consume generated settings metadata programmatically and understand package flow and generator constraints.",
      "module": "settings",
      "version": "1",
      "path": "/settings/reference/schema-api",
      "url": "https://valiant.staticnorth.dev/settings/reference/schema-api",
      "markdownUrl": "/markdown/settings/reference/schema-api.md",
      "content": "---\ntitle: \"Schema API, generation, and diagnostics\"\ndescription: \"Consume generated settings metadata programmatically and understand package flow and generator constraints.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/settings/reference/schema-api\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Schema API, generation, and diagnostics\n\n## Provider contract\n\nEach generated provider implements:\n\n```csharp\npublic interface IValiantSettingsSchemaProvider\n{\n    Type SettingsType { get; }\n    string? SectionPath { get; }\n    ValiantSettingsSchema Schema { get; }\n}\n```\n\nResolve all providers to build custom documentation, editors, configuration audits, or deployment tooling:\n\n```csharp\nforeach (var provider in services.GetServices<IValiantSettingsSchemaProvider>())\n{\n    Console.WriteLine($\"{provider.Schema.Name}: {provider.SectionPath}\");\n\n    foreach (var property in provider.Schema.Properties)\n    {\n        Console.WriteLine($\"  {property.ConfigurationKey} ({property.Kind})\");\n    }\n}\n```\n\n## Model schema\n\n`ValiantSettingsSchema` exposes `SettingsType`, `Name`, `SectionPath`, and `Properties`.\n\n`ValiantSettingsPropertySchema` exposes:\n\n- `Name`, `ConfigurationKey`, and `TypeName`;\n- `Kind`, `IsRequired`, `IsNullable`, and `IsSecret`;\n- `DefaultValue` when it is known at generation time;\n- `Item` for arrays/collections;\n- `Properties` for nested objects.\n\n## ASP.NET Core document\n\nThe UI JSON endpoint returns `ValiantSettingsSchemaDocument`. It contains ordered `ValiantSettingsSchemaEntry` values and indicates whether secrets can be revealed and whether the current response contains revealed values. Each entry can include masked runtime values or a runtime-value resolution error.\n\n## Packages\n\n| Package | Use it for | Target |\n| --- | --- | --- |\n| `StaticNorth.Valiant.Settings` | Schema generation and optional Options binding | .NET 8 and .NET Standard 2.0 |\n| `StaticNorth.Valiant.Settings.AspNetCore` | Built-in explorer and JSON schema endpoint | .NET 8 |\n| `StaticNorth.Valiant.Settings.Validation` | Options validation through Valiant validators | .NET 8 |\n\nIntegration packages forward their parent runtime and generator assets. `StaticNorth.Valiant.Settings.Validation` also carries the core Valiant Validation assets it integrates with.\n\n## Generator scope and diagnostics\n\nOnly types marked with `[ValiantSettings]` enter the incremental generator pipeline. Generated output includes the schema provider and, when the required Microsoft configuration/DI APIs are referenced, the aggregated `AddValiantSettings` registration surface.\n\n| ID | Meaning |\n| --- | --- |\n| `VLS001` | Generic settings model types are not supported |\n| `VLS002` | The settings section path is empty |\n\nThe section path is deliberately required so generated binding and external tooling share one unambiguous configuration identity.\n"
    },
    {
      "id": "settings/samples",
      "title": "Samples",
      "description": "Run the generated schema, Options binding, validation, and ASP.NET Core settings explorer samples.",
      "module": "settings",
      "version": "1",
      "path": "/settings/samples",
      "url": "https://valiant.staticnorth.dev/settings/samples",
      "markdownUrl": "/markdown/settings/samples.md",
      "content": "---\ntitle: \"Samples\"\ndescription: \"Run the generated schema, Options binding, validation, and ASP.NET Core settings explorer samples.\"\nversion: \"1\"\ncanonical: \"https://valiant.staticnorth.dev/settings/samples\"\nsource_revision: \"34222bb7277ce1a771ae4412d572b56f5eb98237\"\n---\n\n# Settings samples\n\nSettings has separate console and ASP.NET Core sample projects. In each project,\nselect one delegate or startup near the top of `Program.cs`.\n\nSettings source generation is assembly-wide. Selecting one scenario changes\nwhich code runs, but every `[ValiantSettings]` model in that project contributes\nto `ValiantSettingsSchemas` and the generated `AddValiantSettings` method. The\nsamples therefore use distinct section paths.\n\n## Core settings\n\nRun the console project:\n\n```bash\ndotnet run --project settings/samples/StaticNorth.Valiant.Settings.Samples\n```\n\nSelect one delegate in\n[`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/settings/samples/StaticNorth.Valiant.Settings.Samples/Program.cs):\n\n| Delegate | Demonstrates | Source |\n| --- | --- | --- |\n| `Basic.Sample.Run` | The normal configured-settings flow: `[ValiantSettings(..., configure: true)]`, `AddValiantSettings(configuration)`, and `IOptions<TSettings>` consumption | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/Basic) |\n| `RegistrationOptions.Sample.Run` | Default schema-provider registration compared with `RegisterSchemaProviders = false`, while configured Options still bind | [`RegistrationOptions`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/RegistrationOptions) |\n| `SchemaRegistry.Sample.Run` | `ValiantSettingsSchemas.All`, `Get<TSettings>`, and successful and unsuccessful `TryGet<TSettings>` lookups | [`SchemaRegistry`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/SchemaRegistry) |\n| `SchemaMetadata.Sample.Run` | Property kinds, nested objects, collections, nullability, required members, and secret metadata | [`SchemaMetadata`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/SchemaMetadata) |\n\n`SchemaMetadata` also shows that a runtime property initializer is not emitted\nas schema `DefaultValue` metadata.\n\n## ASP.NET Core settings\n\nRun the web project:\n\n```bash\ndotnet run --project settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples\n```\n\nSelect one startup type in\n[`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Program.cs):\n\n| Startup | Demonstrates | Source |\n| --- | --- | --- |\n| `Basic.Startup` | `AddValiantSettings()` and the default `/_valiant/settings` explorer and schema routes | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Basic) |\n| `Configuration.Startup` | A custom `/admin/settings` path and authorization conventions on the returned `RouteGroupBuilder` | [`Configuration`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Configuration) |\n| `RuntimeValues.Startup` | `ShowRuntimeValues = true`, explicit secret masking, defensive name-based masking, and reveal disabled | [`RuntimeValues`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/RuntimeValues) |\n| `SecretReveal.Startup` | `AllowSecretReveal = true` with explicit `?revealSecrets=true` opt-in | [`SecretReveal`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/SecretReveal) |\n| `Validation.Startup` | `ValidateWithValiant = true` with permissive behavior when a configured model has no validator | [`Validation`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Validation) |\n| `Validation.InvalidStartup` | Valiant failures translated into `OptionsValidationException` failures | [`Validation`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Validation) |\n| `Validation.RequiredStartup` | `RequireValidators = true` failing when a configured settings model has no matching validator | [`Validation`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Validation) |\n\nThe three validation startups intentionally share one folder because they use\nthe same settings models and validators while exercising different registration\npolicies.\n\n## Try the web scenarios\n\nWith the HTTP launch profile running on port `5194`:\n\n```bash\ncurl -i http://localhost:5194/_valiant/settings\ncurl -i -H \"X-Settings-Admin: true\" http://localhost:5194/admin/settings\ncurl -s http://localhost:5194/runtime-values/schemas\ncurl -s \"http://localhost:5194/secret-reveal/schemas?revealSecrets=true\"\ncurl -i http://localhost:5194/validation/invalid\n```\n\nThe configuration sample uses a deliberately small header-based demo\nauthentication handler. Replace it with the host application's real\nauthentication and authorization policy.\n\nRuntime values and secret reveal are administrative capabilities. Protect the\nreturned route group before enabling either outside local development. See\n[ASP.NET Core UI](https://valiant.staticnorth.dev/settings/guides/aspnetcore-ui) and\n[Binding and validation](https://valiant.staticnorth.dev/settings/guides/binding-validation) for the production\nconfiguration.\n"
    }
  ]
}
