# ADR-001: go-playground/validator as Hidden Backend

**Status:** Accepted
**Date:** 2026-03-18

## Context

Struct validation via struct tags is a well-understood pattern in Go. `github.com/go-playground/validator/v10` is the de-facto standard library for this, supporting a large rule set (`required`, `email`, `min`, `max`, `url`, `uuid`, and hundreds more) and nested struct traversal.

However, directly using the playground `*validate.Validate` type throughout application code creates a hard dependency: its error types (`ValidationErrors`, `InvalidValidationError`) must be imported wherever errors are inspected, and its configuration API leaks into all call sites.

## Decision

`github.com/go-playground/validator/v10` is used as the sole validation backend but is not exposed in the public API.

The public API is the `Validator` interface, which has one method: `Struct(v any) error`. The concrete type `validator` (unexported) holds a `*playground.Validate` instance. The playground package is imported under the alias `playground` to make it unambiguous at a glance which types originate from it.

Callers never see `playground.ValidationErrors` or `*playground.InvalidValidationError` directly. The concrete error types are translated to `*xerrors.Err` inside `Struct()` before being returned.

The playground `*Validate` instance is created once inside `New()` with default options. No custom validators, tag name functions, or struct-level validators are registered. This keeps the API surface small and the behaviour predictable.

## Consequences

- **Positive**: The playground library can be upgraded or replaced without changing any call-site code — only the `valid` package internals change.
- **Positive**: Application code only needs to import `code.nochebuena.dev/go/valid` and `code.nochebuena.dev/go/xerrors`; no direct dependency on `go-playground/validator`.
- **Negative**: Advanced playground features (custom validators, `RegisterTagNameFunc`, cross-field validation) are not accessible without extending the `valid` package. If a project needs them, it should add `Option` functions or methods to `Validator`.
- **Note**: The playground alias `playground "github.com/go-playground/validator/v10"` is retained in the source as a readability aid, not a requirement. It prevents confusion with the package name `valid` used in the surrounding code.