git:20260322.a77ad54 to git:20260828.b2ef325

- Zog schema validation library: schema definition, parsing, validation, error handling, HTTP/JSON/env

- integration, custom tests, and transforms. Invoke whenever task involves any interaction with Zog — writing schemas,

- parsing input, validating structs, handling errors, or integrating with HTTP handlers.

- # Zog

-

- Zod-inspired schema validation for Go. Declarative schema builder with runtime parsing and validation. Import as

- `z "github.com/Oudwins/zog"`.

-

- <critical>

-

- - All fields are **optional by default** (opposite of Zod)

- - Schema keys in `z.Shape{}` must match **struct field names**, not input data keys — use struct tags (`json`, `form`,

- `zog`) for input key mapping

- - All schemas return `ZogIssueList`

- - Check errors with `len(errs) > 0`, not `errs != nil`

- - Zog **panics on schema misconfiguration** (destination type mismatch, missing struct fields) but never on invalid

- input data

- - Do not depend on test execution order — tests may run in parallel in future versions

-

- </critical>

-

- ## Parse vs Validate

-

- Two entry points, same schemas:

-

- - `schema.Parse(data, &dest, ...opts)` — coerces untyped input into destination. Use at IO boundaries (HTTP, JSON, env)

- - `schema.Validate(&value, ...opts)` — validates existing Go values. No coercion. More efficient when data is already

- typed

-

- **Key difference:** `Validate` treats zero values as missing when `Required()` is set. Use `z.Ptr()` + `.NotNil()` to

- distinguish "not provided" from "zero value":

-

- ```go

- // Parse can distinguish 0 from missing

- z.Int().Required().Parse(0, &dest) // ok

-

- // Validate cannot — use pointer

- z.Ptr(z.Int()).NotNil().Validate(&valPtr) // nil = missing, *0 = valid

- ```

-

- **Prefer `Validate` when data is already typed.** Use `Parse` when accepting external input that needs coercion.

-

- ## Schema Types

-

- ### Primitives

-

- All primitive `.Parse()` / `.Validate()` return `ZogIssueList`.

-

- **String:**

-

- - `z.String()` — base string schema

- - `.Trim()` — transform: trims whitespace

- - `.Min(n)`, `.Max(n)`, `.Len(n)` — length validators

- - `.Email()`, `.URL()`, `.UUID()`, `.IPv4()` — format validators

- - `.Match(regex)` — regex match

- - `.Contains(s)`, `.ContainsUpper()`, `.ContainsDigit()`, `.ContainsSpecial()` — content validators

- - `.HasPrefix(s)`, `.HasSuffix(s)` — prefix/suffix validators

