Codec — declare once¶

See also: codex package on pkg.go.dev

A Codec[T] is the single source of truth for a type. It bundles three concerns in one value:

type Codec[T any] struct {
    Schema  schema.Schema          // shape + constraints as data
    Encode  func(T) (any, error)   // T → intermediate (e.g. map[string]any for JSON)
    Decode  func(any) (T, error)   // intermediate → T, validates constraints
}

Why one value?¶

Traditional approaches scatter the same information across multiple files: - A struct with JSON tags for encoding - A validation library for constraints - A Swagger annotation comment for the schema

go-codex collapses all three into a single Codec[T] that you define once and pass around. Every format (JSON, YAML, OpenAPI, AsyncAPI) is derived from the same definition automatically.

Primitive codecs¶

Composition at a glance¶

The following constructors accept another codec as an argument, letting you compose types of arbitrary depth and shape:

Any of these can be used as the codec argument of RequiredField / OptionalField, so nesting is unlimited: Struct → SliceOf(Struct) → Nullable(Struct) → …

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

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

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

// Map[K, V] — keys validated via a key codec.
// Key codec must encode K to a string (JSON/YAML require string map keys).
// The schema emits "propertyNames" for the key constraint.
var sensorIDCodec = codex.String().
    Refine(validate.Pattern(regexp.MustCompile(`^[a-z]+-\d+$`))).
    WithTitle("SensorID")
var sensorsCodec = codex.Map[string, float64](sensorIDCodec, codex.Float64())
// Schema: {type:object, propertyNames:{type:string,title:"SensorID",pattern:"..."}, additionalProperties:{type:number}}
_, _ = sensorsCodec.Encode(map[string]float64{"temp-01": 22.5}) // ok
_, err := sensorsCodec.Encode(map[string]float64{"INVALID": 22.5})
// → KeyError{Key:"INVALID", Err: constraint failed (pattern)}
_ = err

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

Struct codecs¶

var UserCodec = codex.Struct[User](
    codex.RequiredField("name", nameCodec, get, set),
    codex.OptionalField("bio",  codex.String(), get, set),
)

get/set are a getter (func(T) F) and a setter (func(*T, F)) for that one field — how RequiredField/OptionalField/DefaultField read a value out of your struct (encode) and write a decoded value back into it (decode). Go has no reflection-free way to do this automatically, so plain closures are the mechanism; they are not go-codex-internal plumbing, they're what you write at every call site:

codex.RequiredField("name", nameCodec,
    func(u User) string { return u.Name },
    func(u *User, v string) { u.Name = v },
)

They reach nested sub-structs the same way (func(u User) string { return u.Meta.Region }). See "Field factory functions" below for how to avoid repeating them when several struct types share the same field.

Missing fields on decode¶

When a field key is absent from the incoming object, the codec follows this decision tree:

field key absent from wire object?
├─ DefaultField  → apply declared default, continue
├─ RequiredField → return ErrMissingField (decode fails)
└─ OptionalField → do nothing; Go zero value remains ("", 0, nil, …)

RequiredField — missing key → ErrMissingField sentinel, surfaced as ValidationError{Field: "name", Err: ErrMissingField} inside ValidationErrors. Check with errors.Is(err, codex.ErrMissingField).

OptionalField — missing key → the Go field retains its zero value. The set function is never called. There is no distinction between "key absent" and "key present with zero value" at the Go struct level — if you need that, use Nullable:

// "note" absent  → Note == nil  (key was not in the object)
// "note": null   → Note == nil  (key was present, value was null)
// "note": "hi"   → Note == &"hi"
codex.OptionalField("note", codex.Nullable(codex.String()),
    func(u User) *string { return u.Note },
    func(u *User, v *string) { u.Note = v },
)

DefaultField — missing key → declared default applied via set. The default also appears in the generated OpenAPI/AsyncAPI schema as "default": <value>. A zero-value default is valid — DefaultField uses a pointer internally to distinguish "no default" from "default is zero":

codex.DefaultField("log_level",
    codex.String().Refine(validate.OneOf("debug", "info", "warn", "error")),
    "info",   // applied when key absent; emitted as "default" in schema
    func(c Config) string { return c.LogLevel },
    func(c *Config, v string) { c.LogLevel = v },
)

Missing fields — summary¶

Encode note: RequiredField/OptionalField/DefaultField never omit a field on encode — every one of them always writes the key to the output object, even at the Go zero value. For an OPT-IN way to omit a zero-valued (or default-valued) field's key entirely, see "OmitEmptyField/OmitEmptyFieldFunc/OmitDefaultField" below.

Rejecting unknown keys — StrictStruct¶

Struct is forward-compatible by default: any input key not matching a declared field is silently ignored on decode, and the generated schema leaves additionalProperties unset (JSON Schema default: extra properties allowed). Use codex.StrictStruct — same signature as Struct, same RequiredField/OptionalField/DefaultField vocabulary — to reject unknown keys instead (catches typo'd field names):

var StrictUserCodec = codex.StrictStruct[User](
    codex.RequiredField("name", nameCodec, get, set),
    codex.OptionalField("bio",  codex.String(), get, set),
)

_, err := StrictUserCodec.Decode(map[string]any{"name": "Alice", "boi": "typo"})
// err: field "boi": unknown field (codex.ErrUnknownField) — errors.Is-navigable

• Sets Schema.AdditionalProperties = false (JSON Schema additionalProperties: false) — Struct never sets this field at all.
• Unknown-key errors are collected ALONGSIDE normal per-field errors (missing required fields, constraint failures) in one ValidationErrors — a request with both a missing required field and a typo'd key reports both, not just one.
• Not viral/recursive across nesting — a nested field declared with plain Struct stays non-strict even when the OUTER struct uses StrictStruct. Opt in explicitly at each nesting level, exactly like Required/Optional/Default are declared independently per level (see Nested structs).
• Encode is unchanged from Struct — "unknown field" is a decode-only (external input) concept.

Reusing Field declarations for path/topic/header/query vars¶

This is the mechanism behind a general library design principle: one struct, one call (see API Contracts — Design principle) — a caller on either side of a boundary should be able to do an entire encode-or-decode direction with one struct value and one call, not manual map assembly. RequiredField/OptionalField/DefaultField aren't just for JSON object keys — the same declarations work for any string-keyed source: HTTP path/query/header/cookie parameters, MQTT/event topic variables, and file path segments. codex.DecodeVars/EncodeVars decode/encode a map[string]string (instead of a JSON map[string]any) using those exact same Field declarations — no new declaration API to learn:

var idField = codex.RequiredField("id", codex.String().Refine(validate.UUID),
    func(r GetUserReq) string { return r.ID },
    func(r *GetUserReq, v string) { r.ID = v })

// Decode: partial merge into an existing struct (only "id" is touched).
var req GetUserReq
err := codex.DecodeVars(&req, map[string]string{"id": r.PathValue("id")}, idField)

// Encode: extract field values into a vars map (replaces hand-written
// varsFor func(T) map[string]string closures used by adapter constructors).
vars, err := codex.EncodeVars(req, idField)

A field's codec must accept a string on Decode — plain codex.String() for string fields, or codex.StringCodec(parse, format, schema)/ codex.TextCodec[V]()/codex.IntString() (etc.) for typed fields like int/uuid.UUID (vars are always string-valued at the wire level: path segments, topic segments, header/query/cookie values) — see "Typed (non-string) path/topic/query/header/cookie/key vars" below.

Per-boundary sugar: rest.NewPathParam[T, V]/NewRequiredQueryParam[T, V]/ NewOptionalQueryParam[T, V] (+ Header/Cookie equivalents), events.NewTopicParam[T, V], reqreply.NewTopicParam[T, V], and ports.NewFilePathParam[T, V] declare BOTH the boundary's spec Param (for OpenAPI/AsyncAPI generation, unchanged) AND a merge field in ONE call — see Ports feature — File and REST API feature for the full per-boundary API. The plain PathParam/QueryParam/FilePathParam/TopicParam struct literals remain available as the low-level, validate-only alternative (codex.Param's own escape-hatch role — see below).

