go-codex

GO Codex

What is go-codex?

In standard Go, encoding, decoding, validation, and documentation are separate concerns that drift apart. Rename a field and you must update struct tags, the validator, and the schema docs independently — one missed update causes a silent bug or a stale spec.

go-codex is inspired by Haskell's autodocodec. A single Codec[T] value is the source of truth for encode, decode, validation, and schema — written once, never duplicated.

The Problem

// Three separate sources of truth — they drift.
type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func decodeUser(data []byte) (User, error) {
    var u User
    return u, json.Unmarshal(data, &u) // no validation
}

func validateUser(u User) error {
    if u.Name == "" {
        return errors.New("name: must not be empty")
    }
    if u.Age <= 0 {
        return errors.New("age: must be positive")
    }
    return nil
}

// Schema lives in a separate openapi.yaml — updated by hand.

The Solution

// One Codec[User] is encode + decode + validate + schema.
type User struct {
    Name string
    Age  int
}

var UserCodec = codex.Struct[User](
    codex.Field[User, string]{
        Name:     "name",
        Codec:    codex.String().Refine(validate.NonEmptyString),
        Get:      func(u User) string { return u.Name },
        Set:      func(u *User, v string) { u.Name = v },
        Required: true,
    },
    codex.Field[User, int]{
        Name:     "age",
        Codec:    codex.Int().Refine(validate.PositiveInt),
        Get:      func(u User) int { return u.Age },
        Set:      func(u *User, v int) { u.Age = v },
        Required: true,
    },
)

// Decode and validate in one step — error includes field path.
user, err := UserCodec.Decode(map[string]any{"name": "Alice", "age": 30})

// Encode back to the intermediate representation.
data, err := UserCodec.Encode(user)

// Schema derived automatically — no separate YAML needed.
schemaJSON, _ := json.MarshalIndent(UserCodec.Schema, "", "  ")

Shared Contract

go-codex codecs are plain Go values — they can live in a shared package and be imported by any number of services.

pkg/contract/
    user.go       ← UserCodec, CreateUserRequestCodec, ...

// server — decodes and validates incoming payloads
import "yourorg/pkg/contract"

user, err := contract.UserCodec.Decode(raw) // invalid input is rejected

// client — encodes outgoing payloads; generates OpenAPI spec from the same codec
spec, _ := openapi.MarshalYAML(map[string]schema.Schema{
    "User": contract.UserCodec.Schema,
})

A field rename in contract.User breaks compilation on both sides immediately — no stale YAML, no schema drift, no separate code-generation step. This is the key difference from protobuf or OpenAPI-first workflows: the Go source is the contract.

Installation & Usage

go get github.com/DaniDeer/go-codex@latest

Requires Go 1.25 or later.

Import paths

Features

• Multi-Format Support — one Codec[T] reads and writes JSON, YAML, and TOML unchanged
• Encode, Decode, and Validation — constraints run on decode; encode is trusted; validate is explicit
• Builtin Format Constraints — email, uuid, url, date, date-time validated and reflected into schema automatically
• Protocol Path/Topic Constraints — validate.HTTPPath, validate.MQTTPublishTopic, validate.MQTTTopic validate path and topic strings; compose with custom constraints via WithPathConstraints / WithTopicConstraints
• Rich Codec Types — primitives, Time/Date, Nullable[T], Bytes, SliceOf[T], StringMap[V], structs, tagged unions
• Structured Decode Errors — all failure types are concrete structs (ValidationErrors, ConstraintError, TypeMismatchError, ElementError, KeyError, UnknownVariantError, VariantError); use errors.As to inspect them, or pass them directly to log/slog
• OpenAPI Schema Generation — components/schemas map from codec-derived schemas, no manual YAML
• Full OpenAPI 3.1 Document — complete REST API spec (paths, operations, params) from route.Route descriptors
• AsyncAPI 2.6 Document — complete event-driven spec from channel descriptors; same schemas, no duplication
• REST API Builder — typed Decode/Encode helpers per route + OpenAPI spec generation; immediate path validation; BuildPath for runtime path construction with per-variable codec checks
• Event Channel Builder — typed Decode/Encode helpers per channel + AsyncAPI spec generation; immediate topic validation; BuildTopic for runtime topic construction with per-variable codec checks
• net/http Adapter — wire RouteHandle to net/http.ServeMux with one call; 400/500 error handling included
• Paho MQTT Adapter — wire ChannelHandle to Paho MQTT subscribe callbacks; unified Publish handles both static and template topics

Multi-Format Support

Codec[T] operates on an intermediate representation (map[string]any) that is format-agnostic. The format package bridges that intermediate to concrete wire formats — the same codec reads and writes JSON, YAML, and TOML unchanged.

jsonFmt := format.JSON(UserCodec)
yamlFmt := format.YAML(UserCodec)
tomlFmt := format.TOML(UserCodec)

// All three produce identical Go values; validation runs on all three.
user, err := jsonFmt.Unmarshal([]byte(`{"name":"Alice","age":30}`))
user, err  = yamlFmt.Unmarshal([]byte("name: Alice\nage: 30\n"))
user, err  = tomlFmt.Unmarshal([]byte("name = \"Alice\"\nage = 30\n"))

// Encode to any format.
jsonBytes, _ := jsonFmt.Marshal(user)
tomlBytes, _ := tomlFmt.Marshal(user)

Validation errors and field paths are identical regardless of which format is used.

Encode, Decode, and Validation

The trust boundary

go-codex draws a deliberate line between trusted and untrusted data:

This mirrors the design of autodocodec: constraints are a guard on ingress, not a restriction on your own domain logic.

Decode — validates automatically

// Constraints run during Decode. Invalid input is rejected with field-path errors.
user, err := jsonFmt.Unmarshal([]byte(`{"name":"","age":-5}`))
// err: field name: constraint failed (non-empty): expected non-empty string

Encode — trusted, no constraints

// Encoding the value you constructed always succeeds (no constraints run).
// You are responsible for the correctness of values you build.
data, err := jsonFmt.Marshal(User{Name: "", Age: -5}) // succeeds

Validate — explicit bidirectional check

When you need to validate a Go value you constructed — before storing it, after building it programmatically, or to surface errors early — call Validate explicitly. It reuses the exact same Refine constraints, with no duplication:

// Codec.Validate — no format required.
if err := UserCodec.Validate(u); err != nil {
    return fmt.Errorf("constructed invalid user: %w", err)
}

// Format.Validate — same check, accessed through a Format binding.
if err := jsonFmt.Validate(u); err != nil {
    return err
}

Validate is always explicit. Marshal and Encode never silently validate.

