Hypersequent/zen

README

Zen

Zod + Generate = Zen

Converts Go structs with go-validator validations to Zod schemas.

Zen supports self-referential types and generic types. Other cyclic types (apart from self referential types) are not supported as they are not supported by zod itself.

Zen emits Zod v4 schemas by default. Use zen.WithZodV3() if you need the previous output style for snapshot compatibility or incremental migration.

Usage

type Post struct {
	Title string `validate:"required"`
}
type User struct {
	Name       string     `validate:"required"`
	Nickname   *string    // pointers become optional
	Age        int        `validate:"min=18"`
	Height     float64    `validate:"min=0,max=3"`
	Tags       []string   `validate:"min=1"`
	Favourites []struct { // nested structs are kept inline
		Name string `validate:"required"`
	}
	Posts []Post // external structs are emitted as separate exports
}
fmt.Print(zen.StructToZodSchema(User{}))

// Self referential types are supported
type Tree struct {
	Value    int
	Children []Tree
}
fmt.Print(zen.StructToZodSchema(Tree{}))

// We can also use create a converter and convert multiple types together
c := zen.NewConverterWithOpts()

// Generic types are also supported
type GenericPair[T any, U any] struct {
	First  T
	Second U
}
type StringIntPair GenericPair[string, int]
c.AddType(StringIntPair{})

// For non-defined types, the type arguments are appended to the generic type
// name to get the type name
c.AddType(GenericPair[int, bool]{})

// Even nested generic types are supported
type PairMap[K comparable, T any, U any] struct {
	Items map[K]GenericPair[T, U] `json:"items"`
}
c.AddType(PairMap[string, int, bool]{})

// Now export the generated schemas. Duplicate schemas are skipped
fmt.Print(c.Export())

Legacy v3-compatible output is still available:

fmt.Print(zen.StructToZodSchema(User{}, zen.WithZodV3()))

The main migration differences are:

string format tags such as email, http_url, ipv4, uuid4, and md5 now use Zod v4 helpers like z.email(), z.url({ protocol: /^https?$/ }), z.ipv4(), z.uuid({ version: "v4" }), and z.hash("md5")
ip and ip_addr now emit z.union([z.ipv4(), z.ipv6()])
embedded anonymous structs now expand through .shape spreads instead of .merge(...)
enum-like map keys now emit z.partialRecord(...)

Outputs:

export const PostSchema = z.object({
  Title: z.string().min(1),
})
export type Post = z.infer<typeof PostSchema>

export const UserSchema = z.object({
	Name: z.string().min(1),
	Nickname: z.string().nullable(),
	Age: z.number().gte(18),
	Height: z.number().gte(0).lte(3),
	Tags: z.string().array().min(1),
	Favourites: z.object({
		Name: z.string().min(1),
	}).array().nullable(),
	Posts: PostSchema.array().nullable(),
})
export type User = z.infer<typeof UserSchema>

export type Tree = {
	Value: number,
	Children: Tree[] | null,
}
export const TreeSchema: z.ZodType<Tree> = z.object({
	Value: z.number(),
	Children: z.lazy(() => TreeSchema).array().nullable(),
})

export const StringIntPairSchema = z.object({
	First: z.string(),
	Second: z.number(),
})
export type StringIntPair = z.infer<typeof StringIntPairSchema>

export const GenericPairIntBoolSchema = z.object({
	First: z.number(),
	Second: z.boolean(),
})
export type GenericPairIntBool = z.infer<typeof GenericPairIntBoolSchema>

export const PairMapStringIntBoolSchema = z.object({
	items: z.record(z.string(), GenericPairIntBoolSchema).nullable(),
})
export type PairMapStringIntBool = z.infer<typeof PairMapStringIntBoolSchema>

How we use it at Hypersequent