Every one of these boundary-specific PathParam/TopicParam/ FilePathParam types is a thin wrapper over ONE shared pair of primitives in codex: codex.Param{Name, Description, Codec} (the validate-only escape hatch) and codex.MergedParam[T]/codex.NewParam[T, V] (the merge-capable counterpart, built via the SAME RequiredField mechanism above). codex.ValidateParams/codex.ValidateDeclaredParams/ codex.BuildFromParams are the shared validate-loop/declaration-check/ build-substitution bodies every boundary's BuildPath/BuildTopic/ ValidatePathParams/ValidateTopicVars methods delegate to internally — one canonical implementation instead of five independently-duplicated copies (api/rest, api/events, api/reqreply, ports/file.go, ports/dir.go). Each boundary keeps its OWN struct name/vocabulary (PathParam reads as "a REST path variable", TopicParam as "an event/reqreply topic variable") since Go requires a package-owned type to satisfy that package's own sealed option interface (RouteOpt/ ChannelOpt/FileOpt/DirOpt) — but the validation/build LOGIC, and the error shapes (ParamError/MissingParamError/InvalidParamError), are shared. ports' own FilePathParamError/DirPathParamError are the one exception, kept as their own distinct types rather than aliased, since their LogValue() keys predate and differ from codex.Param's.

A struct can mix BOTH sources at once — some fields decoded from the body, others merged from vars — as long as the body codec and the merge fields declare different field names (RouteHandle.DecodeMerged decodes the body first, then merges vars into the same value, touching only the declared merge fields). See REST API — Mixing body fields and merged params.

The SAME mechanism applies in the RESPONSE direction — rest.NewRequiredResponseHeaderParam[Resp, V]/NewOptionalResponseHeaderParam[Resp, V] (+ Cookie equivalents, also generic over V — a typed response header/ cookie merges directly into an int/uuid.UUID/etc. exactly like the request-side constructors above) declare a response header/cookie merge field on Resp: the server sets it automatically from the returned struct's field, and the client merges the HTTP response back into the same field automatically. On top of the four merge-field roles (path/query/header/cookie), nethttp.Call/rest.CallWithTransport is the single-call client convenience that derives every request-side map from ONE struct automatically — this is the concrete "one struct, one call" experience end to end. See REST API — Response merge fields and REST API — One-line client calls.

This also means the pattern is neither JSON-specific nor flat-struct-specific: get/set on RequiredField/OptionalField (and every REST merge-field constructor built on them) are plain Go closures, not reflection over a struct's direct fields — a closure reaching into a NESTED sub-struct (func(r Req) string { return r.Meta.X }) works exactly like a top-level field, with zero framework changes. And since body decode/encode is completely orthogonal to var-merge, ANY format.Format[T] — JSON, YAML, TOML, format.Gob, format.Binary, or a custom format.NewTyped — composes with merge fields unchanged. See REST API — Nested structs & binary body formats and examples/rest-nested-binary for the full runnable version.

Constraints with Refine¶

var EmailCodec = codex.String().Refine(validate.Email)
// Schema gains: format: email
// Decode rejects invalid emails at runtime
// Encode validates before serialising

Constraints run symmetrically — on both Encode and Decode — ensuring the codec is the single source of truth for validity.

Stacking and combining constraints¶

.Refine(...) is variadic and chainable. Every call wraps the previous codec, building a validation chain:

// All three are equivalent — same chain, same execution order:
codex.String().Refine(A, B, C)
codex.String().Refine(A).Refine(B).Refine(C)
codex.String().Refine(A).Refine(B, C)

Constraints run in declaration order. The first failure stops the chain — later constraints do not run.

Mix built-in and custom constraints freely:

var containerNameCodec = codex.String().
    Refine(validate.NonEmptyString).           // built-in: non-empty
    Refine(validate.MaxLen(63)).               // built-in: DNS label max length
    Refine(codex.Constraint[string]{           // custom: no spaces/underscores/slashes
        Name:  "container-name",
        Check: func(v string) bool { return !strings.ContainsAny(v, " _/") },
        Message: func(v string) string {
            return fmt.Sprintf("container name %q must not contain spaces, underscores, or slashes", v)
        },
    }).
    Refine(codex.Constraint[string]{           // custom: must start with a letter
        Name:  "starts-with-letter",
        Check: func(v string) bool { return len(v) > 0 && unicode.IsLetter(rune(v[0])) },
        Message: func(v string) string {
            return fmt.Sprintf("container name %q must start with a letter", v)
        },
    })

Order matters: put cheaper constraints first (length, empty check) so they short-circuit before expensive ones (regex, external lookup).

Schema annotation from custom constraints¶

Set the optional Constraint.Schema function to propagate constraint metadata into the generated OpenAPI/AsyncAPI schema:

var slugCodec = codex.String().
    Refine(validate.NonEmptyString).
    Refine(codex.Constraint[string]{
        Name:  "slug",
        Check: func(v string) bool { return slugPattern.MatchString(v) },
        Message: func(v string) string {
            return fmt.Sprintf("%q is not a valid slug (lowercase letters, digits, hyphens only)", v)
        },
        Schema: func(s schema.Schema) schema.Schema {
            s.Pattern = `^[a-z0-9-]+$`   // emitted in the OpenAPI/AsyncAPI spec
            return s
        },
    })
// Schema: {type: string, minLength: 1, pattern: "^[a-z0-9-]+$"}

Each Constraint.Schema function receives the schema produced by all previous constraints and returns the augmented version — they compose without interfering.

Built-in constraints in the validate package already set Schema where appropriate (e.g. validate.Email sets format: email, validate.RangeInt sets minimum/maximum). Custom constraints without a Schema function simply add runtime validation without changing the spec.

Whole-struct (cross-field) constraints¶

.Refine(...) isn't limited to scalar codecs — codex.Struct[T](...) returns a plain Codec[T], so the same mechanism validates INVARIANTS THAT SPAN MULTIPLE FIELDS, something no single per-field Constraint can see:

type DateRange struct {
    Start, End time.Time
}

var dateRangeCodec = codex.Struct[DateRange](
    codex.RequiredField("start", codex.Time(), func(d DateRange) time.Time { return d.Start }, func(d *DateRange, v time.Time) { d.Start = v }),
    codex.RequiredField("end",   codex.Time(), func(d DateRange) time.Time { return d.End },   func(d *DateRange, v time.Time) { d.End = v }),
).Refine(codex.Constraint[DateRange]{
    Name:  "start-before-end",
    Check: func(d DateRange) bool { return d.Start.Before(d.End) },
    Message: func(d DateRange) string {
        return fmt.Sprintf("start (%s) must be before end (%s)", d.Start, d.End)
    },
})

