Migrating from 0.21 to 0.22

This guide helps you migrate from the dual return type system (ZogIssueList for primitives, ZogIssueMap for complex schemas) to the unified ZogIssueList return type.

What's changed?

1. ZogIssueMap was removed and all schemas now return ZogIssueList
2. ZogIssue.Path is now a slice of strings instead of a string (You can still get the previous path string via Issues.FlattenPath(issue.Path) or issue.PathString()). Now root errors have a nil path instead of an empty string as the path.

Why This Change?

Previously, Zog had two different return types:

• Primitive schemas (String, Int, Bool, Time) returned ZogIssueList
• Complex schemas (Struct, Slice, Pointer) returned ZogIssueMap

The main reason for this change is that I wanted to provide many ways to format the many issue messages a schema might generate. Locking you into a map[path][]issue was unnecesarily restrictive. heavily inspired by Zod v4's error formatting

Quick Migration

Error Checking

// Before (complex schemas):
err := userSchema.Parse(data, &user)
if err != nil {
    // handle errors
}

// After (all schemas):
err := userSchema.Parse(data, &user)
if len(err) > 0 {
    // handle errors
}

Message sanitization

// before
messages = z.Issues.Sanitize(err)
// After
messages = z.Issues.Flatten(err) // or one of the other strategies

Getting the First Error

// Before:
first := errs["$first"][0]

// After (option 1 - direct):
first := errs[0]

Creating previous error map

If you have extensive code using the old map format, you can use the conversion helper:

errs := userSchema.Parse(data, &user)
errsMap := z.Issues.GroupByFlattenedPath(errs)

// Now use errsMap like before
if nameErrs, ok := errsMap["name"]; ok {
    // ...
}

Note: Before using this consider if Issues.Flattened or another one of the formatting strategies is not a better fit

Method Return Type Changes

Schema	Before	After
StringSchema.Parse()	ZogIssueList	ZogIssueList
StringSchema.Validate()	ZogIssueList	ZogIssueList
NumberSchema.Parse()	ZogIssueList	ZogIssueList
NumberSchema.Validate()	ZogIssueList	ZogIssueList
BoolSchema.Parse()	ZogIssueList	ZogIssueList
BoolSchema.Validate()	ZogIssueList	ZogIssueList
TimeSchema.Parse()	ZogIssueList	ZogIssueList
TimeSchema.Validate()	ZogIssueList	ZogIssueList
StructSchema.Parse()	ZogIssueMap	ZogIssueList
StructSchema.Validate()	ZogIssueMap	ZogIssueList
SliceSchema.Parse()	ZogIssueMap	ZogIssueList
SliceSchema.Validate()	ZogIssueMap	ZogIssueList
PointerSchema.Parse()	ZogIssueMap	ZogIssueList
PointerSchema.Validate()	ZogIssueMap	ZogIssueList
BoxedSchema.Parse()	ZogIssueMap	ZogIssueList
BoxedSchema.Validate()	ZogIssueMap	ZogIssueList