# API validation

This package holds functions which validate fields and types in the Kubernetes
API. It may be useful beyond API validation, but this is the primary goal.

Most of the public functions here have signatures which adhere to the following
pattern, which is assumed by automation and code-generation:

```
import (
        "context"
        "k8s.io/apimachinery/pkg/api/operation"
        "k8s.io/apimachinery/pkg/util/validation/field"
)

func <Name>(ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue <ValueType>, <OtherArgs...>) field.ErrorList
```

The name of validator functions should consider that callers will generally be
spelling out the package name and the function name, and so should aim for
legibility.  E.g. `validate.Concept()`.

The `ctx` argument is Go's usual Context.

The `opCtx` argument provides information about the API operation in question.

The `fldPath` argument indicates the path to the field in question, to be used
in errors.

The `value` and `oldValue` arguments are the thing(s) being validated.  For
CREATE operations (`opCtx.Operation == operation.Create`), the `oldValue`
argument will be nil.  Many validators functions only look at the current value
(`value`) and disregard `oldValue`.

The `value` and `oldValue` arguments are always nilable - pointers to primitive
types, slices of any type, or maps of any type.  Validator functions should
avoid dereferencing nil. Callers are expected to not pass a nil `value` unless the
API field itself was nilable. `oldValue` is always nil for CREATE operations and 
is also nil for UPDATE operations if the `value` is not correlated with an `oldValue`.

Simple content-validators may have no `<OtherArgs>`, but validator functions
may take additional arguments.  Some validator functions will be built as
generics, e.g. to allow any integer type or to handle arbitrary slices.

Examples:

```
// NonEmpty validates that a string is not empty.
func NonEmpty(ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ *string) field.ErrorList

// Even validates that a slice has an even number of items.
func Even[T any](ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ []T) field.ErrorList

// KeysMaxLen validates that all of the string keys in a map are under the
// specified length.
func KeysMaxLen[T any](ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ map[string]T, maxLen int) field.ErrorList
```

Validator functions always return an `ErrorList` where each item is a distinct
validation failure and a zero-length return value (not just nil) indicates
success.

Good validation failure messages follow the Kubernetes API conventions, for
example using "must" instead of "should".