• The whole-struct Constraint[DateRange]'s Check receives the FULLY DECODED DateRange — it runs AFTER every per-field Required/Codec/nested-struct check has already succeeded, so a missing/invalid individual field is reported first (per-field ValidationErrors), and the cross-field constraint only runs once the struct is otherwise well-formed.
• Symmetric on Encode too — an in-memory DateRange{Start: later, End: earlier} fails to encode, exactly like any other Refined codec.
• Use this for "at least one of A or B must be set", "field X only valid when field Y is a certain value", range checks across two fields, and similar invariants that a single RequiredField/OptionalField declaration cannot express.

Composition — shared field codecs¶

Define field codecs once and reuse across struct codecs:

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

var UserCodec    = codex.Struct[User](   codex.RequiredField("email", emailFieldCodec, ...), ...)
var ProfileCodec = codex.Struct[Profile](codex.RequiredField("email", emailFieldCodec, ...), ...)
// Both carry the same constraint and description — no duplication.

Field factory functions — reusing field groups across structs¶

When the same field (same name, same codec, same validation rules) appears in multiple structs, combine shared field codecs with a field factory function. A factory function bakes in the field name and codec rules and accepts only the getter/setter — the one thing that is unavoidably struct-specific.

import "time"

// ── Shared field codecs ───────────────────────────────────────────────────────

var idCodec = codex.String().Refine(validate.UUID).
    WithDescription("Unique identifier (UUID v4).")

var createdAtCodec = codex.Time().
    WithDescription("Creation timestamp (RFC 3339).")

// ── Field factory functions ───────────────────────────────────────────────────
// The type parameter T makes each factory work for any struct that has the
// appropriate field, without repeating the field name or validation rules.

func IDField[T any](get func(T) string, set func(*T, string)) codex.Field[T, string] {
    return codex.RequiredField("id", idCodec, get, set)
}

func CreatedAtField[T any](get func(T) time.Time, set func(*T, time.Time)) codex.Field[T, time.Time] {
    return codex.RequiredField("created_at", createdAtCodec, get, set)
}

// ── Structs using Go embedding for DRY field access ──────────────────────────

type AuditBase struct {
    ID        string
    CreatedAt time.Time
}

type User struct {
    AuditBase               // embedded — promotes ID and CreatedAt
    Name  string
    Email string
}

type Device struct {
    AuditBase               // same embedding
    Hostname string
    IPAddr   string
}

// ── Codecs — each struct provides only its own getters/setters ───────────────

var UserCodec = codex.Struct[User](
    IDField(
        func(u User) string  { return u.ID },
        func(u *User, v string) { u.ID = v },
    ),
    CreatedAtField(
        func(u User) time.Time  { return u.CreatedAt },
        func(u *User, v time.Time) { u.CreatedAt = v },
    ),
    codex.RequiredField("name",
        codex.String().Refine(validate.NonEmptyString),
        func(u User) string { return u.Name },
        func(u *User, v string) { u.Name = v },
    ),
    codex.RequiredField("email",
        codex.String().Refine(validate.Email),
        func(u User) string { return u.Email },
        func(u *User, v string) { u.Email = v },
    ),
)

var DeviceCodec = codex.Struct[Device](
    IDField(
        func(d Device) string  { return d.ID },
        func(d *Device, v string) { d.ID = v },
    ),
    CreatedAtField(
        func(d Device) time.Time  { return d.CreatedAt },
        func(d *Device, v time.Time) { d.CreatedAt = v },
    ),
    codex.RequiredField("hostname",
        codex.String().Refine(validate.Hostname),
        func(d Device) string { return d.Hostname },
        func(d *Device, v string) { d.Hostname = v },
    ),
    // ...
)

What is shared: the field name ("id"), the codec (idCodec), and all its constraints and schema metadata. A change to idCodec propagates to every struct that uses IDField — one declaration, zero drift.

What is not shared: the getter/setter functions — they are unavoidably struct-specific because Go's type system cannot derive func(Device) string from func(User) string automatically.

Why not a library feature: Go does not have inheritance, and reflecting on struct fields to auto-derive getters/setters would violate the no-reflection, no-struct-tags design principle. Field factory functions achieve the same result with full type safety and zero magic.

Nested structs¶

A field codec can be any Codec[F] — including another Struct[...] codec. Nesting is unlimited and composes with SliceOf, Nullable, and StringMap:

type Address struct { Street, City, Country string }
type Customer struct { Name, Email string }
type LineItem struct { Product string; Quantity int; Price float64 }
type Order struct {
    ID             string
    Customer       Customer
    Shipping       Address
    BillingAddress Address // same Address type/codec as Shipping — see below
    Items          []LineItem
    Tags           map[string]string
    Note           *string
}

var addressCodec = codex.Struct[Address](
    codex.RequiredField("street",  codex.String().Refine(validate.NonEmptyString), ...),
    codex.RequiredField("city",    codex.String().Refine(validate.NonEmptyString), ...),
    codex.RequiredField("country", codex.String().Refine(validate.NonEmptyString), ...),
)

var lineItemCodec = codex.Struct[LineItem](
    codex.RequiredField("product",  codex.String(), ...),
    codex.RequiredField("quantity", codex.Int().Refine(validate.PositiveInt), ...),
    codex.RequiredField("price",    codex.Float64().Refine(validate.PositiveFloat), ...),
)

var orderCodec = codex.Struct[Order](
    codex.RequiredField("id",       codex.String(), ...),
    codex.RequiredField("customer", customerCodec,              ...),  // nested Struct, required
    codex.RequiredField("shipping", addressCodec,               ...),  // nested Struct, required
    codex.OptionalField("billingAddress", addressCodec,         ...),  // SAME nested Struct, optional
    codex.RequiredField("items",    codex.SliceOf(lineItemCodec).Refine(validate.NonEmptySlice[LineItem](), validate.MaxItems[LineItem](20)), ...), // slice of structs, 1-20 items
    codex.OptionalField("tags",     codex.StringMap(codex.String()), ...), // map
    codex.OptionalField("note",     codex.Nullable(codex.String()),  ...), // optional
)

Required vs optional is orthogonal to whether a field's codec is a nested Struct or a scalar. RequiredField/OptionalField/DefaultField only decide PRESENCE — they never inspect what codec they wrap. shipping and billingAddress above use the exact same addressCodec; only RequiredField vs OptionalField differs:

• Absent + Required → decode fails with ErrMissingField for that field name.
• Absent + Optional → the nested field is silently left at its Go zero value (Address{}) — decode succeeds.
• Present (either case) → decodes through the nested struct's OWN codec, which enforces its OWN required/optional/default rules completely independently. A present-but-incomplete billingAddress (e.g. missing country) still fails — declaring the OUTER field Optional never weakens the INNER struct's own validation, it only controls whether the key itself must exist.

What you get for free: - Encode/decode recurses automatically — order.Customer is a Go struct, the JSON "customer" is an object. - Validation cascades — a constraint failure on customer.email surfaces as a nested ValidationErrors: the top-level error names "customer", and unwrapping it one level (errors.As into codex.ValidationErrors) yields the inner error naming "email" (message reads field customer: field email: ... — nested attribution, not a flattened dotted-path string). - Schema generation — OrderCodec.Schema produces a nested $object with inline Customer/Address schemas, and each nesting level's Required array is independent: billingAddress is absent from the OUTER Required list, but its own embedded schema still declares ["street","city","country"] as required. - Encoding a never-populated Optional nested struct still emits the key with its zero value — codex has no "omit empty" semantics; Required/Optional/Default only affect DECODE and the generated schema's Required array, never what ENCODE writes.

See examples/order for a complete runnable demo with all five nesting patterns, including both a required (shipping) and an optional (billingAddress) nested struct built from the identical codec.

Slices — array-level constraints¶