We have all the types declared in a single module
Use filepath.Walk to find all the go files.
We extract all the struct names using string manipulation on the files contents.
Then using go templates and passing these struct names as input, we generate go code that is later used to generate the zod schemas.

	converter := zen.NewConverterWithOpts(make(map[string]zen.CustomFn))

	{{range .TypesToGenerate}}
	converter.AddType(types.{{.}}{})
	{{end}}

	schema := converter.Export()

Supported validations

Network

Tag	Description
ip	Internet Protocol Address IP
ip4_addr	Internet Protocol Address IPv4
ip6_addr	Internet Protocol Address IPv6
ip_addr	Internet Protocol Address IP
ipv4	Internet Protocol Address IPv4
ipv6	Internet Protocol Address IPv6
url	URL String
http_url	HTTP URL String
url_encoded	URL Encoded

Strings

Tag	Description
alpha	Alpha Only
alphanum	Alphanumeric
alphanumunicode	Alphanumeric Unicode
alphaunicode	Alpha Unicode
ascii	ASCII
boolean	Boolean
contains	Contains
endswith	Ends With
lowercase	Lowercase
number	Number
numeric	Numeric
startswith	Starts With
uppercase	Uppercase

Format

Tag	Description
base64	Base64 String
mongodb	MongoDB ObjectID
datetime	Datetime
email	E-mail String
hexadecimal	Hexadecimal String
html_encoded	HTML Encoded
json	JSON
jwt	JSON Web Token (JWT)
latitude	Latitude
longitude	Longitude
uuid	Universally Unique Identifier UUID
uuid3	Universally Unique Identifier UUID v3
uuid3_rfc4122	Universally Unique Identifier UUID v3 RFC4122
uuid4	Universally Unique Identifier UUID v4
uuid4_rfc4122	Universally Unique Identifier UUID v4 RFC4122
uuid5	Universally Unique Identifier UUID v5
uuid5_rfc4122	Universally Unique Identifier UUID v5 RFC4122
uuid_rfc4122	Universally Unique Identifier UUID RFC4122
md4	MD4 hash
md5	MD5 hash
sha256	SHA256 hash
sha384	SHA384 hash
sha512	SHA512 hash

Comparisons

Tag	Description
eq	Equals
gt	Greater than
gte	Greater than or equal
lt	Less Than
lte	Less Than or Equal
ne	Not Equal

For strings & numbers, will ensure that the value is compared to the parameter given. For slices, arrays, and maps, validates the number of items.
(time, duration and maps are not supported)

Other

Tag	Description
len	Length
max	Maximum
min	Minimum
oneof	One Of
required	Required

required checks that the value is not default, but we are not implementing this check for numbers and booleans

Custom Tags

In addition to the go-validator tags supported out of the box, custom tags can also be implemented.

type SortParams struct {
	Order *string `json:"order,omitempty" validate:"omitempty,oneof=asc desc"`
	Field *string `json:"field,omitempty"`
}

type Request struct {
	SortParams       `validate:"sortFields=title address age dob"`
	PaginationParams struct {
		Start *int `json:"start,omitempty" validate:"omitempty,gt=0"`
		End   *int `json:"end,omitempty" validate:"omitempty,gt=0"`
	} `validate:"pageParams"`
	Search *string `json:"search,omitempty" validate:"identifier"`
}

customTagHandlers := map[string]zen.CustomFn{
	"identifier": func(c *zen.Converter, t reflect.Type, validate string, indent int) string {
		return ".refine((val) => !val || /^[a-z0-9_]*$/.test(val), 'Invalid search identifier')"
	},
	"pageParams": func(c *zen.Converter, t reflect.Type, validate string, indent int) string {
		return ".refine((val) => !val.start || !val.end || val.start < val.end, 'Start should be less than end')"
	},
	"sortFields": func(c *zen.Converter, t reflect.Type, validate string, indent int) string {
		sortFields := strings.Split(validate, " ")
		for i := range sortFields {
			sortFields[i] = fmt.Sprintf("'%s'", sortFields[i])
		}
		return fmt.Sprintf(".extend({field: z.enum([%s])})", strings.Join(sortFields, ", "))
	},
}
opt := zen.WithCustomTags(customTagHandlers)
c := zen.NewConverterWithOpts(opt)