New — smart constructor

Codec.New validates and returns the value in a single call. Use it as a smart constructor when you want to create a validated domain value from a Go value:

// Validate + return in one call.
email, err := emailCodec.New(Email("user@example.com"))
if err != nil {
    return err
}
// email is guaranteed valid here

New is equivalent to calling Validate and then returning the original value. It is a thin wrapper — no new constraint logic.

Must — panic on invalid (for constants and test data)

codex.Must is a generic panic-on-error helper, following the convention of template.Must and regexp.MustCompile. Use it for package-level validated constants or test data setup — places where an invalid value is a programming error, not a recoverable runtime condition:

// Package-level constant — panics at startup if "guest" is somehow invalid.
var guestUser = codex.Must(usernameCodec.New(Username("guest")))

// Test helper — panics immediately rather than hiding setup errors.
got := codex.Must(emailCodec.Decode("user@example.com"))

Must is generic and works with any (T, error) pair — New, Decode, MapCodecValidated, or your own functions.

Error Handling

All decode failures are structured types. Use errors.As to inspect them precisely, or pass them directly to log/slog — every type implements slog.LogValuer.

Error types

Inspecting errors with errors.As

var ve codex.ValidationErrors
if errors.As(err, &ve) {
    for _, fieldErr := range ve {
        var ce codex.ConstraintError
        if errors.As(fieldErr.Err, &ce) {
            // ce.Name   — constraint identifier, e.g. "email", "minLen(3)"
            // ce.Message — human-readable description of the failure
            fmt.Printf("field %q: constraint %q failed: %s\n",
                fieldErr.Field, ce.Name, ce.Message)
        }
        if errors.Is(fieldErr.Err, codex.ErrMissingField) {
            fmt.Printf("field %q is required but absent\n", fieldErr.Field)
        }
    }
}

Structured logging with log/slog

All error types implement slog.LogValuer. Pass them as slog attributes to get structured key-value output instead of a flat error string:

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

var ve codex.ValidationErrors
if errors.As(err, &ve) {
    // Emits each field name and its error as separate slog attributes.
    logger.Error("request validation failed", slog.Any("validation_errors", ve))

    for _, fieldErr := range ve {
        var ce codex.ConstraintError
        if errors.As(fieldErr.Err, &ce) {
            // Emits field.field, field.error, constraint.constraint, constraint.message.
            logger.Warn("field constraint failed",
                slog.Any("field", fieldErr),
                slog.Any("constraint", ce),
            )
        }
    }
}

See examples/error-types/ for a runnable demo of every error type with errors.As and slog. See examples/decode-errors/ for struct validation errors and HTTP 400 response patterns.

Builtin Format Constraints

validate/ ships format constraints for common string types. Each constraint validates the value and annotates schema.Schema so the format appears in OpenAPI output automatically.

URLWithSchemes enables scheme-specific URL validation:

validate.URLWithSchemes("https")        // HTTPS only
validate.URLWithSchemes("ws", "wss")    // WebSocket
validate.URLWithSchemes("grpc")         // gRPC

Range / length constraints (with automatic schema annotation):

Byte-size constraints (runtime-only, no schema annotation):

Protocol path/topic constraints (for use with WithPathConstraints / WithTopicConstraints):

var ContactCodec = codex.Struct[Contact](
    codex.Field[Contact, string]{
        Name:     "email",
        Codec:    codex.String().Refine(validate.Email).WithDescription("Primary email."),
        Get:      func(c Contact) string { return c.Email },
        Set:      func(c *Contact, v string) { c.Email = v },
        Required: true,
    },
    codex.Field[Contact, string]{
        Name:     "id",
        Codec:    codex.String().Refine(validate.UUID),
        Get:      func(c Contact) string { return c.ID },
        Set:      func(c *Contact, v string) { c.ID = v },
        Required: true,
    },
)

// Decode validates format automatically — no extra step.
contact, err := ContactCodec.Decode(map[string]any{
    "email": "not-an-email",   // → constraint failed (email): invalid email address: "not-an-email"
    "id":    "bad-uuid",       // → constraint failed (uuid): invalid UUID: "bad-uuid"
})

// OpenAPI schema includes format: email, format: uuid automatically.
yamlBytes, _ := openapi.MarshalYAML(map[string]schema.Schema{"Contact": ContactCodec.Schema})

See examples/formats/ for a runnable demo covering all constraints.

Custom Constraints

codex.Constraint[T] is the public API for defining your own validation rules. Pass any constraint directly to .Refine().

Inline (one-off):

var AvatarCodec = codex.Bytes().Refine(codex.Constraint[[]byte]{
    Name:    "maxBytes(65536)",
    Check:   func(v []byte) bool { return len(v) <= 65536 },
    Message: func(v []byte) string {
        return fmt.Sprintf("expected at most 65536 bytes, got %d", len(v))
    },
})

