Production Checklist
Use this list before shipping an application that depends on Jeninnet.Validation.
Packages and versions
- [ ] Reference the current preview explicitly (
1.0.0-preview.2) or pin a central version inDirectory.Packages.props. - [ ] Add only the integration packages you use; Core and Abstractions stay framework-free.
- [ ] Keep all Jeninnet.Validation packages on the same version.
- [ ] Read Compatibility and versions before upgrading across previews.
Registration and lifetimes
- [ ] Register every validator as
IValidator<T>; hosts resolve the interface, not the concrete type. - [ ] Validators are stateless after configuration and safe to reuse.
AddGeneratedValidatorsregisters them as scoped; explicit registration can be scoped or singleton. - [ ] Do not capture a scoped service in a singleton validator. Constructor-inject only services with a compatible lifetime.
- [ ] For trimmed or Native AOT deployments, register validators explicitly:
services.AddScoped<CustomerValidator>();
services.AddScoped<IValidator<Customer>, CustomerValidator>();
- [ ] Do not rely on
AddGeneratedValidatorsin AOT; it is annotated[RequiresUnreferencedCode].
Execution path
- [ ] Use
ValidateAsyncwhen the validator containsMustAsync,CustomAsync, async conditions, or async filters. - [ ] Never call sync
Validateon an async-only validator; it throwsAsyncValidatorInvokedSynchronouslyExceptionby design. - [ ] Pass the request cancellation token through the async path.
- [ ] Choose
ValidatevsValidateAndThrowdeliberately.ValidateAndThrowcollects every error before throwing. - [ ] Use
ValidationCallOptionsorValidationStrategyfor per-call rule sets, property filters, cascade, and fail-fast.
Error responses
- [ ] Map validation failures to your API contract once, at the boundary. ASP.NET Core users can
use
AddValidationEndpoints/AddMvcValidationandToProblemErrors. - [ ] Keep
IncludeErrorCodesandIncludeSeveritiesoff unless the client needs them. - [ ] Do not put secrets, SQL, stack traces, or raw user input into custom messages.
- [ ] Confirm
ValidationExceptionis handled and does not escape as a 500. - [ ] Keep ProblemDetails enrichment (
IncludeCorrelationId,IncludeModelType,IncludeDuration) off unless the client contract needs it; correlation ids are request metadata, not user data. - [ ] See Security and data exposure for the threat model.
Observability
- [ ] Add
Jeninnet.Validation.Diagnosticsonly when an exporter or listener is configured; withoutAddValidationDiagnosticsthe sink is null and the core adds no allocation. - [ ] Register the
Jeninnet.ValidationActivitySource/Meter with the OpenTelemetry SDK. - [ ] Keep sampling intentional: metrics are never sampled, tracing can use
SamplingProbability. - [ ] Do not add messages, property values, or custom state to telemetry tags; the package emits only type, validator, rule-set, outcome, and error-count metadata.
Localization
- [ ] Register exactly one
IInnerMessageProviderthroughAddDefaultMessagePacks. - [ ] Add custom packs and overrides through the options callback, not a second provider.
- [ ] Set a
DefaultCultureand verify the fallback chain for unsupported cultures. - [ ] Test at least one right-to-left culture (Arabic) end to end.
- [ ] Keep message keys as constants (
ValidationMessageKeys.*), not literals.
Schema, OpenAPI, and client rules
- [ ] Generate JSON Schema/OpenAPI/client rules from the same descriptors the runtime uses.
- [ ] Treat client rules as advisory data; the server remains authoritative.
- [ ] Verify that conditions export as
hasCondition, not as executable predicates. - [ ] Check custom JSON naming policies (
snake_case,kebab-case) against the OpenAPI transformer’s case-insensitive matching. - [ ] Version the client-rules payload (
schemaVersion) and ship it with the client.
AOT and trimming
- [ ] Publish with
PublishTrimmed/ Native AOT in CI, not only locally. - [ ] Run the published binary; a successful publish is not enough.
- [ ] Keep reflection-based integrations (DataAnnotations, Blazor) out of the AOT claim unless you have tested them.
- [ ] Use
samples/Jeninnet.Validation.AotSmokeas the reference harness.
Testing
- [ ] Cover a valid model and every member’s invalid case.
- [ ] Cover rule sets, conditions, dependent rules, and cascade behavior.
- [ ] Cover async rules on the async path.
- [ ] Cover generated/fluent parity when both authoring styles exist.
- [ ] Use
Jeninnet.Validation.Assertionsfor readable failures; it is test-framework agnostic. - [ ] Add an integration test for each host adapter you ship (ASP.NET Core, MediatR, Blazor, MVC).
Performance
- [ ] Measure in Release, after warmup.
- [ ] Keep the happy path allocation-free; use the allocation audit as the contract.
- [ ] Avoid allocating closures or formatting strings inside hot custom predicates.
- [ ] Benchmark your own validators if they are on a critical path; the built-in benchmarks are a baseline, not a guarantee for custom rules.
Operations
- [ ] Log validation failures at the boundary with a correlation ID, not the full payload.
- [ ] Add
Jeninnet.Validation.Diagnosticswhen you want built-inActivitySource/Meterinstrumentation; otherwise add your own counters/histograms at the boundary. - [ ] Monitor 400 rates separately from 500 rates.
- [ ] Alert on
AsyncValidatorInvokedSynchronouslyException; it indicates a wrong execution path. - [ ] Keep the package version and the documentation version in sync.
- [ ] Run the repository gates if you contribute changes: build, tests, format, docs checks.
Release gate
| Gate | Command |
|---|---|
| Build | dotnet build Jeninnet.Validation.slnx |
| Tests | dotnet test Jeninnet.Validation.slnx |
| Format | dotnet format Jeninnet.Validation.slnx --verify-no-changes --severity info |
| Docs links | pwsh scripts/docs/check-doc-links.ps1 |
| README claims | pwsh scripts/docs/check-readme-claims.ps1 |
| Arabic text | pwsh scripts/docs/check-arabic-text.ps1 |
| AOT smoke | dotnet publish samples/Jeninnet.Validation.AotSmoke/... -c Release -r linux-x64 |