codex.SliceOf(elem) returns a plain Codec[[]T], so it composes with .Refine(...) exactly like any scalar codec — required/optional at the FIELD level is orthogonal to constraints on the array's LENGTH or CONTENTS:

var itemsCodec = codex.SliceOf(lineItemCodec).
    Refine(validate.NonEmptySlice[LineItem]()).  // at least 1 element
    Refine(validate.MaxItems[LineItem](20))      // at most 20 elements
// Schema: {type: array, items: {...}, minItems: 1, maxItems: 20}

Built-in validate constructors for slices (all generic, in validate/slice.go):

UniqueItems requires T comparable — narrower than the other three's any — since it needs Go equality to detect duplicates. For element types containing slices/maps/funcs (not comparable), write a custom codex.Constraint[[]T] using reflect.DeepEqual or a domain-specific key extractor instead.

These constructors are functions, not package-level vars like validate.NonEmptyString — Go has no generic package-level variables, so the element type must be supplied at the call site (validate.MinItems[LineItem](1), not validate.MinItems(1)).

Array-level required/optional (whether the KEY itself must be present) is controlled the same way as any other field — RequiredField/OptionalField/DefaultField wrapping a SliceOf(...) codec, exactly as shown for items above. Absent + Optional leaves the field at its Go zero value (nil slice); absent + Required fails with ErrMissingField; present (either case) runs the length/uniqueness constraints declared via .Refine(...).

Maps — size constraints¶

codex.Map[K,V]/codex.StringMap[V] return plain Codec[map[K]V] codecs, so entry-count constraints compose with .Refine(...) exactly like slice-length constraints:

var tagsCodec = codex.StringMap(codex.String()).
    Refine(validate.MaxProperties[string, string](5))  // at most 5 entries
// Schema: {type: object, additionalProperties: {...}, maxProperties: 5}

Built-in validate constructors for maps (all generic, in validate/map.go):

These mirror validate/slice.go's array constructors exactly, one level up (entries instead of elements). Map KEY constraints (pattern, format, enum, length) are a SEPARATE, already-fully -supported concern: pass a .Refine(...)-composed Codec[K] as Map's keyCodec argument — it renders into the schema's propertyNames and is validated per-key on every decode. Do not confuse the two: MinProperties/MaxProperties constrain how MANY entries the map has; key-codec constraints constrain what EACH key looks like.

EntrySlice[K,V,R] decodes to Codec[[]R] (a slice), not Codec[map[K]V] — its entry-count constraint is therefore validate.MinItems[R]/MaxItems[R]/NonEmptySlice[R] (the SLICE constructors), not the map ones above, even though EntrySlice's generated schema is object-shaped (type: object, matching its wire format). This is a known, harmless schema/type mismatch: a JSON Schema validator ignores minItems/maxItems on a type: object schema (those keywords only apply where type: array), so the RUNTIME constraint still enforces correctly via len(), but the constraint won't appear in the rendered OpenAPI/AsyncAPI spec for that field. If the spec annotation matters for an EntrySlice field, use a custom codex.Constraint[[]R] with a Schema callback that sets MinProperties/MaxProperties directly instead.

Merging key and value into one type (EntrySlice)¶

EntrySlice[K, V, R] handles the case where the object key itself carries domain meaning that belongs inside the value struct. It decodes a JSON/YAML/TOML object into []R, merging the decoded key and value into each element.

Use case: Azure IoT Edge device twins, Kubernetes ConfigMaps, and similar formats use dotted keys like "properties.desired.modules.cv-writer-kvrocks" where the last segment is the container name. With EntrySlice, this decodes directly into []Container — no post-processing loop needed.

Recommended key codec: MapCodecValidated (Option B)¶

Put the prefix logic in the key codec, not in merge/split. This way: - The key codec validates the full wire key and the extracted container name separately - merge receives only the already-extracted name — no strings.TrimPrefix needed - split returns only the name — the codec re-adds the prefix on encode

const prefix = "properties.desired.modules."

var containerNameConstraint = codex.Constraint[string]{
    Name:  "container-name",
    Check: func(v string) bool { return len(v) > 0 && !strings.ContainsAny(v, " /_") },
}
var moduleKeyConstraint = codex.Constraint[string]{
    Name:  "module-key-path",
    Check: func(v string) bool { return strings.HasPrefix(v, prefix) && len(v) > len(prefix) },
}

// containerKeyCodec: wire validates full dotted key; domain validates container name.
var containerKeyCodec = codex.MapCodecValidated(
    codex.String().Refine(moduleKeyConstraint),      // wire: "properties.desired.modules.cv-writer"
    codex.String().Refine(containerNameConstraint),   // domain: "cv-writer"
    func(fullKey string) (string, error) {            // decode: strip prefix
        return strings.TrimPrefix(fullKey, prefix), nil
    },
    func(name string) (string, error) {               // encode: add prefix
        return prefix + name, nil
    },
)

var containersCodec = codex.EntrySlice(
    containerKeyCodec,   // K = string (container name)
    moduleCodec,         // V = ModuleConfig
    func(name string, m ModuleConfig) Container {     // merge: name already extracted
        return Container{Name: name, Image: m.Image, Status: m.Status}
    },
    func(c Container) (string, ModuleConfig) {        // split: returns container name
        return c.Name, ModuleConfig{Image: c.Image, Status: c.Status}
    },
)
// → Codec[[]Container]

Decode path — multiple containers¶

Given the wire object:

{
  "properties.desired.modules.cv-writer-kvrocks": {"image": "myregistry/cv-writer:1.0", "status": "running"},
  "properties.desired.modules.cv-writer-gateway": {"image": "myregistry/gateway:3.1",  "status": "running"},
  "properties.desired.modules.analytics-engine":  {"image": "myregistry/analytics:2.1", "status": "stopped"}
}

containersCodec.Decode(rawJSON) iterates every key-value pair:

Result: []Container with 3 elements. Sort after decode if order matters — JSON object key order is not guaranteed.

Encode path — multiple containers¶

containersCodec.Encode(containers) processes each element:

1. split(c) → (c.Name, ModuleConfig{c.Image, c.Status})
2. containerKeyCodec.Encode(c.Name) → validates name → "properties.desired.modules." + c.Name
3. moduleCodec.Encode(ModuleConfig{...}) → {"image":"...","status":"..."}
4. Writes one key-value pair into the output map

Result: the same flat dotted-key object as the input. All three containers are present. Key validation happens for every element — a single invalid name (e.g. one with an underscore) stops encoding and returns KeyError{Key: "bad_name", Err: ConstraintError{Name:"container-name",...}}.

Format compatibility¶

Extracting multiple fields from a key¶

K doesn't have to be string. Any comparable Go type works — including a struct. Use a Struct[ModuleKey] domain codec with MapCodecValidated to parse and validate each segment independently.

Key format: "properties.desired.modules.<tenant>.<container-name>"
Two segments → ModuleKey{Tenant, Name} — extracted in one key codec, no parsing in merge/split.

type ModuleKey struct {
    Tenant string // "tenant-acme"
    Name   string // "cv-writer-kvrocks"
}

type TenantContainer struct {
    Tenant string
    Name   string
    Image  string
    Status string
}

// Domain codec validates each field independently.
var moduleKeyStructCodec = codex.Struct[ModuleKey](
    codex.RequiredField("tenant", codex.String().Refine(tenantConstraint),
        func(k ModuleKey) string { return k.Tenant },
        func(k *ModuleKey, v string) { k.Tenant = v },
    ),
    codex.RequiredField("name", codex.String().Refine(containerNameConstraint),
        func(k ModuleKey) string { return k.Name },
        func(k *ModuleKey, v string) { k.Name = v },
    ),
)

