Skip to main content

Overview

In zog issues represent something that went wrong during any step of the parsing execution structure.

Most of the time, you will be interacting with Zog issues through:

Zod has Errors and Issues, issues are the structure thrown by Zod while Issues are the issues generated by the validation tests. In Zog we do not throw errors. But each issue may have an optional error inside it. If present this is the underlying error that caused the issue. For example the error generated trying to unmarshal json which is wrapped in a z.Issue to avoid exposing the underlying error to the user.

The ZogIssue​

The ZogIssue is a struct that contains multiple fields and has some helper setter methods. It looks like this:

// ZogIssue represents an issue that occurred during parsing or validation.
// When printed it looks like:
// ZogIssue{Code: coercion_issue, Params: map[], Type: number, Value: not_empty, Message: number is invalid, Error: failed to coerce string int: strconv.Atoi: parsing "not_empty": invalid syntax}
type ZogIssue struct {
	// Code is the unique identifier for the issue. Generally also the ID for the Test that caused the issue. See below for a full list
	Code zconst.ZogIssueCode
	// Path is the path to the field that caused the issue
	Path []string
	// Value is the data value that caused the issue.
	// If using Schema.Parse(data, dest) then this will be the value of data.
	Value any
	// Dtype is the destination type. i.e The zconst.ZogType of the value that was validated.
	// If using Schema.Parse(data, dest) then this will be the type of dest.
	Dtype string
	// Params is the params map for the issue. Taken from the Test that caused the issue.
	// This may be nil if Test has no params.
	Params map[string]any
	// Message is the human readable, user-friendly message for the issue.
	// This is safe to expose to the user.
	Message string
	// Err is the wrapped error or nil if none
	Err error
}

ZogIssueList​

All schemas return a ZogIssueList, which is a slice of ZogIssue instances:

type ZogIssueList = []*ZogIssue

Each issue contains a Path field that indicates where in your data structure the issue occurred:

// String schema - Path is nil for root-level primitive
errList := z.String().Min(5).Email().Parse("foo", &dest)
// errList[0].Path = nil, errList[0].Message = "min length is 5"

// Struct schema - Path contains the field name as a slice
errList := z.Struct(z.Shape{"name": z.String().Min(5)}).Parse(data, &dest)
// errList[0].Path = []string{"name"}, errList[0].Message = "min length is 5"

// Nested structs and slices - Path is a slice of path segments
errList := z.Struct(z.Shape{
    "address": z.Struct(z.Shape{
        "streets": z.Slice(z.String().Min(10)),
    }),
}).Parse(data, &dest)
// errList[0].Path = []string{"address", "streets", "[0]"}, errList[0].Message = "min length is 10"
// You can convert Path to a string using Issues.FlattenPath(issue.Path) or issue.PathString()

Issue Codes​

Error codes are unique identifiers for each type of issue that can occur in Zog. They are used to generate issue messages and to identify the issue in the issue formatter. A full updated list of issue codes can be found in the zconst package. But here are some common ones:

type ZogIssueCode = string

const (
	IssueCodeCustom   ZogIssueCode = "custom"   // all
	IssueCodeRequired ZogIssueCode = "required" // all
	IssueCodeCoerce   ZogIssueCode = "coerce"   // all
	IssueCodeFallback ZogIssueCode = "fallback" // all. Applied when other errror code is not implemented. Required to be implemented for every zog type!

	IssueCodeEQ    ZogIssueCode = "eq"             // number, time, string
	IssueCodeOneOf ZogIssueCode = "one_of_options" // string or number

	IssueCodeMin      ZogIssueCode = "min"       // string, slice
	IssueCodeMax      ZogIssueCode = "max"       // string, slice
	IssueCodeLen      ZogIssueCode = "len"       // string, slice
	IssueCodeContains ZogIssueCode = "contained" // string, slice

	// number only
	IssueCodeLTE ZogIssueCode = "lte" // number
	IssueCodeLT  ZogIssueCode = "lt"  // number
	IssueCodeGTE ZogIssueCode = "gte" // number
	IssueCodeGT  ZogIssueCode = "gt"  // number

	// string only
	IssueCodeEmail           ZogIssueCode = "email"
	IssueCodeUUID            ZogIssueCode = "uuid"
	IssueCodeMatch           ZogIssueCode = "match"
	IssueCodeURL             ZogIssueCode = "url"
	IssueCodeHasPrefix       ZogIssueCode = "prefix"
	IssueCodeHasSuffix       ZogIssueCode = "suffix"
	IssueCodeContainsUpper   ZogIssueCode = "contains_upper"
	IssueCodeContainsLower   ZogIssueCode = "contains_lower"
	IssueCodeContainsDigit   ZogIssueCode = "contains_digit"
	IssueCodeContainsSpecial ZogIssueCode = "contains_special"
	// time only
	IssueCodeAfter  ZogIssueCode = "after"
	IssueCodeBefore ZogIssueCode = "before"
	// bool only
	IssueCodeTrue  ZogIssueCode = "true"
	IssueCodeFalse ZogIssueCode = "false"

	// ZHTTP ERRORS
	IssueCodeZHTTPInvalidJSON  ZogIssueCode = "invalid_json"  // invalid json body
	IssueCodeZHTTPInvalidForm  ZogIssueCode = "invalid_form"  // invalid form data
	IssueCodeZHTTPInvalidQuery ZogIssueCode = "invalid_query" // invalid query params
)