Back to results
rametta/zodot(opens in a new tab)
Language: GDScript
🛡️ Zod for Godot Data Validation
- stars
- 67
- watchers
- 2
- forks
- 8
- open issues
- 2
- Last updated
- 01/03/2025
gem-hunterLanguage: GDScript
🛡️ Zod for Godot Data Validation
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.
.nullable(), .union(), typed dictionaries, and more.coerce() that uses str_to_varClone addons/zodot into your projects addons folder, or download directly from the Godot Asset Store.
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
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 missingExamples
# 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
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 lengthExample
var schema = Z.string().minimum(1).maximum(20) schema.parse("hello").ok() # true schema.parse("").ok() # false
Parse integer type.
Available extension constraints:
.minimum(value: int) enforces a minimum value.maximum(value: int) enforces a maximum valueExample
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
Parse float type.
Available extension constraints:
.minimum(value: float) enforces a minimum value.maximum(value: float) enforces a maximum valueExample
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
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
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 itemExample
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
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 itemExample
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
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
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
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
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
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
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
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
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
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
Parse Plane type.
Example
Z.plane().parse(Plane.PLANE_XY).ok() # true
Parse Projection type.
Example
Z.projection().parse(Projection.ZERO).ok() # true
Parse Quaternion type.
Example
Z.quaternion().parse(Quaternion.IDENTITY).ok() # true
Parse AABB type.
Example
Z.aabb().parse(AABB()).ok() # true
Parse RID type.
Example
Z.rid().parse(RID()).ok() # true
Parse Basis type.
Example
Z.basis().parse(Basis.FLIP_X).ok() # true
There are many more validators, please check here for a full list of all the validators available.