c.Convert(Request{})

Outputs:

export const SortParamsSchema = z.object({
  order: z.enum(["asc", "desc"] as const).optional(),
  field: z.string().optional(),
})
export type SortParams = z.infer<typeof SortParamsSchema>

export const RequestSchema = z.object({
  PaginationParams: z.object({
    start: z.number().gt(0).optional(),
    end: z.number().gt(0).optional(),
  }).refine((val) => !val.start || !val.end || val.start < val.end, 'Start should be less than end'),
  search: z.string().refine((val) => !val || /^[a-z0-9_]*$/.test(val), 'Invalid search identifier').optional(),
  ...SortParamsSchema.extend({field: z.enum(['title', 'address', 'age', 'dob'])}).shape,
})
export type Request = z.infer<typeof RequestSchema>

The function signature for custom type handlers is:

func(c *Converter, t reflect.Type, validate string, indent int) string

We can use c to process nested types. Indent level is for passing to other converter APIs.

Ignored Tags

To ensure safety, zen will panic if it encounters unknown validation tags. If these tags are intentional, they should be explicitly ignored.

opt := zen.WithIgnoreTags("identifier")
c := zen.NewConverterWithOpts(opt)

Skipping Fields

A field can be excluded from the generated schema and type with the zen:"ignore" struct tag:

type User struct {
	Name string
	// Kept in the JSON response for API backward compatibility, but the
	// frontend no longer uses it, so omit it from the generated schema.
	LegacyToken string `json:"legacyToken" zen:"ignore"`
}

Outputs:

export const UserSchema = z.object({
	Name: z.string(),
})
export type User = z.infer<typeof UserSchema>

This differs from json:"-" (which zen also honors): json:"-" drops the field from the JSON payload entirely, whereas zen:"ignore" leaves JSON serialization untouched and only removes the field from the generated schema and type. This is handy when a field must stay in the wire format - e.g. a deprecated field kept for backward compatibility with external API clients - but should not surface in your in-house frontend's types. zen:"ignore" also applies to embedded (anonymous) fields, which json:"-" cannot skip.

Custom Types

We can pass type name mappings to custom conversion functions:

customTypeHandlers := map[string]zen.CustomFn{
	"github.com/shopspring/decimal.Decimal": func (c *zen.Converter, t reflect.Type, v string, indent int) string {
		// Shopspring's decimal type serialises to a string.
		return "z.string()"
	},
}
opt := zen.WithCustomTypes(customTypeHandlers)
c := zen.NewConverterWithOpts(opt)

c.Convert(User{
	Money decimal.Decimal
})

Outputs:

export const UserSchema = z.object({
	Money: z.string(),
})
export type User = z.infer<typeof UserSchema>

There are some custom types with tests in the custom directory.

The function signature for custom type handlers is:

func(c *Converter, t reflect.Type, validate string, indent int) string

We can use c to process nested types. Indent level is for passing to other converter APIs.

Name Clashes

Schema names are derived from the Go type name alone, so two types with the same name from different packages (e.g. api.User and db.User, or Page[api.User] and Page[db.User]) would generate the same schema. zen panics when this happens, instead of silently reusing one type's schema for the other.

To resolve it, give the types of a package a prefix. It applies wherever those types appear, including as generic type arguments:

type Account struct {
	Owner   api.User
	Record  db.User
	History Page[db.User]
}

opt := zen.WithPackagePrefixes(map[string]string{
	"github.com/acme/app/db": "Db",
})
c := zen.NewConverterWithOpts(opt)

c.Convert(Account{})