Reusable (like validate/*):

func MaxBytes(n int) codex.Constraint[[]byte] {
    return codex.Constraint[[]byte]{
        Name:  fmt.Sprintf("maxBytes(%d)", n),
        Check: func(v []byte) bool { return len(v) <= n },
        Message: func(v []byte) string {
            return fmt.Sprintf("expected at most %d bytes, got %d", n, len(v))
        },
    }
}

var AvatarCodec = codex.Bytes().Refine(MaxBytes(65536))

With schema annotation — set Constraint.Schema to propagate constraint metadata into the generated OpenAPI/AsyncAPI schema:

func MaxLen(n int) codex.Constraint[string] {
    return codex.Constraint[string]{
        Name:  fmt.Sprintf("maxLen(%d)", n),
        Check: func(v string) bool { return len(v) <= n },
        Message: func(v string) string {
            return fmt.Sprintf("expected at most %d characters, got %d", n, len(v))
        },
        Schema: func(s schema.Schema) schema.Schema {
            s.MaxLength = &n    // ← reflected into OpenAPI output automatically
            return s
        },
    }
}

The validate/ package ships ready-made constraints using this exact pattern (MinLen, MaxLen, RangeInt, Email, etc.). validate.MaxBytes and validate.MinBytes are built-in for []byte byte-count limits.

Cross-Field Constraints: RefineFunc

RefineFunc wraps a plain func(T) error as a post-decode constraint. Use it on struct codecs to validate relationships between fields without defining a named Constraint[T].

type DateRange struct {
    Start time.Time
    End   time.Time
}

var dateRangeCodec = codex.Struct[DateRange](
    codex.RequiredField[DateRange, time.Time]("start", codex.Time(),
        func(r DateRange) time.Time { return r.Start },
        func(r *DateRange, v time.Time) { r.Start = v }),
    codex.RequiredField[DateRange, time.Time]("end", codex.Time(),
        func(r DateRange) time.Time { return r.End },
        func(r *DateRange, v time.Time) { r.End = v }),
).RefineFunc(func(r DateRange) error {
    if !r.End.After(r.Start) {
        return errors.New("end must be after start")
    }
    return nil
})

On failure, RefineFunc produces a ConstraintError{Name:"refine", ...} — the same error type as Refine.

Available Codec Types

// Nullable pointer field
var noteCodec = codex.Nullable(codex.String())  // Codec[*string]
note, _ := noteCodec.Decode(nil)                // → (*string)(nil)
s := "hello"
enc, _ := noteCodec.Encode(&s)                  // → "hello"
enc, _ = noteCodec.Encode(nil)                  // → nil (JSON null)

// Time and Date
var createdAtCodec = codex.Time()               // Codec[time.Time]
enc, _ := createdAtCodec.Encode(time.Now())     // → "2024-06-15T12:00:00Z"

// StringMap
var tagsCodec = codex.StringMap(codex.String()) // Codec[map[string]string]
enc, _ := tagsCodec.Encode(map[string]string{"env":"prod"})
// → map[string]any{"env":"prod"}

// Any — opaque passthrough, no type enforcement
var rawCodec = codex.Any()
val, _ := rawCodec.Decode(map[string]any{"x": 1}) // passes through unchanged

Either[A, B] — Typed Sum Type

Either2 tries codec A first; if decode fails, tries codec B. Encode uses whichever branch is non-nil. Schema emits {oneOf: [schemaA, schemaB]}.

// A config value that is either a string DSN or a structured DBConfig
type DBConfig struct { Host string; Port uint }
var dbConfigCodec = codex.Struct[DBConfig](...)

var dsnOrConfig = codex.Either2(codex.String(), dbConfigCodec)
// Codec[codex.Either[string, DBConfig]]

// Decode from a plain string
left, _ := dsnOrConfig.Decode("postgres://localhost/db")
// left.Left = &"postgres://localhost/db", left.Right = nil

// Decode from a structured object
right, _ := dsnOrConfig.Decode(map[string]any{"host": "localhost", "port": float64(5432)})
// right.Left = nil, right.Right = &DBConfig{...}

If both branches fail, Decode returns EitherError{Errors: []error{errA, errB}}. Left branch wins on ambiguity.

UntaggedUnion[T] — Interface Union Without Discriminator

UntaggedUnion is the complement to TaggedUnion for cases where the encoded form has no discriminator field. Decode tries each variant in order; encode uses the explicit which selector.

type Shape interface{ area() float64 }
type Circle struct{ Radius float64 }
type Rect   struct{ W, H   float64 }

var shapeCodec = codex.UntaggedUnion[Shape](
    func(s Shape) int {
        switch s.(type) {
        case Circle: return 0
        case Rect:   return 1
        }
        return -1
    },
    codex.UntaggedVariant[Shape]{Name: "circle", Codec: codex.MapCodecSafe(circleCodec, ...)},
    codex.UntaggedVariant[Shape]{Name: "rect",   Codec: codex.MapCodecSafe(rectCodec, ...)},
)

Decode: first-match wins. Encode: which(v) returns the variant index (0-based). Schema: {oneOf: [{...circle...}, {...rect...}]}.

If all branches fail, returns EitherError{Errors: [...]}.

Pure[T] and Eq[T] — Fixed and Single-Value Codecs

Pure always decodes to a fixed value (ignoring wire input) and always encodes that value (ignoring the Go value). Use for protocol version fields, derived fields set automatically, or any field that must always carry one specific value.

Eq wraps a base codec with an equality constraint. The base codec handles type coercion; Eq then rejects anything that doesn't equal value. Schema sets {enum: [value]}.

// CloudEvents 1.0 envelope
type CloudEvent struct {
    SpecVersion string
    Type        string
    ID          string
}

var CloudEventCodec = codex.Struct[CloudEvent](
    codex.Field[CloudEvent, string]{
        Name:  "specversion",
        // Pure: always decodes to "1.0"; always encodes "1.0". Wire value is ignored.
        Codec: codex.Pure("1.0").WithDescription("CloudEvents spec version."),
        ...
    },
    codex.Field[CloudEvent, string]{
        Name:  "type",
        // Eq: String() handles type coercion; then only "com.example.order.placed" passes.
        Codec: codex.Eq(codex.String(), "com.example.order.placed"),
        ...
    },
)

// Decode: specversion wire value is ignored
event, _ := CloudEventCodec.Decode(map[string]any{
    "specversion": "ignored",
    "type":        "com.example.order.placed",
    "id":          "550e8400-...",
})
// event.SpecVersion == "1.0"  ← Pure always returns the fixed value

// Eq rejects wrong type
_, err := CloudEventCodec.Decode(map[string]any{
    "specversion": "1.0",
    "type":        "com.example.user.created",  // wrong
    "id":          "550e8400-...",
})
// err: constraint failed (eq(com.example.order.placed)): expected ...

See examples/event-driven for a runnable demo.

Codec Transformations: MapCodecSafe and MapCodecValidated

Both combinators build a Codec[B] from an existing Codec[A] by supplying mapping functions. Choose based on how much validation you need.

MapCodecSafe — type mapping, infallible decode direction

func MapCodecSafe[A, B any](c Codec[A], to func(A) B, from func(B) (A, error)) Codec[B]

• to (decode direction) must always succeed — it is a total function.
• from (encode direction) may return an error.
• Schema is inherited from Codec[A] (the wire codec).
• Use for newtype wrappers: type Email string over codex.String().

type Email string

var EmailCodec = codex.MapCodecSafe(
    codex.String(),
    func(s string) Email { return Email(s) },
    func(e Email) (string, error) { return string(e), nil },
)

MapCodecValidated — fallible mapping with post-decode validation

func MapCodecValidated[A, B any](ca Codec[A], cb Codec[B], to func(A) (B, error), from func(B) (A, error)) Codec[B]

• Both to and from may return an error.
• After mapping A → B, cb.Validate(b) enforces all Refine constraints defined on cb.
• Validation also runs on the encode direction before from is called.
• Schema comes from cb (the domain type with its constraints).
• Use when the mapping itself is fallible and the target type B carries its own validation rules.

type Celsius float64

var celsiusBaseCodec = codex.MapCodecSafe(
    codex.Float64().
        Refine(validate.MinFloat(-273.15)).
        Refine(validate.MaxFloat(1_000_000)),
    func(f float64) Celsius { return Celsius(f) },
    func(c Celsius) (float64, error) { return float64(c), nil },
)

var celsiusCodec = codex.MapCodecValidated(
    codex.Float64(),    // ca: wire codec
    celsiusBaseCodec,   // cb: domain codec with range constraints
    func(f float64) (Celsius, error) {
        if f != f { // NaN
            return 0, errors.New("NaN is not a valid temperature")
        }
        return Celsius(f), nil
    },
    func(c Celsius) (float64, error) { return float64(c), nil },
)

temp, err := celsiusCodec.Decode(float64(36.6)) // → Celsius(36.6), nil
_, err = celsiusCodec.Decode(float64(-300))     // → error: below absolute zero
_, err = celsiusCodec.Encode(Celsius(2e6))      // → error: exceeds maximum

See examples/codec-mapping for a full example showing all three codec reuse patterns: shared field codec variables, sub-codec direct reuse, MapCodecSafe, and MapCodecValidated.

OpenAPI Schema Generation

Spec: openapis.org - OpenAPI 3.2.0

Codec[T] carries a schema.Schema that describes the type: field names, types, constraints, descriptions, and examples. The render/openapi package converts that schema into an OpenAPI 3.x components/schemas map — no manual YAML authoring, no drift.

import (
    "github.com/DaniDeer/go-codex/render/openapi"
    "github.com/DaniDeer/go-codex/validate"
)

var UserCodec = codex.Struct[User](
    codex.Field[User, string]{
        Name: "name",
        Codec: codex.String().
            Refine(validate.NonEmptyString).
            Refine(validate.MaxLen(100)).
            WithTitle("Full Name").
            WithDescription("The user's full display name."),
        Get:      func(u User) string { return u.Name },
        Set:      func(u *User, v string) { u.Name = v },
        Required: true,
    },
    codex.Field[User, int]{
        Name: "age",
        Codec: codex.Int().
            Refine(validate.RangeInt(0, 150)).
            WithDescription("Age in years."),
        Get:      func(u User) int { return u.Age },
        Set:      func(u *User, v int) { u.Age = v },
        Required: true,
    },
)

// Render components/schemas as YAML — ready to paste into openapi.yaml.
yamlBytes, err := openapi.MarshalYAML(map[string]schema.Schema{
    "User": UserCodec.Schema,
})

Output (trimmed):

User:
  type: object
  properties:
    name:
      type: string
      title: Full Name
      description: The user's full display name.
      minLength: 1
      maxLength: 100
    age:
      type: integer
      description: Age in years.
      minimum: 0
      maximum: 150
  required: [name, age]

The same UserCodec encodes, decodes, validates, and documents — written once.

Constraint schema reflection is opt-in: validate.* constraints (e.g. MinLen, RangeInt, OneOf, Pattern) automatically annotate the schema. Custom constraints can do the same by setting Constraint.Schema.

See examples/openapi/ for a runnable demonstration.

Full OpenAPI 3.1 Document

render/openapi can emit a complete OpenAPI 3.1 document — not just components/schemas — using the DocumentBuilder. Define HTTP routes with route.Route descriptors that reference codec schemas; the builder assembles paths, operations, parameters, request bodies, responses, and components/schemas in one step.

Schemas named via Body.SchemaName or Response.SchemaName are automatically registered in components/schemas and referenced with $ref. Unnamed schemas are inlined.

import (
    "github.com/DaniDeer/go-codex/render/openapi"
    "github.com/DaniDeer/go-codex/route"
)

doc, err := openapi.NewDocumentBuilder(openapi.Info{
    Title:   "User API",
    Version: "1.0.0",
}).
    AddServer(openapi.Server{URL: "https://api.example.com/v1"}).
    AddRoute(route.Route{
        Method:      "POST",
        Path:        "/users",
        OperationID: "createUser",
        Summary:     "Create a user",
        RequestBody: &route.Body{
            Required:   true,
            Schema:     CreateUserRequestCodec.Schema,
            SchemaName: "CreateUserRequest", // → $ref + registered in components
        },
        Responses: []route.Response{
            {Status: "201", Description: "Created", Schema: &UserCodec.Schema, SchemaName: "User"},
            {Status: "400", Description: "Validation error."},
        },
    }).
    AddRoute(route.Route{
        Method: "GET",
        Path:   "/users/{id}",
        PathParams: []route.Param{
            {Name: "id", Required: true, Schema: schema.Schema{Type: "string", Format: "uuid"}},
        },
        Responses: []route.Response{
            {Status: "200", Description: "OK", Schema: &UserCodec.Schema, SchemaName: "User"},
            {Status: "204", Description: "No Content"}, // no body — content omitted
        },
    }).
    Build()

yamlBytes, err := doc.MarshalYAML()

Build() validates:

• No duplicate (method, path) pairs.
• PathParams names exactly match {placeholder} segments in the path.
• Path parameters are always required: true in the output.

See examples/rest-api/ for a runnable demonstration.

AsyncAPI 2.6 Document

Spec: asyncapi.com - specification 3.1.0

render/asyncapi produces a full AsyncAPI 2.6 document from channel descriptors. The same schema.Schema that drives OpenAPI output also describes AsyncAPI message payloads — no duplication.

import "github.com/DaniDeer/go-codex/render/asyncapi"

doc, err := asyncapi.NewDocumentBuilder(asyncapi.Info{
    Title:   "User Events",
    Version: "1.0.0",
}).
    AddServer("production", asyncapi.Server{
        URL:      "amqp://broker.example.com",
        Protocol: "amqp",
    }).
    AddChannel("user/created", asyncapi.ChannelItem{
        Subscribe: &asyncapi.Operation{
            Summary: "User created",
            Message: asyncapi.Message{
                Schema:     UserCreatedEventCodec.Schema,
                SchemaName: "UserCreatedEvent", // → $ref + registered in components
            },
        },
    }).
    Build()

yamlBytes, err := doc.MarshalYAML()

Output (trimmed):

asyncapi: 2.6.0
info:
  title: User Events
  version: 1.0.0
channels:
  user/created:
    subscribe:
      summary: User created
      message:
        payload:
          $ref: "#/components/schemas/UserCreatedEvent"
components:
  schemas:
    UserCreatedEvent:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string, minLength: 1 }

See examples/event-driven/ for a runnable demonstration.

REST API Builder

api/rest is a transport-agnostic REST API builder. Register routes with codec-backed request and response types; the builder returns a RouteHandle with typed Decode and Encode helpers. Pass those helpers to any HTTP framework — this package imports no HTTP library.

The same builder generates a complete OpenAPI 3.1 spec from all registered routes.

import (
    "github.com/DaniDeer/go-codex/api/rest"
    "github.com/DaniDeer/go-codex/validate"
)

// WithPathConstraints validates every registered path at AddRoute time.
b := rest.NewBuilder(
    rest.Info{Title: "User API", Version: "1.0.0"},
    rest.WithPathConstraints(validate.HTTPPath),
)
b.AddServer(rest.Server{URL: "https://api.example.com/v1"})

// AddRoute returns (RouteHandle, error) — path is validated immediately.
createUser, err := rest.AddRoute[CreateUserRequest, User](b, "POST", "/users",
    createUserCodec, userCodec,
    rest.RouteConfig{
        OperationID:    "createUser",
        Summary:        "Create a user",
        ReqSchemaName:  "CreateUserRequest",
        RespSchemaName: "User",
        Responses: []rest.ResponseMeta{
            {Status: "400", Description: "Validation error."},
        },
    })
if err != nil {
    log.Fatal(err) // *rest.InvalidPathError if path is invalid
}

// Route with a path variable and per-variable codec validation.
getUser, err := rest.AddRoute[struct{}, User](b, "GET", "/users/{id}",
    codex.Struct[struct{}](), userCodec,
    rest.RouteConfig{
        OperationID:    "getUser",
        Summary:        "Get a user by ID",
        RespSchemaName: "User",
        PathParamCodecs: map[string]codex.Codec[string]{
            "id": codex.String().Refine(validate.UUID),
        },
    })
if err != nil {
    log.Fatal(err)
}

// BuildPath substitutes {id} and validates it against the UUID codec.
path, err := getUser.BuildPath(map[string]string{"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"})
if err != nil {
    var missingVar *rest.MissingPathVarError
    var paramErr *rest.PathParamError
    switch {
    case errors.As(err, &missingVar):
        log.Fatalf("missing path variable: %s", missingVar.Name)
    case errors.As(err, &paramErr):
        log.Fatalf("invalid value for path variable %s: %v", paramErr.Name, paramErr.Err)
    }
}
// path == "/users/f47ac10b-58cc-4372-a567-0e02b2c3d479"

// In your HTTP handler — works with net/http, Gin, Chi, Echo, anything:
req, err := createUser.Decode(body)   // JSON → CreateUserRequest, validates
user, err := myService.Create(req)
out, err  := createUser.Encode(user)  // User → JSON

// Route descriptor for your framework's router:
fmt.Println(createUser.Descriptor.Method, createUser.Descriptor.Path) // POST /users

// OpenAPI 3.1 spec from all registered routes:
doc, err := b.OpenAPISpec()
yamlBytes, _ := doc.MarshalYAML()

Builder options:

Error types from AddRoute and BuildPath:

Future: framework-specific adapters (adapters/gin, adapters/chi, etc.) will wrap RouteHandle for zero-boilerplate integration. The api/rest core stays dependency-free.

See examples/api-rest/ for a runnable demonstration, and examples/adapters-nethttp/ for the net/http adapter.

net/http Adapter

adapters/nethttp wires a RouteHandle to net/http in one line. No boilerplate for body reading, JSON encoding, or error response formatting.

import nethttp "github.com/DaniDeer/go-codex/adapters/nethttp"

mux := http.NewServeMux()

// Register uses the Go 1.22+ "METHOD /path" ServeMux pattern automatically.
nethttp.Register(mux, createUser, func(ctx context.Context, req CreateUserReq) (User, error) {
    return svc.CreateUser(ctx, req)
})

http.ListenAndServe(":8080", mux)

• POST/PUT/PATCH: body read → handle.Decode (validates) → handler → handle.Encode → write
• GET/HEAD/DELETE: handler called with zero value of Req; path/query extraction via middleware or context
• Errors: {"error":"..."} JSON — 400 for decode/validation, 500 for handler/encode failures
• Response status: taken from the route descriptor's primary response (e.g. 201 for POST)

Codec as domain boundary: the functional pipeline

A codec is not just a validator — it is the public contract of a module boundary. Every boundary — HTTP request, database, HTTP response — is modelled as a codec. Constraints defined on shared field codec variables propagate to all boundaries that reference them: one definition, zero duplication.

The architecture has three cleanly separated layers:

┌────────────────────────────────────────────────────────────────────┐
│  LAYER 1 — DOMAIN MODELS + CONSTRAINTS                             │
│                                                                     │
│  emailFieldCodec  = codex.String().Refine(validate.Email)          │
│  nameFieldCodec   = codex.String().Refine(validate.NonEmpty)       │
│                                         ↑                           │
│  createUserReqCodec  Codec[CreateUserReq]  │ shared field codecs   │
│  userRecordCodec     Codec[UserRecord]     ┤ defined once          │
│  userCodec           Codec[User]           ┘ used in all three     │
├────────────────────────────────────────────────────────────────────┤
│  LAYER 2 — BUSINESS LOGIC (pure domain functions, zero IO)         │
│                                                                     │
│  buildUserRecord(CreateUserReq) UserRecord                         │
│  buildUserResponse(UserRecord) User                                │
│    ← no database, no HTTP, no side effects                         │
│    ← independently unit-testable with plain Go structs             │
├────────────────────────────────────────────────────────────────────┤
│  LAYER 3 — INFRASTRUCTURE (HTTP + database + external services)    │
│                                                                     │
│  UserStore — uses userRecordCodec.Encode/Decode for all DB IO      │
│  makeCreateUserHandler(store) — orchestrates L2 + L3               │
│  nethttp.Register(mux, route, handler) — the only HTTP line        │
│  b.OpenAPISpec()               — the only OpenAPI line             │
│    ← swap to gRPC, CLI, or test without touching L1 or L2          │
└────────────────────────────────────────────────────────────────────┘

The pipeline for POST /users:

Codec[Req] ─ decode ─▶ CreateUserReq ─▶ buildUserRecord ─▶ UserRecord
                                                               ↓ store.Save (Codec[UserRecord].Encode)
Codec[Resp] ─ encode ─▶ User ◀─ buildUserResponse ◀─ UserRecord

Shared field codecs define each domain constraint once and propagate it to all three boundary codecs — HTTP request (required), database schema (required), HTTP response (optional):

var emailFieldCodec = codex.String().Refine(validate.Email).WithDescription("Email address.")

var createUserReqCodec = codex.Struct[CreateUserReq](
    codex.RequiredField[CreateUserReq, string]("email", emailFieldCodec, ...),
)
var userRecordCodec = codex.Struct[UserRecord](
    codex.RequiredField[UserRecord, string]("email", emailFieldCodec, ...),
)
var userCodec = codex.Struct[User](
    codex.OptionalField[User, string]("email", emailFieldCodec, ...),
)

The database store uses the codec for all IO — schema definition and serialization are the same object:

func (s *UserStore) Save(r UserRecord) error {
    encoded, _ := userRecordCodec.Encode(r)   // map[string]any — like SQL INSERT
    s.rows[r.ID] = encoded.(map[string]any)
    return nil
}

func (s *UserStore) Get(id string) (UserRecord, bool) {
    row := s.rows[id]
    record, _ := userRecordCodec.Decode(row)  // validates on read — like SQL scan
    return record, true
}

Pure domain functions are independently testable — no store, no HTTP server required:

func TestBuildUserRecord(t *testing.T) {
    req := CreateUserReq{Name: "Alice", Email: "alice@example.com"}
    record := buildUserRecord(req) // Layer 2 called directly
    // assert on record — zero setup
}

See examples/adapters-nethttp for the full runnable demonstration including tests.

MapCodecSafe / MapCodecValidated are different: they produce a single Codec[B] where encode uses A's wire format. They are designed for same-wire bidirectional mappings (newtypes, DSN strings) — not for HTTP request→response where the two wire formats differ. See Codec Transformations.

Event Channel Builder

api/events is a transport-agnostic event channel builder. Register channels with codec-backed payload types; the builder returns a ChannelHandle with typed Decode and Encode helpers. Pass those helpers to any message broker — this package imports no messaging library.

The same builder generates a complete AsyncAPI 2.6 spec from all registered channels.

import (
    "github.com/DaniDeer/go-codex/api/events"
    "github.com/DaniDeer/go-codex/validate"
)

// WithTopicConstraints validates every registered topic at AddChannel time.
b := events.NewBuilder(
    events.Info{Title: "User Events", Version: "1.0.0"},
    events.WithTopicConstraints(validate.MQTTPublishTopic),
)
b.AddServer("production", events.Server{URL: "amqp://broker.example.com", Protocol: "amqp"})

// AddChannel returns (ChannelHandle, error) — topic is validated immediately.
userCreated, err := events.AddChannel[UserCreatedEvent](b, "user/created", userCreatedCodec,
    events.ChannelConfig{
        Subscribe: &events.OperationConfig{
            Summary:    "A user was created",
            SchemaName: "UserCreatedEvent",
        },
    })
if err != nil {
    log.Fatal(err) // *events.InvalidTopicError if topic is invalid
}

// Channel with a topic template and per-variable codec validation.
sensorMeasurement, err := events.AddChannel[Measurement](b, "sensors/{sensorID}/measurements",
    measurementCodec,
    events.ChannelConfig{
        Subscribe: &events.OperationConfig{Summary: "Sensor measurement received"},
        TopicParamCodecs: map[string]codex.Codec[string]{
            "sensorID": codex.String().Refine(validate.UUID),
        },
    })
if err != nil {
    log.Fatal(err)
}

// BuildTopic substitutes {sensorID} and validates it against the UUID codec.
topic, err := sensorMeasurement.BuildTopic(map[string]string{
    "sensorID": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
})
if err != nil {
    var missingVar *events.MissingTopicVarError
    var paramErr *events.TopicParamError
    switch {
    case errors.As(err, &missingVar):
        log.Fatalf("missing topic variable: %s", missingVar.Name)
    case errors.As(err, &paramErr):
        log.Fatalf("invalid value for topic variable %s: %v", paramErr.Name, paramErr.Err)
    }
}
// topic == "sensors/f47ac10b-58cc-4372-a567-0e02b2c3d479/measurements"

// In your broker callback — works with Paho MQTT, AMQP, Kafka, NATS, anything:
event, err := userCreated.Decode(msg.Payload()) // JSON → UserCreatedEvent, validates
handleUserCreated(event)

// AsyncAPI 2.6 spec from all registered channels:
doc, err := b.AsyncAPISpec()
yamlBytes, _ := doc.MarshalYAML()

Both subscribe and publish directions can be registered on the same channel:

events.AddChannel[UserEvent](b, "user/events", codec, events.ChannelConfig{
    Subscribe: &events.OperationConfig{Summary: "Receive user events"},
    Publish:   &events.OperationConfig{Summary: "Send user events"},
})

Builder options:

Error types from AddChannel and BuildTopic:

Future: broker-specific adapters (adapters/amqp, adapters/kafka, etc.) will wrap ChannelHandle for zero-boilerplate integration.

See examples/api-events/ for a runnable demonstration, and examples/adapters-mqtt/ for the Paho MQTT adapter.

Paho MQTT Adapter

adapters/mqtt wires a ChannelHandle to Paho MQTT with production-ready error handling and observability. SubscribeHandler returns a mqtt.MessageHandler ready to pass to client.Subscribe. Publish encodes the value and publishes it, waiting for broker acknowledgement with context-aware cancellation.

Pattern: separate loggers for domain and transport concerns:

import (
    "errors"
    "log/slog"
    mqtt    "github.com/eclipse/paho.mqtt.golang"
    amqtt   "github.com/DaniDeer/go-codex/adapters/mqtt"
    "github.com/DaniDeer/go-codex/codex"
)

// Create separate loggers for business logic and transport errors.
domainLogger  := slog.Default().With("layer", "domain")
mqttLogger    := slog.Default().With("transport", "mqtt")

// Domain logging decorator — separates logging concern from handler body.
handler := withDomainLoggingErr("measurement.process",
    makeHandleMeasurement(store, threshold, publishAlert),
    domainLogger,
    extractMeasurementAttrs,
)

// Subscribe with structured error handling — distinguish decode vs handler failures.
// For template topics (e.g. "sensors/{sensorID}/measurements"), build the concrete
// topic with BuildTopic before subscribing.
topic, _ := sensorMeasurement.BuildTopic(map[string]string{"sensorID": sensorUUID})
client.Subscribe(topic, 1,
    amqtt.SubscribeHandler(ctx, sensorMeasurement, handler,
        func(e amqtt.SubscribeError) {
            // e.Topic is the concrete incoming topic (msg.Topic()), not the template.
            switch e.Kind {
            case amqtt.KindDecode:
                var validationErrs codex.ValidationErrors
                if errors.As(e.Err, &validationErrs) {
                    mqttLogger.Warn("decode failed: validation errors",
                        "topic", e.Topic,
                        "errors", validationErrs, // triggers ValidationErrors.LogValue()
                    )
                } else {
                    mqttLogger.Warn("decode failed", "topic", e.Topic, "error", e.Err)
                }
            case amqtt.KindHandler:
                mqttLogger.Error("handler failed", "topic", e.Topic, "error", e.Err)
            }
        },
    ),
)

// Publish — static topic: pass nil for vars.
err := amqtt.Publish(ctx, client, alertChannel, 1, false, AlertEvent{...}, nil)

// Publish — template topic: pass vars map; BuildTopic is called internally.
err = amqtt.Publish(ctx, client, sensorMeasurement, 1, false, m,
    map[string]string{"sensorID": sensorUUID})

SubscribeError.Kind distinguishes:

• KindDecode — codec validation failure (user error, log Warn)
• KindHandler — application logic failure (system error, log Error)

SubscribeError.Topic — always the concrete incoming message topic, even for template channels (e.g. sensors/abc-123/measurements not sensors/{sensorID}/measurements).

Publish signature:

func Publish[T any](
    ctx      context.Context,
    client   pahomqtt.Client,
    handle   *events.ChannelHandle[T],
    qos      byte,
    retained bool,
    msg      T,
    vars     map[string]string, // nil → use handle.Topic; non-nil → BuildTopic(vars)
) error

Structured logging: all codec error types (ValidationErrors, ConstraintError, TypeMismatchError, etc.) implement slog.LogValuer. Using slog.Any("errors", err) triggers the full nested structure — field names, constraint details, type mismatches — without string parsing.

See examples/adapters-mqtt for the full runnable demonstration including tests — measurement ingestion from a sensor network, time series storage, and threshold-breach alerts using the three-layer codec pipeline pattern.

Special Topics

Protobuf Integration

go-codex and Protobuf solve different problems. In a proto-first workflow the two complement each other cleanly.

Ownership model:

Workflow:

1. Define your .proto file — this is the source of truth for the wire format.
2. Run protoc-gen-go to generate Go structs.
3. Write a Codec[T] on top of the generated struct to add what proto cannot express: validation constraints, field descriptions, examples, and format-agnostic (JSON/YAML/TOML) decode.

// Generated by protoc-gen-go — do not edit.
type CreateUserRequest struct {
    Name  string
    Email string
    Age   int32
}

// Defined by you — the codec adds validation + documentation.
var CreateUserRequestCodec = codex.Struct[CreateUserRequest](
    codex.Field[CreateUserRequest, string]{
        Name:     "name",
        Codec:    codex.String().Refine(validate.NonEmptyString).WithDescription("Display name."),
        Get:      func(r CreateUserRequest) string { return r.Name },
        Set:      func(r *CreateUserRequest, v string) { r.Name = v },
        Required: true,
    },
    // ...
)

What this gives you:

• gRPC handles binary transport; the codec handles REST/JSON/YAML config validation.
• render/openapi renders the codec's schema as OpenAPI documentation — no separate YAML file.
• Validation rules (Refine) live in Go, next to the type, not scattered across proto options.

What this is not: go-codex does not generate .proto files from codecs, and does not read .proto files. The proto file is the wire-format source of truth; the codec is the validation-and-documentation source of truth. These concerns are intentionally separate.

CLI Tools

Go is a popular language for CLI tools. go-codex is well suited for config file decoding (YAML, TOML, JSON): define a codec once and get type-safe parsing, structured validation errors, and auto-generated JSON Schema documentation for free.

For command-line flag and argument parsing (the --flag value part), use cobra, pflag, or the standard flag package — they handle --help, shell completion, and usage text that codecs are not designed for.

Where go-codex fits in a CLI: read the config file → decode with the codec → get typed struct with all validation errors collected upfront.

// Config is the application configuration struct.
type Config struct {
    Port    int
    LogLevel string
}

var configCodec = codex.Struct[Config](
    codex.RequiredField[Config, int]("port", codex.Int().Refine(validate.RangeInt(1, 65535)),
        func(c Config) int { return c.Port },
        func(c *Config, v int) { c.Port = v },
    ),
    codex.OptionalField[Config, string]("log_level",
        codex.String().Refine(validate.OneOf("debug", "info", "warn", "error")),
        func(c Config) string { return c.LogLevel },
        func(c *Config, v string) { c.LogLevel = v },
    ),
)

// In main() or cobra's PersistentPreRunE:
data, _ := os.ReadFile("config.toml")
cfg, err := format.TOML(configCodec).Unmarshal(data)
if err != nil {
    // err is a codex.ValidationErrors — all field errors collected at once.
    log.Fatal(err)
}
// cfg is fully validated and typed.
_ = cfg.Port

What you get for free:

• All field validation errors collected in one pass (not stop-at-first).
• render/openapi can render the codec's schema as JSON Schema for documentation or editor autocomplete.
• The same codec works with JSON, YAML, and TOML config files — swap format.TOML for format.YAML or format.JSON without touching the codec.

Environment variables only (12-factor / containers): use format.FromEnv — the codec's schema drives string-to-type coercion so you don't write per-field strconv code:

// Env var names: strings.ToUpper(prefix + field_name)
// "port"      + "APP_" → APP_PORT
// "log_level" + "APP_" → APP_LOG_LEVEL
cfg, err := format.FromEnv(configCodec, "APP_")
if err != nil {
    // err is a codex.ValidationErrors — parse errors, missing required
    // fields, and constraint violations all collected in one pass.
    log.Fatal(err)
}

Nested struct fields expand the prefix (db.host → APP_DB_HOST). Slices use comma separation (APP_TAGS=web,api,v2). Complex fields also accept JSON — no separate codec needed: format.FromEnv parses the JSON string into the same intermediate map[string]any that format.TOML and format.JSON produce, then calls the same codec.Decode. All field validations run unchanged.

# Nested struct as JSON object — replaces prefix expansion (APP_DB_HOST etc.)
APP_DB='{"host":"localhost","port":5432,"name":"mydb"}'

# Slice as JSON array — replaces comma-separated
APP_TAGS='["web","api","v2"]'

# StringMap as JSON object — only supported format
APP_LABELS='{"env":"prod","team":"platform"}'

JSON takes precedence when the value starts with { or [. See examples/env-config for a full example.

Environment variable overrides on top of a config file: decode the file, apply os.LookupEnv overrides to the struct, then call configCodec.Validate(cfg). See examples/cli-config.

What go-codex does not do: parse os.Args, generate --help output, or handle subcommands. Use cobra/flag for those.

Schema Metadata: WithExample, WithDeprecated, DefaultField

Codecs carry their schema. Three methods annotate that schema for documentation purposes:

var emailCodec = codex.String().
    Refine(validate.Email).
    WithDescription("Primary contact email.").
    WithExample("alice@example.com")   // → example: alice@example.com in OpenAPI

var legacyIPCodec = codex.String().
    Refine(validate.IPv4).
    WithDescription("IPv4 of last login. Deprecated: use hostname instead.").
    WithDeprecated()                   // → deprecated: true in OpenAPI

var configCodec = codex.Struct[Config](
    codex.RequiredField[Config, int]("port", ...),
    // Absent APP_LOG_LEVEL → "info" is used; default visible in generated schema
    codex.DefaultField[Config, string](
        "log_level",
        codex.String().Refine(validate.OneOf("debug", "info", "warn", "error")),
        "info",
        func(c Config) string { return c.LogLevel },
        func(c *Config, v string) { c.LogLevel = v },
    ),
)

The DefaultField constructor sets Required: false and propagates the default value into the schema's default property. Zero-value defaults are supported (the Default *F field uses a pointer to distinguish "no default" from "" or 0).

See examples/formats for WithExample and WithDeprecated in context, and examples/env-config for DefaultField.

Project Structure

go-codex/
├── go.mod
├── README.md

├── codex/                  # ⭐ PUBLIC API: codecs, primitives, struct, union, slice
│   ├── codec.go            # Codec[T], WithDescription, WithTitle, WithExample, WithDeprecated, Validate, New
│   ├── either.go           # Either[A,B] type, Either2 codec
│   ├── errors.go           # ValidationError, ValidationErrors, EitherError
│   ├── map.go              # MapCodecSafe, MapCodecValidated, Downcast
│   ├── must.go             # Must[T] — generic panic-on-error helper
│   ├── nullable.go         # Nullable[T]
│   ├── object.go           # Field[T,F], RequiredField, OptionalField, DefaultField, Struct[T]
│   ├── primitives.go       # Int, Int32, Int64, Uint, Uint64, Float32, Float64, String, Bool, Bytes, Any, Pure
│   ├── refine.go           # Constraint[T], Refine, RefineFunc, Eq (Constraint.Schema for schema reflection)
│   ├── slice.go            # SliceOf[T]
│   ├── stringmap.go        # StringMap[V]
│   ├── time.go             # Time(), Date(), Duration()
│   └── union.go            # TaggedUnion[T], UntaggedUnion[T], UntaggedVariant[T]
│
├── format/                 # format bridges: JSON, YAML, TOML
│   └── format.go           # Format[T], JSON(), YAML(), TOML(), New()
│
├── route/                  # HTTP route descriptors (no renderer logic)
│   └── route.go            # Route, Param, Body, Response
│
├── api/                    # API builders (no HTTP or messaging library imports)
│   ├── internal/           # shared helpers (not public API)
│   │   └── template.go     # ParseTemplateVars, BuildFromTemplate — used by rest + events
│   ├── rest/               # REST API builder: typed Decode/Encode + OpenAPI spec
│   │   └── builder.go      # Builder, AddRoute[Req,Resp], AddServer, AddSchema, RouteHandle, BuildPath
│   └── events/             # Event channel builder: typed Decode/Encode + AsyncAPI spec
│       └── builder.go      # Builder, AddChannel[T], AddServer, AddSchema, ChannelHandle, BuildTopic
│
├── adapters/               # transport-specific adapters (wrap api/rest or api/events)
│   ├── nethttp/            # net/http adapter for api/rest RouteHandles
│   │   └── adapter.go      # Handler, Register, HandlerWithOptions, RequestFromContext
│   └── mqtt/               # Paho MQTT adapter for api/events ChannelHandles
│       └── adapter.go      # SubscribeHandler, Publish, SubscribeError, ErrorKind
│
├── render/                 # spec renderers (import schema only, or schema + route)
│   ├── internal/
│   │   └── schemarender/   # shared schema-to-map renderer (used by openapi + asyncapi)
│   │       └── schemarender.go  # SchemaObject
│   ├── openapi/            # OpenAPI 3.1 renderer
│   │   ├── openapi.go      # SchemaObject, ComponentsSchemas, MarshalJSON, MarshalYAML
│   │   └── document.go     # DocumentBuilder, Document, Info, Server — full 3.1 spec
│   └── asyncapi/           # AsyncAPI 2.6 renderer
│       ├── asyncapi.go     # delegates schema rendering to render/internal/schemarender
│       └── document.go     # DocumentBuilder, Document, ChannelItem, Operation, Message
│
├── schema/                 # schema model (pure data, zero dependencies)
│   └── schema.go           # Schema, Property, DiscriminatorSchema
│
├── validate/               # reusable constraints (reflect into schema automatically)
│   ├── bytes.go            # MaxBytes(n), MinBytes(n)
│   ├── duration.go         # PositiveDuration, NonNegativeDuration, MinDuration, MaxDuration
│   ├── float.go            # PositiveFloat, NegativeFloat, NonZeroFloat, MinFloat, MaxFloat, RangeFloat
│   ├── format.go           # Email, UUID, URL, URLWithSchemes, URI, Hostname, IPv4, IPv6, Date, Time, DateTime, SemVer, Slug, CIDR
│   ├── int.go              # PositiveInt, NegativeInt, NonZeroInt, MinInt, MaxInt, RangeInt; int32 + int64 variants
│   ├── uint.go             # PositiveUint, MinUint, MaxUint, RangeUint; uint64 variants
│   └── string.go           # NonEmptyString, MinLen, MaxLen, Pattern, OneOf, HTTPPath, MQTTTopic, MQTTPublishTopic
│
└── examples/               # usage demonstrations — not importable
    ├── adapters-mqtt/      # Paho MQTT adapter: wiring api/events to Paho client
    ├── adapters-nethttp/   # net/http adapter: wiring api/rest to ServeMux
    ├── api-events/         # Event channel builder: typed helpers + AsyncAPI spec
    ├── api-rest/           # REST API builder: typed helpers + OpenAPI spec
    ├── decode-errors/      # multi-field ValidationErrors + errors.As demo
    ├── event-driven/       # full AsyncAPI 2.6 document from channel descriptors
    ├── formats/            # builtin format constraints demo (Email, UUID, URL, ...)
    ├── html-sanitize/      # sanitizing untrusted HTML input with a codec
    ├── multiformat/        # JSON / YAML / TOML with one codec
    ├── openapi/            # OpenAPI components/schemas generation from a Codec
    ├── order/              # nested structs, SliceOf, Time, Nullable, StringMap demo
    ├── rest-api/           # full OpenAPI 3.1 document from route descriptors
    ├── shape/              # tagged union + Downcast demo
    ├── templ-mapper/       # mapping codec-validated data to templ components
    ├── validate/           # explicit Validate before marshal
    ├── codec-mapping/      # shared field codecs, sub-codec reuse, MapCodecSafe, MapCodecValidated
    └── construction/       # New + Must: construction-time validation demo