🛡️ Zodot

Data Validator for Godot - inspired by Zod

Zodot is a lightweight data validation library for Godot. Define a schema shape, then use that schema to validate any data. Excellent for parsing data that was stored in JSON, or data returned from API's.

Features:

Validators for all the Godot Variant Types
More expressive than what GDScript provides, allows things like .nullable(), .union(), typed dictionaries, and more
Automatic data coercing with .coerce() that uses str_to_var
Extendible with custom validators for your own types
Clear error messages
Lightweight & Zero Dependencies

Installation

Clone addons/zodot into your projects addons folder, or download directly from the Godot Asset Store.

Usage

Here is an example of a defined schema for a User with 3 fields and their corresponding types. We can also see there are extra constraints on the name and age, such as name can not be empty, and age must be greater than 12.

# Our User Schema
var UserSchema = Z.schema({
  "name": Z.string().non_empty().maximum(5),
  "age": Z.integer().minimum(12),
  "is_tall": Z.boolean()
})

# Our data we want to validate
var user = {
  "name": "Jason",
  "age": 100,
  "is_tall": true
}

func _ready():
  # Validate the data against the schema and get the result
  var result = UserSchema.parse(user)
  print(result.ok()) # true

Using the same schema, here is an example where the validation fails:

var user = {
  "name": "Jason",
  "age": 10,
  "is_tall": true
}

var result = UserSchema.parse(user)
print(result.ok()) # false
print(result.error) # "Field 'age' has value lower than desired minimum of 12"

Example where data was stored by calling var_to_str on every field and stored as JSON.

var schema = Z.schema({
  "my_float": Z.float().coerce(),
  "my_color": Z.color().coerce(),
  "my_vect3": Z.vector3().coerce()
})

var data = {
  "my_float": var_to_str(1.23),
  "my_color": var_to_str(Color(5.5,6.6,7.7, .5)),
  "my_vect3": var_to_str(Vector3(1.9,2.3,3.5)),
}

# Simulate retreiving this data from external source
# by stringifying than parsing
var json_string = JSON.stringify(data)
var json = JSON.new()
json.parse(json_string)

var result = schema.parse(json.data)

assert_eq(result.data.my_color, Color(5.5,6.6,7.7, .5)) # true
assert_eq(result.data.my_float, 1.23) # true
assert_eq(result.data.my_vect3, Vector3(1.9,2.3,3.5)) # true

Types

Here is a list of all the available types to use for validation, and their associated constraints. All types also have these base constraints available:

.coerce() calls str_to_var() before validation, useful if previously called var_to_str()
.nullable() allows the field to be null or missing

Examples

# Coerce example
var schema = Z.integer().minimum(2).maximum(20).coerce()
schema.parse("5").ok() # true
var result = schema.parse(var_to_str(26)).ok() # false
result.data == 26 # true, result data contains the coerced value

# Nullable example
var schema = Z.integer().minimum(2).maximum(20).nullable()
schema.parse(5).ok() # true
schema.parse(null).ok() # true
schema.parse(26).ok() # false

Z.string()

Parse string type.

Available extension constraints:

.non_empty() enforces strings to not be empty
.minimum(value: int) enforces a minimum length
.maximum(value: int) enforces a maximum length

Example

var schema = Z.string().minimum(1).maximum(20)
schema.parse("hello").ok() # true
schema.parse("").ok() # false

Z.integer()

Parse integer type.

Available extension constraints:

.minimum(value: int) enforces a minimum value
.maximum(value: int) enforces a maximum value

Example

var schema = Z.integer().minimum(1).maximum(20)
schema.parse(5).ok() # true
schema.parse(100).ok() # false
schema.parse(5.5).ok() # false - float is not an integer

Z.float()

Parse float type.

Available extension constraints:

.minimum(value: float) enforces a minimum value
.maximum(value: float) enforces a maximum value

Example