Outputs UserSchema, DbUserSchema and PageDbUserSchema.

Caveats

Does not support cyclic types - it's a limitation of zod, but self-referential types are supported.
Sometimes outputs in the wrong order - it really needs an intermediate DAG to solve this.

License

Distributed under MIT License, please see license file within the code for more details.

Credits

Inspired by supervillain
Uses several regexes from validator

README

Zen

Zod + Generate = Zen

Converts Go structs with go-validator validations to Zod schemas.

Zen supports self-referential types and generic types. Other cyclic types (apart from self referential types) are not supported as they are not supported by zod itself.

Zen emits Zod v4 schemas by default. Use zen.WithZodV3() if you need the previous output style for snapshot compatibility or incremental migration.

Usage

type Post struct {
	Title string `validate:"required"`
}
type User struct {
	Name       string     `validate:"required"`
	Nickname   *string    // pointers become optional
	Age        int        `validate:"min=18"`
	Height     float64    `validate:"min=0,max=3"`
	Tags       []string   `validate:"min=1"`
	Favourites []struct { // nested structs are kept inline
		Name string `validate:"required"`
	}
	Posts []Post // external structs are emitted as separate exports
}
fmt.Print(zen.StructToZodSchema(User{}))

// Self referential types are supported
type Tree struct {
	Value    int
	Children []Tree
}
fmt.Print(zen.StructToZodSchema(Tree{}))

// We can also use create a converter and convert multiple types together
c := zen.NewConverterWithOpts()

// Generic types are also supported
type GenericPair[T any, U any] struct {
	First  T
	Second U
}
type StringIntPair GenericPair[string, int]
c.AddType(StringIntPair{})

// For non-defined types, the type arguments are appended to the generic type
// name to get the type name
c.AddType(GenericPair[int, bool]{})

// Even nested generic types are supported
type PairMap[K comparable, T any, U any] struct {
	Items map[K]GenericPair[T, U] `json:"items"`
}
c.AddType(PairMap[string, int, bool]{})

// Now export the generated schemas. Duplicate schemas are skipped
fmt.Print(c.Export())

Legacy v3-compatible output is still available:

fmt.Print(zen.StructToZodSchema(User{}, zen.WithZodV3()))

The main migration differences are:

string format tags such as email, http_url, ipv4, uuid4, and md5 now use Zod v4 helpers like z.email(), z.url({ protocol: /^https?$/ }), z.ipv4(), z.uuid({ version: "v4" }), and z.hash("md5")
ip and ip_addr now emit z.union([z.ipv4(), z.ipv6()])
embedded anonymous structs now expand through .shape spreads instead of .merge(...)
enum-like map keys now emit z.partialRecord(...)

Outputs:

export const PostSchema = z.object({
  Title: z.string().min(1),
})
export type Post = z.infer<typeof PostSchema>

export const UserSchema = z.object({
	Name: z.string().min(1),
	Nickname: z.string().nullable(),
	Age: z.number().gte(18),
	Height: z.number().gte(0).lte(3),
	Tags: z.string().array().min(1),
	Favourites: z.object({
		Name: z.string().min(1),
	}).array().nullable(),
	Posts: PostSchema.array().nullable(),
})
export type User = z.infer<typeof UserSchema>

export type Tree = {
	Value: number,
	Children: Tree[] | null,
}
export const TreeSchema: z.ZodType<Tree> = z.object({
	Value: z.number(),
	Children: z.lazy(() => TreeSchema).array().nullable(),
})

export const StringIntPairSchema = z.object({
	First: z.string(),
	Second: z.number(),
})
export type StringIntPair = z.infer<typeof StringIntPairSchema>

export const GenericPairIntBoolSchema = z.object({
	First: z.number(),
	Second: z.boolean(),
})
export type GenericPairIntBool = z.infer<typeof GenericPairIntBoolSchema>