- - `.OneOf([]string{...})` — enum-like validation (replaces Zod's `z.Enum()`)

- - `.Not()` — negates the next test

-

- **Numbers:**

-

- - `z.Int()`, `z.Int32()`, `z.Int64()`, `z.Float32()`, `z.Float64()` — numeric schemas

- - `.GT(n)`, `.GTE(n)`, `.LT(n)`, `.LTE(n)`, `.EQ(n)` — comparison validators

- - `.OneOf([]T{...})` — enum-like validation

- - `.Not()` — negates the next test

-

- **Bool:**

-

- - `z.Bool()` — boolean schema

- - `.True()`, `.False()`, `.EQ(v)` — value validators

-

- **Time:**

-

- - `z.Time()` — validates `time.Time`

- - `.After(t)`, `.Before(t)`, `.Is(t)` — temporal validators

- - `z.Time(z.Time.Format(layout))` — parse strings using layout (default: `time.RFC3339`). Coercion only works with

- `Parse()`, not `Validate()`

-

- ### Complex Types

-

- **Struct:**

-

- ```go

- schema := z.Struct(z.Shape{

- "name": z.String().Required(),

- "age": z.Int().GT(0),

- })

- ```

-

- - `.Pick("key1", map[string]bool{"a": true})` — shallow copy with only specified fields

- - `.Omit("key1", map[string]bool{"a": true})` — shallow copy without specified fields

- - `.Extend(z.Shape{...})` — shallow copy with additional fields

- - `.Merge(other1, other2)` — merge schemas, last wins on conflict

- - Structs cannot be `Required()` or `Optional()` — use `z.Ptr(z.Struct(...))` for optional structs

-

- **Slice:**

-

- ```go

- schema := z.Slice(z.String().Required())

- ```

-

- - `.Min(n)`, `.Max(n)`, `.Length(n)` — size validators

- - `.Contains(val)` — element presence validator

- - `.Not()` — negates the next test

-

- **Pointer:**

-

- ```go

- z.Ptr(z.String()) // pointer to string

- ```

-

- - `.NotNil()` — equivalent to `Required()` for other types

-

- **Boxed:**

-

- ```go

- z.Boxed[BoxType, InnerType](innerSchema, unboxFunc, boxFunc)

- ```

-

- Wraps a schema with custom box/unbox logic for types like `sql.NullString`, `driver.Valuer`, or custom wrappers. The

- `unboxFunc` extracts the inner value; `boxFunc` creates the wrapper from validated value (can be `nil` if boxing not

- needed).

-

- ### Custom Primitive Schemas

-

- For named types based on primitives:

-

- ```go

- type Env string

- z.StringLike[Env]().OneOf([]Env{"prod", "dev"})

- ```

-

- Available: `z.StringLike[T]()`, `z.IntLike[T]()`, `z.FloatLike[T]()`, `z.UintLike[T]()`, `z.BoolLike[T]()`

-

- ### CustomFunc

-

- Quick validation for non-primitive types without defining a full schema:

-

- ```go

- z.CustomFunc(func(valPtr *uuid.UUID, ctx z.Ctx) bool {

- return valPtr.IsValid()

- }, z.Message("invalid uuid"))

- ```

-

- Does not support coercion.

-

- ## Generic Schema Methods

-

- Available on all schema types:

-

- - `.Required()` — field must be present and non-zero

- - `.Optional()` — field can be absent (default behavior)

- - `.Default(val)` / `.DefaultFunc(fn)` — use this value when input is zero. Takes priority over `Required()`. Tests

- still run

- - `.Catch(val)` / `.CatchFunc(fn)` — on any error, set destination to this value and stop execution

- - `.Test(z.Test{...})` — complex custom test (like Zod's `superRefine`)

- - `.TestFunc(fn, ...opts)` — simple custom test (like Zod's `refine`)

- - `.Transform(func(valPtr *T, ctx z.Ctx) error)` — post-validation in-place mutation

-

- Execution order: nil check → default/required → coerce → validation loop (tests + transforms in order) → catch on error

-

- ## Struct Tags

-

- Schema keys match struct field names by default. Use struct tags for input key mapping:

-

- - `json` — JSON input

- - `form` — form data

- - `query` — query params

- - `env` — environment variables

- - `zog` — catch-all, works for any input

-

- Priority: `json`/`form`/`query`/`env` → `zog` → schema field name

-

- ```go

- type User struct {

- Name string `zog:"first-name"`

- LastName string `query:"last_name" json:"last-name"`

- }

- ```

-

- ## Custom Tests

-

- **Simple (refine-like):** Return `bool` — Zog creates the issue:

-

- ```go

- z.String().TestFunc(func(data *string, ctx z.Ctx) bool {

- return *data == "expected"

- }, z.Message("must be expected"))

- ```

-

- For structs/slices, the parameter is `any` — cast manually:

-

- ```go

- z.Struct(z.Shape{...}).TestFunc(func(dataPtr any, ctx z.Ctx) bool {

- user := dataPtr.(*User)

- return user.Name != ""

- })

- ```

-

- **Complex (superRefine-like):** Add issues manually via context:

-

- ```go

- z.String().Test(z.Test{

- Func: func(val any, ctx z.Ctx) {

- s := val.(string)

- if !isValid(s) {

- ctx.AddIssue(ctx.Issue().SetMessage("invalid value"))

- }

- },

- })

- ```

-

- **Reusable tests:** Wrap in functions returning `z.Test[T]`:

-

- ```go

- func MinWords(n int, opts ...z.TestOption) z.Test[any] {

- options := []z.TestOption{z.Message(fmt.Sprintf("must have at least %d words", n))}

- options = append(options, opts...)

- return z.TestFunc(func(val any, ctx z.Ctx) bool {

- s := val.(*string)

- return len(strings.Fields(*s)) >= n

- }, options...)

- }

- ```

-

- ## Transforms

-

- Post-validation mutation via pointer. Runs in declaration order with tests:

-

- ```go

- z.String().Min(3).Transform(func(valPtr *string, ctx z.Ctx) error {

- *valPtr = strings.ToLower(*valPtr)

- return nil

- })

- ```

-

- Struct transforms receive `any` — cast to struct pointer:

-

- ```go

- z.Struct(z.Shape{...}).Transform(func(dataPtr any, ctx z.Ctx) error {

- user := dataPtr.(*User)

- user.FullName = user.First + " " + user.Last

- return nil

- })

- ```

-

- Returning an error from a transform stops execution and produces an issue.

-

- ## Preprocess

-

- Transform input **before** parsing. Pure function — creates a copy:

-

- ```go

- z.Preprocess(func(data any, ctx z.Ctx) (any, error) {

- s, ok := data.(string)

- if !ok {

- return nil, fmt.Errorf("expected string, got %T", data)

- }

- return strings.Split(s, ","), nil

- }, z.Slice(z.String().Email().Required()))

- ```

-

- **Footgun:** With `Validate()`, the `data` argument is a pointer to the value, not the raw input.

-

- ## Error Handling

-

- ### ZogIssue

-

- ```go

- type ZogIssue struct {

- Code zconst.ZogIssueCode // issue identifier (e.g., "required", "min", "email")

- Path []string // location in data structure (nil for root primitives)

- Value any // input value that caused the issue

- Dtype string // destination type

- Params map[string]any // test parameters (may be nil)

- Message string // human-readable, user-safe message

- Err error // underlying error or nil

- }

- ```

-

- All schemas return `ZogIssueList = []*ZogIssue`. Each issue has a `Path` field:

-

- - Primitive root: `nil`

- - Struct field: `[]string{"name"}`

- - Nested: `[]string{"address", "streets", "[0]"}`

- - Path to string: `issue.PathString()` or `z.Issues.FlattenPath(issue.Path)`

-

- ### Formatting Strategies

-

- - `z.Issues.Flatten(errs)` — `map[path][]messages`. Root issues under `"$root"` key (`zconst.ISSUE_KEY_ROOT`)

- - `z.Issues.Treeify(errs)` — nested tree mirroring data structure. Each node has `errors` array and `properties`/`items`

- - `z.Issues.Prettify(errs)` — human-readable string with `✖` prefix and `→ at path` lines

-

- ### Issue Codes

-

- Common codes: `required`, `coerce`, `custom`, `min`, `max`, `len`, `email`, `uuid`, `url`, `match`, `gt`, `gte`, `lt`,

- `lte`, `eq`, `one_of_options`, `after`, `before`, `true`, `false`, `prefix`, `suffix`, `contains_upper`,

- `contains_digit`, `contains_special`, `contained`

-

- HTTP-specific: `invalid_json`, `invalid_form`, `invalid_query`

-

- ### Custom Messages

-

- Per-test: `z.Message("text")`, `z.MessageFunc(fn)`, `z.IssueCode("code")`, `z.IssuePath("path")`

-

- ```go

- z.String().Min(5, z.Message("must be at least 5 chars"))

- ```

-

- Per-execution: `z.WithIssueFormatter(fn)` — overrides all messages for one `Parse`/`Validate` call

-

- Global: Override `conf.DefaultIssueMessageMap[zconst.TypeString][zconst.IssueCodeRequired]` or replace

- `conf.IssueFormatter`

-

- ## Test Options

-

- Options passed to any test:

-

- - `z.Message("...")` — static issue message

- - `z.MessageFunc(func(e *ZogIssue, ctx z.Ctx))` — dynamic issue message

- - `z.IssueCode("...")` — override issue code

- - `z.IssuePath("...")` — override issue path

-

- ## Execution Options

-

- Options passed to `Parse()` / `Validate()`:

- - `z.WithCoercer(fn)` — per-schema coercion override (Parse only)

- - `z.WithIssueFormatter(fn)` — override message formatting for this execution

- - `z.WithCtxValue(key, val)` — pass custom data to tests/transforms via `ctx.Get(key)`

- ## Context

- `z.Ctx` interface available in tests, transforms, and preprocessors:

- - `ctx.Get(key)` — retrieve value set via `z.WithCtxValue()`

- - `ctx.AddIssue(issue)` — add a custom issue

- - `ctx.Issue()` — create a new issue pre-filled with current schema context (path, value, type)

- ## HTTP Integration (zhttp)

- ```go

- import "github.com/Oudwins/zog/zhttp"

- errs := userSchema.Parse(zhttp.Request(r), &user)

- ```

- `zhttp.Request(r)` auto-detects content type (JSON, form, query params). Only supports parsing into structs.

- Invalid input produces a root issue with code `invalid_json`, `invalid_form`, or `invalid_query` — the schema does not

- run.

- ## JSON Integration (zjson)

- ```go

- import "github.com/Oudwins/zog/parsers/zjson"

- errs := userSchema.Parse(zjson.Decode(bytes.NewReader(jsonBytes)), &user)

- ```

- Accepts `io.Reader` or `io.ReaderCloser`. Only supports structs.

- ## Environment Variables (zenv)

- ```go

- import "github.com/Oudwins/zog/zenv"

- errs := envSchema.Parse(zenv.NewDataProvider(), &cfg)

- ```

- Use `env` or `zog` struct tags for key mapping. Coercion handles string-to-type conversion automatically.

- ## i18n

- ```go

- import (

- "github.com/Oudwins/zog/i18n"

- "github.com/Oudwins/zog/i18n/en"

- "github.com/Oudwins/zog/i18n/es"

- )

- // Setup

- i18n.SetLanguagesErrsMap(map[string]i18n.LangMap{

- "en": en.Map,

- "es": es.Map,

- }, "en") // default language

- // Per-execution

- schema.Parse(data, &dest, z.WithCtxValue(i18n.LangKey, "es"))

- ```

- Single language: set `conf.DefaultErrMsgMap = es.Map`.

- ## Global Configuration

- Via `github.com/Oudwins/zog/conf`:

- - `conf.Coercers.Float64 = func(data any) (any, error) {...}` — override type coercion

- - `conf.DefaultCoercers.Float64(data)` — fallback to default coercer

- - `conf.DefaultIssueMessageMap` — override issue messages per type and code

- - `conf.IssueFormatter` — replace the global issue formatter

- ## Patterns

- ### Struct Validate Method

- ```go

- var userSchema = z.Struct(z.Shape{

- "ID": z.Int().Required(),

- "Name": z.String().Required().Min(2),

- })

- func (u *User) Validate() z.ZogIssueList {

- return userSchema.Validate(u)

- }

- ```

- ### HTTP Handler

- ```go

- func handleCreate(w http.ResponseWriter, r *http.Request) {

- var user User

- if errs := userSchema.Parse(zhttp.Request(r), &user); len(errs) > 0 {

- w.WriteHeader(http.StatusBadRequest)

- json.NewEncoder(w).Encode(z.Issues.Flatten(errs))

- return

- }

- // user is valid and populated

- }

-

- ### Environment Config

-

- ```go

- var envSchema = z.Struct(z.Shape{

- "PORT": z.Int().GT(1000).LT(65535).Default(3000),

- "DB_HOST": z.String().Default("localhost"),

- })

-

- var Env = func() Config {

- var c Config

- if errs := envSchema.Parse(zenv.NewDataProvider(), &c); len(errs) > 0 {

- log.Fatal(z.Issues.Prettify(errs))

- }

- return c

- }()

- ## Limitations

-

- - No `z.Map()` schema

- - `zhttp` and `zjson` only parse into structs

- - Structs/slices do not support `Catch()`; structs do not support `Default()`

- - Deeply nested schemas incur reflection overhead

- - `Pick`, `Omit`, `Extend`, `Merge` are not type-safe

-

- ## Application

-

- When **writing** code with Zog: apply all conventions silently — don't narrate each rule. Always check errors with

- `len(errs) > 0`. Define schemas as package-level `var`, not inside functions. If an existing codebase contradicts a

- convention, follow the codebase and flag the divergence once.

- When **reviewing** code with Zog: cite the specific violation and show the fix inline. Proactively flag: `errs != nil`

- checks (must be `len(errs) > 0`), missing `Required()` on mandatory fields, schema keys not matching struct field names,

- and missing struct tags for external input mapping.

- ## Integration

- The **golang** skill governs Go language conventions. This skill governs Zog-specific API and patterns. When both apply,

- Zog idioms (e.g., `z.Shape{}` key naming) take precedence over general Go naming rules within schema definitions.