// Two-layer key codec:
//   wire  — validates the full dotted key
//   domain — validates each extracted segment via moduleKeyStructCodec
var twoPartKeyCodec = codex.MapCodecValidated(
    codex.String().Refine(twoPartKeyConstraint),  // "properties.desired.modules.t.n" ✓
    moduleKeyStructCodec,                          // {Tenant:"t", Name:"n"} ✓
    func(fullKey string) (ModuleKey, error) {      // decode: strip prefix + split
        rest := strings.TrimPrefix(fullKey, prefix)
        parts := strings.SplitN(rest, ".", 2)
        return ModuleKey{Tenant: parts[0], Name: parts[1]}, nil
    },
    func(k ModuleKey) (string, error) {            // encode: reassemble
        return prefix + k.Tenant + "." + k.Name, nil
    },
)

// K = ModuleKey (comparable struct — all fields are strings)
var tenantContainersCodec = codex.EntrySlice(
    twoPartKeyCodec,
    moduleCodec,
    func(k ModuleKey, m ModuleConfig) TenantContainer {
        return TenantContainer{Tenant: k.Tenant, Name: k.Name, Image: m.Image, Status: m.Status}
    },
    func(c TenantContainer) (ModuleKey, ModuleConfig) {
        return ModuleKey{Tenant: c.Tenant, Name: c.Name},
               ModuleConfig{Image: c.Image, Status: c.Status}
    },
)
// → Codec[[]TenantContainer]

Decode table — wire to Go:

Field-level validation on encode: TenantContainer{Tenant: "tenant_acme", ...} (underscore in tenant) → moduleKeyStructCodec.Validate → ValidationErrors[{Field:"tenant", Err:ConstraintError{Name:"tenant-name"}}] → wrapped in KeyError{Key:"{tenant_acme ...}", Err:...}. The error identifies the failing field, not just "the key is invalid".

General rule: for N segments in a key, use K = struct with N fields. Go structs are comparable when all fields are comparable types (strings, ints, etc.).

See examples/flat-key-patch Section 10 for the full runnable demo.

Static key — constant name injected via MapCodecSafe¶

When the key is known at compile time (it never varies), the container name is not on the wire — it only exists as the field name literal in the codec. There is nothing to decode. Inject it as a constant.

Wire format (the key is always exactly this):

{
  "properties.desired.modules.cv-writer-kvrocks": {"image": "myregistry/cv-writer:1.0", "status": "running"}
}

Goal: Container{Name: "cv-writer-kvrocks", Image: "...", Status: "running"} — name comes from the key, which we know statically.

Pattern: wrap the value codec with MapCodecSafe to inject the constant name during decode and strip it on encode (name is not serialized into the value object):

const cvWriterKeyName = "cv-writer-kvrocks"
const cvWriterKey     = "properties.desired.modules." + cvWriterKeyName

// valueWithNameCodec: decodes ModuleConfig → Container{Name: constant, ...}
//                     encodes Container     → ModuleConfig (drops Name — not on wire)
var valueWithNameCodec = codex.MapCodecSafe(
    moduleCodec,
    func(m ModuleConfig) Container {          // decode: inject constant
        return Container{Name: cvWriterKeyName, Image: m.Image, Status: m.Status}
    },
    func(c Container) (ModuleConfig, error) { // encode: drop name
        return ModuleConfig{Image: c.Image, Status: c.Status}, nil
    },
)

// Outer codec: the full dotted key is the field name. Dots are valid field names.
var cvWriterCodec = codex.Struct[Container](
    codex.RequiredField(cvWriterKey, valueWithNameCodec,
        func(c Container) Container { return c },
        func(outer *Container, inner Container) { *outer = inner },
    ),
)
// Decode: {"properties.desired.modules.cv-writer-kvrocks": {"image":"...","status":"running"}}
// Result: Container{Name:"cv-writer-kvrocks", Image:"...", Status:"running"}
//
// Encode: Container{Name:"cv-writer-kvrocks", Image:"...", Status:"running"}
// Result: {"properties.desired.modules.cv-writer-kvrocks": {"image":"...","status":"running"}}
//          ↑ Name is NOT in the value object — only the key encodes it

When to use which pattern:

See examples/flat-key-patch Section 11 for the full runnable demo.

Schema generation and OpenAPI / AsyncAPI embedding¶

EntrySlice emits the same schema as Map[K, V] — an object schema. The Go type is []R (a slice), but the wire format is a JSON object, so the schema correctly documents what is on the wire:

type: object
propertyNames:           # key codec schema — validates each JSON key
  type: string
  title: ContainerName   # set via .WithTitle() on the key codec
  minLength: 1
additionalProperties:    # value codec schema — validates each JSON value
  type: object
  properties:
    image:
      type: string
      minLength: 1
    status:
      type: string
      enum: [running, stopped]
  required: [image, status]

It embeds transparently into OpenAPI and AsyncAPI — use it anywhere you'd use any other Codec[T]:

// OpenAPI — as a response body
rest.NewRoute[GetReq, []Container]("GET", "/twins/{id}/modules",
    reqCodec,
    containersCodec,    // Codec[[]Container] — emits object schema in spec
    rest.RouteMeta{OperationID: "listModules"},
)

// AsyncAPI — as a channel payload
events.NewChannel[[]Container]("twins/{id}/modules", containersCodec,
    events.Subscribe{Summary: "Module container list from device twin."},
)

Both produce the same type: object schema in their respective specs.

propertyNames.title documents the key role. Add .WithTitle(...) on the domain string codec in your key codec to give the key a readable name in the schema:

codex.String().Refine(validate.NonEmptyString).
    WithTitle("ContainerName").
    WithDescription("Container name — appears as the JSON object key, not a value field.")

What does NOT appear in the schema: the Name field of Container — because name is not in moduleCodec. The schema documents the wire format (key = container name, value = {image, status}), not the Go struct. This is correct: on the wire, name IS the key.

Cross-field constraints: RefineFunc¶

RefineFunc wraps a func(T) error applied on both Encode and Decode. Use it to validate relationships between fields:

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

Unknown fields on decode¶

The decode loop iterates only over the fields you declared. Keys present in the incoming object but not in the codec are silently dropped — they never touch the result struct and do not cause an error.

// Wire JSON: {"name":"Alice","email":"alice@example.com","role":"admin","_internal":123}
// Codec declares: "name", "email" only
// Result: User{Name: "Alice", Email: "alice@example.com"}  ← "role", "_internal" dropped

The encode side is symmetric: Encode writes only declared fields. Any Go struct fields without a codec entry are absent from the output.

This is intentional — it makes the codec resilient to API evolution. A producer can add new fields without breaking consumers that have not declared them yet.

If you need to reject unknown fields, add a RefineFunc that compares incoming keys against the declared set. The generated schema does not emit "additionalProperties": false by default.

Encode, Decode, and Validation¶

// Decode — validates automatically
user, err := jsonFmt.Unmarshal([]byte(`{"name":"","age":-5}`))
// err: field name: constraint failed (non-empty): expected non-empty string

// Encode — also validates
data, err := jsonFmt.Marshal(User{Name: "", Age: -5})
// err: field name: constraint failed (non-empty): ...

// Validate — explicit round-trip check
if err := UserCodec.Validate(u); err != nil {
    return fmt.Errorf("constructed invalid user: %w", err)
}

Smart constructors: New and Must¶

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

