ZOG - A Zod & Yup like Schema Parser & Validator for GO

Zog is a schema builder for runtime value parsing and validation. Define a schema, transform a value to match, assert the shape of an existing value, or both. Zog schemas are extremely expressive and allow modeling complex, interdependent validations, or value transformations.

Killer Features:

• Concise yet expressive schema interface, equipped to model simple to complex data models
• Zod-like API, use method chaining to build schemas in a typesafe manner
• Extensible: add your own Tests and Schemas
• Rich errors with detailed context, make debugging a breeze
• Fast: Zog is one of the fastest Go validation libraries. We are just behind the goplayground/validator for most of the govalidbench benchmarks.
• Built-in coercion support for most types
• Zero dependencies!
• Four Helper Packages
  • zenv: parse environment variables
  • zhttp: parse http forms & query params
  • zjson: parse json
  • i18n: Opinionated solution to good i18n zog errors

API Stability:

• I will consider the API stable when we reach v1.0.0
• However, I believe very little API changes will happen from the current implementation. The APIs most likely to change are the data providers (please don't make your own if possible use the helpers whose APIs will not change meaningfully) and the z.Ctx most other APIs should remain the same. I could be wrong but I don't expect many breaking changes.
• Although we want to keep breaking changes to a minimum, Zog is still in version 0 and will have breaking changes in the minor versions as per semver. So please be careful when upgrading minor versions.

Introduction

0. Read the docs at zog.dev

Or don't, below is the quickstart guide

1 Install

go get github.com/Oudwins/zog

2 Create a user schema and its struct

import (
	z "github.com/Oudwins/zog"
)

type User struct {
	Name string
	Age  int
}

var userSchema = z.Struct(z.Schema{
	// its very important that schema keys like "name" match the struct field name NOT the input data
	"name": z.String().Min(3, z.Message("Override default message")).Max(10),
	"age":  z.Int().GT(18),
})

3 Validate your schema

Using schema.Parse()

func main() {
	u := User{}
	m := map[string]string{
		"name": "Zog",
		"age":       "",    // won't return an error because fields are optional by default
	}
	errsMap := userSchema.Parse(m, &u)
	if errsMap != nil {
		// handle errors -> see Errors section
	}
	u.Name // "Zog"
	// note that this might look weird but we didn't say age was required so Zog just skipped the empty string and we are left with the uninitialized int
	// If we need 0 to be a valid value for age we can use a pointer to an int which will be nil if the value was not present in the input data
	u.Age // 0
}

Using schema.Validate()

func main() {
	u := User{
		Name: "Zog",
		Age:  0, // wont return an error because fields are optional by default otherwise it will error
	}
	errsMap := userSchema.Validate(&u)
	if errsMap != nil {
		// handle errors -> see Errors section
	}
}

4. Its easy to use with http & json

The zhttp package has you covered for JSON, Forms and Query Params, just do:

import (
	zhttp "github.com/Oudwins/zog/zhttp"
)

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

If you are receiving json some other way you can use the zjson package

import (
	zjson "github.com/Oudwins/zog/zjson"
)

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

5. Or to validate your environment variables

The zenv package has you covered, just do:

import (
	zenv "github.com/Oudwins/zog/zenv"
)

err := envSchema.Parse(zenv.NewDataProvider(), &envs)

6. You can also parse individual fields

var t = time.Time
errsList := Time().Required().Parse("2020-01-01T00:00:00Z", &t)

7 And do stuff before and after parsing

var dest []string
Slice(String().Email().Required()).PreTransform(func(data any, ctx z.Ctx) (any, error) {
	s := data.(string)
	return strings.Split(s, ","), nil
}).PostTransform(func(destPtr any, ctx z.Ctx) error {
	s := destPtr.(*[]string)
	for i, v := range *s {
		(*s)[i] = strings.TrimSpace(v)
	}
	return nil
}).Parse("foo@bar.com,bar@foo.com", &dest) // dest = [foo@bar.com bar@foo.com]

Roadmap

These are some of the things I want to add to zog before v1.0.0

• Support for schema.Clone()
• support for catch & default for structs & slices
• Struct generation from the schemas

Support

The damm domain costs me some outrageous amount like 100$ a year, so if any one wants to help cover that cost through github sponsors that is more than welcome.

Acknowledgments

• Big thank you to @AlexanderArvidsson for being there to talk about architecture and design decisions. It helped a lot to have someone to bounce ideas off of
• Credit for all the inspiration goes to /colinhacks/zod & /jquense/yup
• Credit for the initial idea goes to anthony (@anthonyGG) -> /anthdm/superkit he made a hacky version of this idea that I used as a starting point, I was never happy with it so I inspired me to rewrite it from scratch. I owe him a lot
• Credit for the zod logo goes to /colinhacks/zod

License

This project is licensed under the MIT License - see the LICENSE file for details.