zog-best-practices

Zog Usage

Use this skill when writing, reviewing, or debugging Go code that uses github.com/Oudwins/zog.

1. What Is Zog

Zog is a Zod-inspired schema validation and parsing library for Go. The API is chainable and schema-first: define a schema, then either parse external input into a destination or validate an already-built Go value.

Zog is useful for HTTP handlers, JSON input, environment variables, config, forms, and any place where Go values need validation plus optional coercion.

2. Defining A Schema

Define reusable schemas with z.Struct(z.Shape{...}) and primitive schema builders like z.String(), z.Int(), z.Bool(), z.Time(), z.Slice(...), and z.Ptr(...).

import z "github.com/Oudwins/zog"

type User struct {
	Name string `json:"name" zog:"name"`
	Age  int    `json:"age" zog:"age"`
}

var userSchema = z.Struct(z.Shape{
	"Name": z.String().Required().Min(3),
	"Age":  z.Int().Required().GT(18),
})

Schema keys for structs are Go field names. Tags such as json, zog, or env map external input keys to those fields during parsing.

type User struct {
	Name string `json:"name" zog:"name"`
}

var userSchema = z.Struct(z.Shape{
	"Name": z.String().Required(), // Go field name, not "name"
})

3. Validating And Parsing

Use Parse(data, &dest) when input is external or loosely typed. Parse can coerce values and writes into the destination.

var user User
errs := userSchema.Parse(map[string]any{"name": "Ada", "age": "42"}, &user)
if errs != nil {
	return errs
}

Use Validate(&value) when the value is already a typed Go value and you only need validation.

user := User{Name: "Ada", Age: 42}
errs := userSchema.Validate(&user)
if errs != nil {
	return errs
}

Zog returns z.ZogIssueList; nil means success. If relevant to the task, fetch https://zog.dev/errors/overview.md for error concepts, or https://zog.dev/errors/formatting.md for helpers like z.Issues.Flatten, z.Issues.Treeify, z.Issues.Prettify, and custom response formatting.

4. Supporting Packages

• zhttp: parse http.Request JSON, form, multipart-after-manual-parse, or query input.
• zjson: parse JSON readers into structs.
• zenv: parse environment variables into typed config structs.
• i18n: configure localized error messages.
• zconst: constants for issue codes, types, and tags.

5. Common Mistakes

Mistake: Using JSON Names As Struct Schema Keys

Wrong:

var schema = z.Struct(z.Shape{
	"name": z.String().Required(),
})

Correct:

type User struct {
	Name string `json:"name" zog:"name"`
}

var schema = z.Struct(z.Shape{
	"Name": z.String().Required(),
})

Mistake: Forgetting That Fields Are Optional By Default

Wrong:

var schema = z.Struct(z.Shape{
	"Email": z.String().Email(), // missing input is allowed
})

Correct:

var schema = z.Struct(z.Shape{
	"Email": z.String().Required().Email(),
})

Mistake: Passing Non-Pointers To Execution Methods

Wrong:

var user User
errs := userSchema.Parse(data, user)
errs := userSchema.Validate(user)

Correct:

var user User
errs := userSchema.Parse(data, &user)
errs := userSchema.Validate(&user)

Mistake: Treating Parse And Validate As Interchangeable

Wrong:

// Validating an already-zero-valued struct cannot prove an absent field was present.
var user User
errs := userSchema.Validate(&user)

Correct:

// Use Parse for external input when presence and coercion matter.
var user User
errs := userSchema.Parse(input, &user)

Mistake: Blind Type Assertions In Preprocessors

Wrong:

schema := z.Preprocess(func(data any, ctx z.Ctx) (any, error) {
	return strings.Split(data.(string), ","), nil
}, z.Slice(z.String()))

Correct:

schema := z.Preprocess(func(data any, ctx z.Ctx) (any, error) {
	s, ok := data.(string)
	if !ok {
		return nil, fmt.Errorf("expected string but got %T", data)
	}
	return strings.Split(s, ","), nil
}, z.Slice(z.String()))

6. Best Practices

Reuse Schemas Instead Of Rebuilding Them

Prefer global or package-level schemas for hot paths such as HTTP requests.

var createUserSchema = z.Struct(z.Shape{
	"Name": z.String().Required().Min(3),
	"Age":  z.Int().Required().GT(18),
})

func handleCreateUser(w http.ResponseWriter, r *http.Request) {
	var user User
	errs := createUserSchema.Parse(zhttp.Request(r), &user)
	_ = errs
}

If a schema must be built dynamically and performance matters, consider sync.Pool to reuse schemas.

Prefer Validate When Coercion Is Not Needed

Validate is faster than Parse when you already have a typed Go value.

func saveUser(user *User) error {
	if errs := userSchema.Validate(user); errs != nil {
		return fmt.Errorf("invalid user: %v", z.Issues.Flatten(errs))
	}
	return nil
}

Collect Issues After Using Them On Hot Paths

Issue generation is allocation-heavy. After formatting or logging issues, collect them for reuse.

errs := userSchema.Validate(&user)
if errs != nil {
	defer z.Issues.Collect(errs)
	return z.Issues.Flatten(errs)
}

Wrap Reusable Custom Tests

Use helper functions for repeated custom validation so messages and options stay consistent.

func StrongPassword(opts ...z.TestOption) z.Test[*string] {
	return z.TestFunc("strong_password", func(password *string, ctx z.Ctx) bool {
		return len(*password) >= 12
	}, opts...)
}

var schema = z.Struct(z.Shape{
	"Password": z.String().Required().Test(StrongPassword()),
})

Be Careful With Global Configuration

The conf package changes behavior globally for all schemas. Prefer local schema options unless the whole application needs the change.

conf.Coercers.Float64 = func(data any) (any, error) {
	if str, ok := data.(string); ok && strings.Contains(str, ",") {
		return parseCommaFloat(str)
	}
	return conf.DefaultCoercers.Float64(data)
}

References

• Full API Reference: https://zog.dev/reference.md
• Package docs:
• zhttp: https://zog.dev/packages/zhttp.md
• zjson: https://zog.dev/packages/zjson.md
• zenv: https://zog.dev/packages/zenv.md
• i18n: https://zog.dev/packages/i18n.md
• zconst: https://zog.dev/packages/zconst.md
• internals: https://zog.dev/packages/internals.md
• When fetched docs pages contain relative links, follow them as markdown by using https://zog.dev/{relative_path}.md.

SOP

When using this skill, first understand the user's request and identify which Zog concepts or packages are involved. Fetch the reference or package docs above only when they are relevant or needed to avoid guessing. After gathering the necessary context, perform the user's request.