// Must: panic-on-error for package-level constants and test data.
var guestUser = codex.Must(usernameCodec.New(Username("guest")))

Named per-field constructors for struct codecs¶

Codec[T].New is the one smart-constructor primitive — go-codex does not (and will not) auto-derive a NewUser(field1, field2, ...) constructor from a codex.Struct[T] codec. Two hard constraints rule that out: go-codex has no reflection and no struct-tag codec wiring (all field wiring is explicit Go code via Field/RequiredField/OptionalField/DefaultField), and Go generics cannot express a variadic-arity type parameter list, so one generic helper can't cover struct codecs of every arity.

The idiomatic pattern is a thin, hand-written wrapper that takes positional field values and delegates to Codec.New — the full codec validation (every field's Refine constraints) still runs on every call:

var UserCodec = codex.Struct[User](
    codex.RequiredField("name", nameCodec,
        func(u User) string { return u.Name },
        func(u *User, v string) { u.Name = v }),
    codex.RequiredField("age", ageCodec,
        func(u User) int { return u.Age },
        func(u *User, v int) { u.Age = v }),
)

func NewUser(name string, age int) (User, error) {
    return UserCodec.New(User{Name: name, Age: age})
}

u, err := NewUser("alice", 30)
if err != nil { return err }
// u.Name and u.Age both passed their Refine constraints

See examples/construction/main.go (Profile/NewProfile) for a runnable version.

HasCodec[T]: letting a type carry its own codec¶

Codec[T].New/Validate above always need the codec value in scope at the call site (emailCodec.New(...)). codex.HasCodec[T] is an opt-in interface — the closest Go gets to Pydantic's "the model knows how to validate/serialize itself" without inheritance (Go has none) — that lets a type declare its OWN canonical codec once, so generic helper functions can then work on it without repeating the codec's name:

// HasCodec is implemented by types that declare their canonical Codec.
type HasCodec[T any] interface {
    Codec() Codec[T]
}

func Validate[T HasCodec[T]](v T) error
func New[T HasCodec[T]](v T) (T, error)
func EncodeSelf[T HasCodec[T]](v T) (any, error)
func DecodeAs[T HasCodec[T]](raw any) (T, error)
func SchemaOf[T HasCodec[T]]() schema.Schema

A type implements it with one method:

type Image struct{ Name, Tag string }

var imageCodec = codex.Struct[Image](
    codex.RequiredField("name", codex.String().Refine(validate.NonEmptyString),
        func(i Image) string { return i.Name },
        func(i *Image, v string) { i.Name = v }),
    codex.OptionalField("tag", codex.String(),
        func(i Image) string { return i.Tag },
        func(i *Image, v string) { i.Tag = v }),
)

// Value receiver, package-level codec — the common case (no per-instance state).
func (Image) Codec() codex.Codec[Image] { return imageCodec }

...and every generic helper works on it, with zero further per-type code:

img, err := codex.New(Image{Name: "alpine", Tag: "latest"})
err = codex.Validate(img)
raw, err := codex.EncodeSelf(img)
back, err := codex.DecodeAs[Image](raw)
s := codex.SchemaOf[Image]()

Zero-value-call contract for DecodeAs/SchemaOf. Neither has a T value to call .Codec() on yet, so both call it on T's zero value (var zero T; zero.Codec()...). This is correct and side-effect-free for the documented common case (a stateless Codec()), but a HasCodec implementation whose Codec() genuinely depends on instance state must NOT be used with DecodeAs/SchemaOf — its zero value would return the WRONG codec. Validate/New/EncodeSelf have no such restriction; they always call Codec() on the actual value passed in.

This does not change the "no auto-derived NewUser(...)" decision above. HasCodec gives you generic DISPATCH over a codec you already declared by hand — it is not a way to synthesize a constructor from field names, and the same reflection/struct-tag/variadic-arity limitations still apply. Adoption is entirely opt-in, exactly like Codec[T].New itself — no existing type or package is required to implement HasCodec.

PartialField/PartialStruct: patching an existing struct¶

Struct[T]'s own Encode unconditionally writes EVERY declared field into its output map — RequiredField and OptionalField alike. There is no built-in "omit this field from the encoded object when it was never set" behavior, so a "patch"/"partial update" struct (only SOME fields set, and only those written to the wire) can't be expressed with Struct directly. PartialField/PartialStruct are a parallel interface/constructor pair — not a modification of FieldCodec/Struct — for exactly that case:

type ProfilePatch struct {
    Nickname *string
    Age      *int
}
var profilePatchCodec = codex.PartialStruct[ProfilePatch](
    codex.PartialField("nickname", codex.String(),
        func(p ProfilePatch) *string { return p.Nickname },
        func(p *ProfilePatch, v *string) { p.Nickname = v }),
    codex.PartialField("age", codex.Int(),
        func(p ProfilePatch) *int { return p.Age },
        func(p *ProfilePatch, v *int) { p.Age = v }),
)

raw, _ := profilePatchCodec.Encode(ProfilePatch{Nickname: ptr("bob")})
// raw == map[string]any{"nickname": "bob"} — "age" key is ABSENT, not null.

Every PartialField-declared field is required to be a pointer *F on T: nil means "not set, leave untouched" when encoding; non-nil means "set to this value". codec is the SAME field-level Codec[F] an existing full-struct declaration for this concept already uses — reused completely unchanged, so a patch field's validation is inherited from the base type's own codec with zero new logic. Decode is the mirror: only fields whose keys are present in the input get assigned; absent keys leave the target pointer nil. If every field is nil, Encode returns an empty map[string]any (not an error — a caller for whom an entirely-empty patch is meaningless should reject it themselves via their own domain error).

Why not just extend OptionalField? FieldCodec[T]'s sealed encode method returns (string, any, error) — no room for a "was this actually set" signal without either a breaking interface change touching every existing Field[T,F] consumer, or an ad-hoc sentinel value threaded through any (exactly the kind of implicit-behavior hack this library avoids elsewhere). A parallel interface avoids touching FieldCodec/Struct at all, and keeps Struct's well-tested "always-write-every-field" semantics completely separate from PartialStruct's "omit-when-unset" semantics — two clearly-named, single-purpose entry points instead of one function with two presence models a reader would have to hold in their head at once.

Nesting needs no special mechanism. A PartialStruct-built Codec[F] can be used as another PartialField[Outer, F]'s codec — PartialField accepts any Codec[F], and PartialStruct returns a plain Codec[T], so this is ordinary Codec[T] composability (the same way Struct already nests inside Struct today). Presence for the nested field is decided exactly like any other field: is the OUTER pointer nil? The caller only allocates the nested pointer (&SettingsPatch{Image: &img}) when it actually means to include a change inside it — there is no "auto-collapse an empty nested result" heuristic involved.

Nesting gotcha: presence is decided by != nil, not "has any inner field set" — so a non-nil-but-entirely-empty nested pointer (e.g. &SettingsPatch{} with every one of ITS OWN fields left nil) still encodes as present ("settings": {} — a key with an empty object, not an absent key). This is a natural consequence of the nil-means-unset rule, not a bug, but it's a real footgun: only allocate a nested patch pointer when you're about to set at least one field inside it.

Gotcha: named types over Map/SliceOf. codex.Map[K,V]/ codex.SliceOf[T] return a Codec over the PLAIN underlying type (map[K]V/[]T), not any named type built on top of it. If F in PartialField[T,F] is a named type (e.g. type EnvVars map[EnvVarName]EnvVar), passing that raw Map-built codec directly to PartialField fails Go's generic type inference — even though the underlying representation is identical. Fix: wrap it in a trivial identity retype via codex.MapCodecSafe (Codec[map[K]V] → Codec[NamedType]) before passing it to PartialField — see modulepatch.envVarsCodec for the reference pattern.

No new structured error types and no observer integration are needed: PartialStruct/PartialField reuse whatever errors the per-field Codec[F] values already produce (ValidationError/ValidationErrors, exactly like Struct), and are pure codec-construction primitives with no I/O, same as Struct/UntaggedUnion/TaggedUnion. See examples/go-edge-models/models/iotedge/modulepatch.ModuleFieldsPatch for a real-world worked example (patching one IoT-Edge module's fields, including a nested ModuleSettingsPatch grouping) — this subsection and .github/instructions/go-codex.instructions.md's matching section are now the authoritative design reference (the feature's roadmap doc was retired once shipped).

OmitEmptyField/OmitEmptyFieldFunc/OmitDefaultField: omitting a zero-valued field on encode¶

Struct[T]'s Encode unconditionally writes EVERY declared field into its output map — RequiredField, OptionalField, and DefaultField alike (see the "Encode note" callout above). PartialField/PartialStruct already solve "omit unset" — but only by converting every field of the struct to a pointer, a shape suited to a dedicated "patch" type, not to retrofitting onto an ordinary value-typed struct just to reduce noise on a handful of fields. OmitEmptyField/OmitEmptyFieldFunc/OmitDefaultField are a parallel, opt-in mechanism for exactly that case — no pointer reshape, and freely mixable with Required/Optional/Default fields in the SAME Struct(...) call:

type Build struct {
    Context    string
    Dockerfile string
}
var buildCodec = codex.Struct[Build](
    codex.OmitEmptyField("context", codex.String(),
        func(b Build) string { return b.Context },
        func(b *Build, v string) { b.Context = v }),
    codex.OmitEmptyFieldFunc("dockerfile", codex.String(),
        func(b Build) string { return b.Dockerfile },
        func(b *Build, v string) { b.Dockerfile = v },
        func(v string) bool { return v == "" }),
)

raw, _ := buildCodec.Encode(Build{Context: "./app"})
// raw == map[string]any{"context": "./app"} — "dockerfile" key is ABSENT, not "".

Hard usage rule — not a soft suggestion. Comparing a field's current value to Go's zero value to decide "omit it" is fundamentally ambiguous whenever the zero value is ALSO a legitimate, deliberately-chosen value (e.g. a Retries int field where 0 means "explicitly no retries," not "never touched") — the exact same long-standing criticism of encoding/json's omitempty tag. Only use this family for fields whose own documented type convention already treats the Go zero value as a first-class "absent" sentinel (this codebase's own convention for MemLimit==0, Healthcheck==Healthcheck{}, Build.Context==""). For a field where the zero value is itself meaningful, distinguishable data, use PartialField/PartialStruct instead — the pointer-based approach is the only one that can actually make that distinction.

• OmitEmptyField[T, F comparable] — the ergonomic shorthand: omits when the current value equals F's Go zero value via ==.
• OmitEmptyFieldFunc[T, F any] — the escape hatch: an explicit isEmpty func(F) bool predicate, required whenever F isn't comparable (slices, maps) or "empty" means something other than Go's zero value (e.g. a domain type's own IsSet()-style check).
• OmitDefaultField[T, F comparable] — decodes exactly like DefaultField (absent key → declared default applied) but omits the key on encode whenever the current value equals that SAME declared default — a "minimal diff" round trip. This does not modify DefaultField itself, which keeps its existing "always show the resolved value" contract (relied on by real configs that want the effective value explicit) — it's a separate, additive sibling.

Why not just change OptionalField/DefaultField directly? Both are used across dozens of existing call sites where zero (or the declared default) is legitimate, already-relied-upon data — silently flipping their encode behavior would change wire output for every existing caller with no migration path. Keeping this opt-in, per-field, and separately named avoids that blast radius entirely — exactly the same reasoning PartialField already established for staying a parallel mechanism instead of a breaking FieldCodec/Struct change.

Nil-vs-empty correctness for slices/maps. OmitEmptyFieldFunc's predicate should compare against nil, not len(s) == 0 — a nil slice means "the key was never in the wire object" (exactly what OptionalField's own decode already produces for an absent key), while a non-nil, zero-length slice ([]string{}) means "the wire explicitly had an empty array" — a genuinely different state a len()==0 check would incorrectly conflate. codex.IsZeroValue[F any](v F) bool is a ready-made, reflection-based predicate that gets this right automatically (it checks IsNil() for slices/maps/pointers, not length) — pass it explicitly to OmitEmptyFieldFunc when you don't want to hand-write s == nil yourself:

codex.OmitEmptyFieldFunc("tags", codex.SliceOf(codex.String()),
    get, set, codex.IsZeroValue)

This is go-codex's only use of reflection, and it is entirely opt-in — never a hidden default. Struct's own field constructors (RequiredField/OptionalField/DefaultField) and this family's own zero-value shorthand (OmitEmptyField[T, F comparable]) use plain == comparison, no reflection at all; codex.IsZeroValue exists purely as a convenience a caller may choose to pass to OmitEmptyFieldFunc's isEmpty parameter. This deliberately does NOT become OmitEmptyField's automatic default behavior for non-comparable types — a blind structural zero-check knows nothing about a type's own business meaning of "empty" (e.g. a domain type whose IsSet() checks only ONE of its fields, not the whole struct), so an implicit reflect-based default could silently disagree with that type's own convention.

Interaction with Template/DottedKeyCodec/DecodeVars/EncodeVars. FieldCodec[T] has four consumers besides Struct/StrictStruct — DottedKeyCodec, Template's NewTemplate/Fields(), and DecodeVars/EncodeVars. None of them route through Struct's Encode loop — they call a field's plain encode() method directly. A sparse field's plain encode() ALWAYS encodes the current value, exactly like OptionalField — it deliberately does NOT consult isEmpty. Only encodeSparse() (consulted exclusively by Struct's own type-assertion check) honors the omit rule. This guarantees a path/topic/dotted-key var declared with OmitEmptyField never silently goes missing from a URI/topic/key build merely because its value happened to be zero — in practice this scenario shouldn't arise, since path/topic template vars are conventionally always-required, but the guarantee holds regardless.

No new structured error types and no observer integration are needed: these constructors reuse whatever errors the per-field Codec[F] already produces (ValidationError/ValidationErrors, exactly like Struct), and are pure codec-construction primitives with no I/O.

Maybe[T]: definitive presence tracking¶

OmitEmptyField/OmitEmptyFieldFunc (above) solve "omit a zero-valued field on Encode" via a HEURISTIC: compare the current value to Go's zero value (or a custom predicate). This heuristic is fundamentally UNABLE to distinguish two states that are byte-identical in Go's memory model: "this field was never touched" vs. "this field was explicitly set to exactly the zero-equivalent value" (e.g. a caller who genuinely means Retries: 0, Nick: ""). codex.Maybe[T] — go-codex's Go rendering of Haskell's Maybe/Rust's Option — is a lightweight, PER-FIELD alternative: a small value type pairing a T with an explicit "was this ever set" bit (Just/Nothing), usable as the type of ONE struct field (not the whole struct) — giving OmitEmptyField-style omission a DEFINITIVE signal instead of a heuristic, without forcing every OTHER field in the struct to become a pointer too (contrast with PartialField/PartialStruct, which solves this same ambiguity but requires an ALL-pointer struct reshape).

Maybe[T] does NOT replace OmitEmptyField/OmitEmptyFieldFunc. They remain the right choice for the common case — a field whose zero-means- absent convention is already safe and documented (as with every field in dockercompose.Service). Maybe[T] is the precise escape hatch for the genuinely ambiguous cases where that heuristic isn't good enough.

type Profile struct {
    Name string
    Nick codex.Maybe[string]
}
var profileCodec = codex.Struct[Profile](
    codex.RequiredField("name", codex.String(),
        func(p Profile) string { return p.Name },
        func(p *Profile, v string) { p.Name = v }),
    codex.MaybeField("nick", codex.String(),
        func(p Profile) codex.Maybe[string] { return p.Nick },
        func(p *Profile, v codex.Maybe[string]) { p.Nick = v }),
)

var p Profile
p.Nick.Set("")     // explicitly set to "" -- NOT the same as never touched
raw, _ := profileCodec.Encode(p)
// raw == map[string]any{"name": "", "nick": ""} -- "nick" key IS present,
// because it was explicitly Set, even though its value is the zero value.
// A never-touched p.Nick (Maybe[string]{}) would omit the "nick" key
// entirely -- the exact distinction OmitEmptyField cannot make.

Maybe[T]'s API: Just(v)/Nothing[T]() construct a set/unset value; Set(v) is REPEATABLE (every call overwrites — contrast with Immutable.Set's exactly-once contract); Get() NEVER panics (returns T's zero value when unset — contrast with Immutable.Get, which panics before the first Set); IsSet()/TryGet() are the explicit-presence- check siblings. Four combinators round out the type for working with it functionally: MaybeMap[T,R](m, fn) (a free function, not a method — Go generic methods cannot introduce a new type parameter R, the same constraint forge.NewFunction[In, Out] already documents elsewhere; applies fn only if set, Nothing in → Nothing out) — named MaybeMap rather than the shorter Map to avoid colliding with the existing codex.Map[K,V] map-codec constructor; MaybeFlatMap[T,R](m, fn) (also a free function, same reasoning) chains a Maybe-returning function instead — Haskell's >>=/Rust's and_then — for the case where the transformation ITSELF might not produce a value (e.g. parsing a Maybe[string] into a Maybe[int], where the string might not parse): a Just input can still yield Nothing if fn does, unlike MaybeMap, whose fn always returns a plain R; OrElse(fallback) (the safe- default-value idiom, Rust's unwrap_or/Haskell's fromMaybe); Filter(pred) (narrows "set" down to "set AND satisfies some condition," returning Nothing otherwise).

Maybe[T] the TYPE has no ambient codec — but MaybeCodec[T] derives one, symmetric with Either2. Unlike Immutable/Mutable (which both REQUIRE a Codec[T] at construction), a bare Maybe[T] value carries no codec of its own — a zero-initialized Maybe[V]{} is already meaningful (Nothing) with no constructor call needed at all. This mirrors Either exactly: the bare Either[A,B] struct ALSO has no ambient codec — you always derive one from inner codecs (Either2(ca, cb)). MaybeCodec[T](inner Codec[T]) Codec[Maybe[T]] is Maybe's exact counterpart to Either2 — both are plain, general codec-derivation functions, usable with ANY composer (RequiredField, OptionalField, SliceOf, Map, or standalone), not just via a dedicated field constructor:

codex.MaybeCodec(codex.String()).Decode("hi")      // Just("hi")
codex.SliceOf(codex.MaybeCodec(codex.Int()))       // Codec[[]Maybe[int]]
codex.RequiredField("note", codex.MaybeCodec(codex.String()), get, set)
// -- decodes Just/Nothing correctly, but Encode ALWAYS shows the key
// (Nothing renders as "", the inner codec's zero value) -- no omission.
// Use MaybeField instead when omission-on-Nothing is what you want.

MaybeField is a documented, provable special case of this general composition — MaybeField(name, codec, get, set) behaves EXACTLY like:

codex.OmitEmptyFieldFunc(name, codex.MaybeCodec(codec), get, set,
    func(m codex.Maybe[V]) bool { return !m.IsSet() })

(TestMaybeField_EquivalentToOmitEmptyFieldFuncPlusMaybeCodec proves this by constructing a Struct BOTH ways and asserting identical Encode output for every presence state.) This is the exact same relationship StringOrInt64() already has to Either2(String(), Int64()) — a named, common-case convenience built directly on a general composition, not a separate mechanism. MaybeField's own internal implementation is left as its existing, already-tested hand-written form (not literally rewritten to call OmitEmptyFieldFunc) — the equivalence is proven by test, not by sharing code, avoiding churn to working code for a purely cosmetic reason.

How does MaybeField render in Schema? IDENTICALLY to a plain OptionalField of the same type — no oneOf/nullable/any marker distinguishing "definitively presence-tracked" from "always-shown optional." Verified by an actual render:

codex.MaybeField("nick", codex.String(), get, set)
// Schema -> {"Type": "string"} -- indistinguishable from
// codex.OptionalField("nick", codex.String(), get, set)'s OWN schema,
// and NOT present in the Struct's "Required" array.

This is correct, not a gap. MaybeCodec[T]'s Schema field is literally inner.Schema, untouched, and sparseField.schema() (shared by every sparse-family constructor — OmitEmptyField/OmitDefaultField/ MaybeField alike) always reports Required=false. The WIRE contract genuinely is identical between MaybeField and OptionalField for the same V — a valid document either omits the key or includes V's shape, in BOTH cases. Just/Nothing vs. "Go zero value" is a Go-side, POST-decode distinction with no wire-visible difference to describe — a schema correctly stays silent about a distinction that doesn't exist on the wire. (Contrast with EitherField's schema, which DOES differ visibly from a plain field's — see the Either ergonomics section below.)

Why not just use a pointer (*T), like PartialField does? A fair question, since PartialField/PartialStruct already ship and already solve this ambiguity definitively via pointers. Pointers remain the right tool for a DEDICATED patch/partial-update type where EVERY field is independently optional — the all-pointer reshape is the point there, not a cost. But reusing bare pointers as the GENERAL per-field answer has real downsides Maybe[T] avoids:

• No struct reshape required. Making one ordinary domain field's type *string instead of string touches every existing read site of that field (arithmetic, string ops, anything not expecting a pointer) — real, spread-out churn. Maybe[T] only changes what the FIELD wraps, not what every consumer must additionally nil-check.
• Safe-by-default, not panic-by-forgetting. Every pointer read site must remember to nil-check or safely dereference. Maybe[T]'s Get() is ALWAYS safe (zero value, never panics); the presence check (IsSet()/TryGet()) is the deliberate opt-in, inverting the usual pointer footgun.
• No aliasing. Copying a struct with pointer fields means BOTH copies share the same underlying value — mutating through one pointer silently affects the other. Maybe[T] carries T BY VALUE inside the wrapper; copying a Maybe[T]-containing struct copies the value too, exactly like every other value-typed field in Go.
• No extra heap allocation. Each non-nil pointer is a separate heap allocation; Maybe[T]{value T; set bool} stores T INLINE — no additional indirection beyond the struct's own layout, a real difference under load for structs with many optional fields (e.g. a hot decode path).
• No collision with Nullable[T]'s existing meaning for *T. go-codex already uses *T (via codex.Nullable[T]) for a DIFFERENT axis: wire-level explicit null vs. a real value. Reusing bare pointers ALSO for "was the Go field ever assigned" would overload one Go pattern with two different meanings depending on context.