schema

Overview ¶

Package schema provides declarative normalization, defaulting, and validation of Go values.

Types describe their own rules by implementing Schematic. Callers then run those rules with Enforce.

Quick start ¶

type Email string

func (Email) Schema() schema.Schema {
    return schema.String{
        TrimSpace:   true,
        ToLower:     true,
        MustBeEmail: true,
    }
}

type User struct {
    Email Email
    Name  string
}

func (User) Schema() schema.Schema {
    return schema.Object{
        "Email": schema.String{MustNotBeZero: true},
        "Name":  schema.String{MustNotBeZero: true, TrimSpace: true, MinLen: 1},
    }
}

Callers run the schema by calling Enforce (or EnforceAny).

Mutation contract ¶

Enforce uses a mutate-when-possible strategy. When the caller passes a pointer, the pointee is mutated in place by normalizations and defaults; Result.Value holds the same pointer. When the caller passes a value, Go copies it on the function call, so the caller's original variable is unchanged and Result.Value holds the transformed copy. In both cases, Result.Value is the canonical way to read the output.

Two locations cannot be mutated in place even through a pointer input, because Go forbids it: map keys, and values stored by-value inside an interface field. For map keys, the containing map is rebuilt so the normalized key exists; for interface-boxed by-value fields, the new value is boxed back into the slot. Both are transparent to the caller.

Presence and zero vocabulary ¶

Two separate concepts drive rule behavior: nil-ness and zero-ness. Nil-ness is meaningful only for nilable slots (pointers, interfaces, slices, maps). Zero-ness is meaningful for scalar values and is defined per type: the empty string, numeric zero, and so on. Bool does not use zero vocabulary; it uses MustBeTrue and MustBeFalse instead.

The four control flags, applied per type where meaningful, are:

• MustNotBeNil: reject a nil slot.
• MustNotBeZero: reject a zero value after nil handling.
• DefaultIfNil: replace a nil slot with a supplied default.
• DefaultIfZero: replace a zero value after nil handling with a supplied default.

Nil handling runs as a pre-step before leaf rules. On a nil slot: DefaultIfNil (if set) materializes the value and the default flows into the leaf rule; otherwise MustNotBeNil (if set) produces a validation error and leaf processing stops. Every leaf rule therefore operates on a concrete, non-nil value.

Execution order ¶

For each leaf value: (1) nil handling and type dispatch, (2) SkipFunc on the concrete value, (3) normalize (TrimSpace, case, TransformFunc), (4) DefaultIfZero if still zero, (5) write back, (6) value validators, (7) ValidateFunc.

For objects: (1) field rules, (2) TransformFunc, (3) ValidateFunc.