var schema = Z.float().minimum(1.0).maximum(20.5)
schema.parse(5.5).ok() # true
schema.parse(100.45).ok() # false
schema.parse(5).ok() # false - int is not a float

Z.boolean()

Parse boolean type.

Accepts enum to constrain to either only true or only false. Default is both.

Example

Z.boolean().parse(true).ok() # true
Z.boolean().parse(false).ok() # true

Z.boolean(z_boolean.Kind.ONLY_TRUE).parse(true).ok() # true
Z.boolean(z_boolean.Kind.ONLY_TRUE).parse(false).ok() # false

Z.boolean(z_boolean.Kind.ONLY_FALSE).parse(true).ok() # false
Z.boolean(z_boolean.Kind.ONLY_FALSE).parse(false).ok() # true

Z.array()

Parse array type.

Accepts an optional extra schema to constrain array items to a certain type.

Available extension constraints:

.non_empty() enforces the array to have at least 1 item

Example

Z.array().parse([1,2,3]).ok() # true
Z.array().non_empty().parse([]).ok() # false, empty
Z.array(Z.integer()).parse([1,2,3]).ok() # true
Z.array(Z.integer()).parse(["1",2,3]).ok() # false, item[0] is a string

Z.dictionary()

Parse dictionary type.

Accepts an optional extra schema to constrain dictionary items to a certain type. (For a specific dictionary shape, use Z.schema() instead)

Available extension constraints:

.non_empty() enforces the dictionary to have at least 1 item

Example

Z.dictionary().parse({"key": 1}).ok() # true
Z.dictionary().non_empty().parse({}).ok() # false, empty
Z.dictionary(Z.integer()).parse({"key": 1}).ok() # true
Z.dictionary(Z.integer()).parse({"key": "a"}).ok() # false, key is a string

Z.schema()

A special type for defining specific object shapes that are more rigid than a standard dictionary. Takes a dictionary as argument, where each key defines a type.

Example

var schema = Z.schema({
  "first_name": Z.string().non_empty(),
  "fave_color": Z.color().nullable()
})

var data = {
  "first_name": "Jason",
  "fave_color": Color.ALICE_BLUE
}

schema.parse(data).ok() # true

Z.union()

A special type for allowing a field to be more than 1 type. Takes an array of schemas to validate against.

Example:

# Allow a field to be a color OR a vector3
var schema = Z.union([Z.color(), Z.vector3()])

schema.parse(Vector3(1,2,3)).ok() # true
schema.parse(Color(1,2,3)).ok() # true
schema.parse(67).ok() # false

Z.zenum() (Z.enum())

A special type for parsing Godot enum's.

Note: Since enum is a reserved word, this validator can not be called Z.enum() so it is called Z.zenum() instead.

Example:

enum Speed = {
  Fast,
  Slow,
  Medium
}

var schema = Z.zenum(Speed)

schema.parse(Speed.Fast).ok() # true
schema.parse(Speed.Slow).ok() # true
schema.parse(Speed.Medium).ok() # true
schema.parse(0).ok() # true
schema.parse(1).ok() # true
schema.parse(2).ok() # true
schema.parse(67).ok() # false

Z.color()

Parse Color type.

Example

Z.color().parse(Color.ALICE_BLUE).ok() # true
Z.color().parse(Color(1,2,3,0.5)).ok() # true
Z.color().parse("blue").ok() # false

Z.vector2() & Z.vector2i()

Parse Vector2 and Vector2i types respectively.

Example

# Vector2
Z.vector2().parse(Vector2.ZERO).ok() # true
Z.vector2().parse(Vector2(1.1, 2)).ok() # true
Z.vector2().parse(Vector3.ZERO).ok() # false

# Vector2I
Z.vector2i().parse(Vector2i.ZERO).ok() # true
Z.vector2i().parse(Vector2i(1, 2)).ok() # true
Z.vector2i().parse(Vector2.ZERO).ok() # false

Z.vector3() & Z.vector3i()