export const PairMapStringIntBoolSchema = z.object({
	items: z.record(z.string(), GenericPairIntBoolSchema).nullable(),
})
export type PairMapStringIntBool = z.infer<typeof PairMapStringIntBoolSchema>

How we use it at Hypersequent

We have all the types declared in a single module
Use filepath.Walk to find all the go files.
We extract all the struct names using string manipulation on the files contents.
Then using go templates and passing these struct names as input, we generate go code that is later used to generate the zod schemas.

	converter := zen.NewConverterWithOpts(make(map[string]zen.CustomFn))

	{{range .TypesToGenerate}}
	converter.AddType(types.{{.}}{})
	{{end}}

	schema := converter.Export()

Supported validations

Network

Tag	Description
ip	Internet Protocol Address IP
ip4_addr	Internet Protocol Address IPv4
ip6_addr	Internet Protocol Address IPv6
ip_addr	Internet Protocol Address IP
ipv4	Internet Protocol Address IPv4
ipv6	Internet Protocol Address IPv6
url	URL String
http_url	HTTP URL String
url_encoded	URL Encoded

Strings

Tag	Description
alpha	Alpha Only
alphanum	Alphanumeric
alphanumunicode	Alphanumeric Unicode
alphaunicode	Alpha Unicode
ascii	ASCII
boolean	Boolean
contains	Contains
endswith	Ends With
lowercase	Lowercase
number	Number
numeric	Numeric
startswith	Starts With
uppercase	Uppercase

Format

Tag	Description
base64	Base64 String
mongodb	MongoDB ObjectID
datetime	Datetime
email	E-mail String
hexadecimal	Hexadecimal String
html_encoded	HTML Encoded
json	JSON
jwt	JSON Web Token (JWT)
latitude	Latitude
longitude	Longitude
uuid	Universally Unique Identifier UUID
uuid3	Universally Unique Identifier UUID v3
uuid3_rfc4122	Universally Unique Identifier UUID v3 RFC4122
uuid4	Universally Unique Identifier UUID v4
uuid4_rfc4122	Universally Unique Identifier UUID v4 RFC4122
uuid5	Universally Unique Identifier UUID v5
uuid5_rfc4122	Universally Unique Identifier UUID v5 RFC4122
uuid_rfc4122	Universally Unique Identifier UUID RFC4122
md4	MD4 hash
md5	MD5 hash
sha256	SHA256 hash
sha384	SHA384 hash
sha512	SHA512 hash

Comparisons

Tag	Description
eq	Equals
gt	Greater than
gte	Greater than or equal
lt	Less Than
lte	Less Than or Equal
ne	Not Equal

For strings & numbers, will ensure that the value is compared to the parameter given. For slices, arrays, and maps, validates the number of items.
(time, duration and maps are not supported)

Other

Tag	Description
len	Length
max	Maximum
min	Minimum
oneof	One Of
required	Required

required checks that the value is not default, but we are not implementing this check for numbers and booleans

Custom Tags

In addition to the go-validator tags supported out of the box, custom tags can also be implemented.

type SortParams struct {
	Order *string `json:"order,omitempty" validate:"omitempty,oneof=asc desc"`
	Field *string `json:"field,omitempty"`
}

type Request struct {
	SortParams       `validate:"sortFields=title address age dob"`
	PaginationParams struct {
		Start *int `json:"start,omitempty" validate:"omitempty,gt=0"`
		End   *int `json:"end,omitempty" validate:"omitempty,gt=0"`
	} `validate:"pageParams"`
	Search *string `json:"search,omitempty" validate:"identifier"`
}