Parse Vector3 and Vector3i types respectively.

Example

# Vector3
Z.vector3().parse(Vector3.ZERO).ok() # true
Z.vector3().parse(Vector3(1.1, 2, 6)).ok() # true
Z.vector3().parse(Vector4.ZERO).ok() # false

# Vector3I
Z.vector3i().parse(Vector3i.ZERO).ok() # true
Z.vector3i().parse(Vector3i(1, 2, 7)).ok() # true
Z.vector3i().parse(Vector3.ZERO).ok() # false

Z.vector4() & Z.vector4i()

Parse Vector4 and Vector4i types respectively.

Example

# Vector4
Z.vector4().parse(Vector4.ZERO).ok() # true
Z.vector4().parse(Vector4(1.1, 2, 6, 1)).ok() # true
Z.vector4().parse(Vector3.ZERO).ok() # false

# Vector4I
Z.vector4i().parse(Vector4i.ZERO).ok() # true
Z.vector4i().parse(Vector4i(1, 2, 7, 8)).ok() # true
Z.vector4i().parse(Vector4.ZERO).ok() # false

Z.transform2d() & Z.transform3d()

Parse Transform2D and Transform3D types respectively.

Example

# Transform2D
Z.transform2d().parse(Transform2D.FLIP_X).ok() # true
Z.transform2d().parse(Vector3.ZERO).ok() # false

# Transform3D
Z.transform3d().parse(Transform3D.FLIP_Z).ok() # true
Z.transform3d().parse(Vector4.ZERO).ok() # false

Z.rect2() & Z.rect2i()

Parse Rect2 and Rect2i types respectively.

Example

# Rect2
Z.rect2().parse(Rect2(1,2,3,4.5)).ok() # true
Z.rect2().parse(Vector3.ZERO).ok() # false

# Rect2i
Z.rect2i().parse(Rect2(1,2,3,4)).ok() # true
Z.rect2i().parse(Vector4.ZERO).ok() # false

Z.plane()

Parse Plane type.

Example

Z.plane().parse(Plane.PLANE_XY).ok() # true

Z.projection()

Parse Projection type.

Example

Z.projection().parse(Projection.ZERO).ok() # true

Z.quaternion()

Parse Quaternion type.

Example

Z.quaternion().parse(Quaternion.IDENTITY).ok() # true

Z.aabb()

Parse AABB type.

Example

Z.aabb().parse(AABB()).ok() # true

Z.rid()

Parse RID type.

Example

Z.rid().parse(RID()).ok() # true

Z.basis()

Parse Basis type.

Example

Z.basis().parse(Basis.FLIP_X).ok() # true

More

There are many more validators, please check here for a full list of all the validators available.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

🛡️ Zodot

Features:

Installation

Usage

Types

Z.string()

Z.integer()

Z.float()

Z.boolean()

Z.array()

Z.dictionary()

Z.schema()

Z.union()

Z.zenum() (Z.enum())

Z.color()

Z.vector2() & Z.vector2i()

Z.vector3() & Z.vector3i()

Z.vector4() & Z.vector4i()

Z.transform2d() & Z.transform3d()

Z.rect2() & Z.rect2i()

Z.plane()

Z.projection()

Z.quaternion()

Z.aabb()

Z.rid()

Z.basis()

More

Files

README.md

Latest commit

History

README.md

File metadata and controls

🛡️ Zodot

Features:

Installation

Usage

Types

Z.string()

Z.integer()

Z.float()

Z.boolean()

Z.array()

Z.dictionary()

Z.schema()

Z.union()

Z.zenum() (Z.enum())

Z.color()

Z.vector2() & Z.vector2i()

Z.vector3() & Z.vector3i()

Z.vector4() & Z.vector4i()

Z.transform2d() & Z.transform3d()

Z.rect2() & Z.rect2i()

Z.plane()

Z.projection()

Z.quaternion()

Z.aabb()

Z.rid()

Z.basis()

More