customTagHandlers := map[string]zen.CustomFn{
	"identifier": func(c *zen.Converter, t reflect.Type, validate string, indent int) string {
		return ".refine((val) => !val || /^[a-z0-9_]*$/.test(val), 'Invalid search identifier')"
	},
	"pageParams": func(c *zen.Converter, t reflect.Type, validate string, indent int) string {
		return ".refine((val) => !val.start || !val.end || val.start < val.end, 'Start should be less than end')"
	},
	"sortFields": func(c *zen.Converter, t reflect.Type, validate string, indent int) string {
		sortFields := strings.Split(validate, " ")
		for i := range sortFields {
			sortFields[i] = fmt.Sprintf("'%s'", sortFields[i])
		}
		return fmt.Sprintf(".extend({field: z.enum([%s])})", strings.Join(sortFields, ", "))
	},
}
opt := zen.WithCustomTags(customTagHandlers)
c := zen.NewConverterWithOpts(opt)

c.Convert(Request{})

Outputs:

export const SortParamsSchema = z.object({
  order: z.enum(["asc", "desc"] as const).optional(),
  field: z.string().optional(),
})
export type SortParams = z.infer<typeof SortParamsSchema>

export const RequestSchema = z.object({
  PaginationParams: z.object({
    start: z.number().gt(0).optional(),
    end: z.number().gt(0).optional(),
  }).refine((val) => !val.start || !val.end || val.start < val.end, 'Start should be less than end'),
  search: z.string().refine((val) => !val || /^[a-z0-9_]*$/.test(val), 'Invalid search identifier').optional(),
  ...SortParamsSchema.extend({field: z.enum(['title', 'address', 'age', 'dob'])}).shape,
})
export type Request = z.infer<typeof RequestSchema>

The function signature for custom type handlers is:

func(c *Converter, t reflect.Type, validate string, indent int) string

We can use c to process nested types. Indent level is for passing to other converter APIs.

Ignored Tags

To ensure safety, zen will panic if it encounters unknown validation tags. If these tags are intentional, they should be explicitly ignored.

opt := zen.WithIgnoreTags("identifier")
c := zen.NewConverterWithOpts(opt)

Skipping Fields

A field can be excluded from the generated schema and type with the zen:"ignore" struct tag:

type User struct {
	Name string
	// Kept in the JSON response for API backward compatibility, but the
	// frontend no longer uses it, so omit it from the generated schema.
	LegacyToken string `json:"legacyToken" zen:"ignore"`
}

Outputs:

export const UserSchema = z.object({
	Name: z.string(),
})
export type User = z.infer<typeof UserSchema>

Custom Types

We can pass type name mappings to custom conversion functions:

customTypeHandlers := map[string]zen.CustomFn{
	"github.com/shopspring/decimal.Decimal": func (c *zen.Converter, t reflect.Type, v string, indent int) string {
		// Shopspring's decimal type serialises to a string.
		return "z.string()"
	},
}
opt := zen.WithCustomTypes(customTypeHandlers)
c := zen.NewConverterWithOpts(opt)

c.Convert(User{
	Money decimal.Decimal
})

Outputs:

export const UserSchema = z.object({
	Money: z.string(),
})
export type User = z.infer<typeof UserSchema>

There are some custom types with tests in the custom directory.

The function signature for custom type handlers is:

func(c *Converter, t reflect.Type, validate string, indent int) string

We can use c to process nested types. Indent level is for passing to other converter APIs.

Name Clashes

To resolve it, give the types of a package a prefix. It applies wherever those types appear, including as generic type arguments:

type Account struct {
	Owner   api.User
	Record  db.User
	History Page[db.User]
}

opt := zen.WithPackagePrefixes(map[string]string{
	"github.com/acme/app/db": "Db",
})
c := zen.NewConverterWithOpts(opt)

c.Convert(Account{})

Outputs UserSchema, DbUserSchema and PageDbUserSchema.

Caveats

Does not support cyclic types - it's a limitation of zod, but self-referential types are supported.
Sometimes outputs in the wrong order - it really needs an intermediate DAG to solve this.

License

Distributed under MIT License, please see license file within the code for more details.

Credits

Inspired by supervillain
Uses several regexes from validator

gem-hunter