Luau Schema Validator (LSV)

Resources Community Resources
#1

LUAu Schema Validator (LSV)

Get the model Here —> | RobloxModel |

Overview

LSV is a module created to validate tables against defined schemas. I thought this could be a useful tool, so I developed it to help with ensuring that data conforms to certain rules. It might still need some fine-tuning, but it’s a starting point for data validation in Lua.
I took inspiration from JSON Schemas, obviously taking only very limited part of it (just essentials rules).

Key Features

  • Type Validation: Supports basic types such as string, integer, number, table, and boolean.
  • Constraints: Includes rules for validation like:
    • Maximum and minimum values (maximum, minimum).
    • String length constraints (maxLenght, minLenght).
    • Table item constraints (maxItems, minItems, uniqueItems).
    • Primitive variables ENUM (enum = {"foo"}).
    • Required Items in tables (requiredItems = {"foo, bob"}).
    • additionalItems in tables (additionalItems = false/true).
  • Recursive Validation: Can validate nested tables.
  • Detailed Error/Warning Messages: Provides clear error messages to help with debugging.

Why should you use LSV?

  1. Avoiding Data Structure Errors
    When working with tables, especially in larger projects, ensuring that data is in the correct format can be challenging. LSV allows you to define rules that enforce:

    • Required fields
    • Correct data types
    • Allowed value ranges
    • Unique elements in lists

  2. Automating Data Validation
    If you’re working with JSON-style config files, user inputs, or database-like structures, you don’t need to manually check every table. LSV does it for you, saving development time, also the module supports nested tables, allowing you to validate these complex data structures with multiple layers of validation.

  3. Making Debugging Easier
    LSV provides detailed error messages when validation fails, helping you quickly identify what went wrong. Instead of manually checking for missing or incorrect values, you get a clear error message like:

    [LSV]: Invalid table, the value of Main.temperature is lesser than the maximum
[LSV]: Invalid table, the type of Main.temperature should be 'integer', got 'string'

Methods

  • LSV.new(schema)

    • Description: Creates a new LSV object with the provided schema (Constructor).
    • Parameters:
      • schema (table): The schema that defines the validation rules.
    • Returns: A new LSV object or nil if there’s an error.

  • LSV:ValidateTable(t)

    • Description: Validates a table against the schema.
    • Parameters:
      • t (table): The table to validate.
    • Returns:
      • true: If the table is valid.
      • false, errorMessage: If the table is not valid, along with an error message.

Constraints

  • General Constraints

    Constraint Type Description
    type string Expected data type (string, integer, number, boolean, table).
    enum table Defines allowed values (e.g., { "foo", "bar" }).

  • Number Constraints (For integer and number types)

    Constraint Type Description
    minimum number The minimum allowed value.
    maximum number The maximum allowed value.

  • String Constraints (For string type only)

    Constraint Type Description
    minLength number Minimum length of the string.
    maxLength number Maximum length of the string.

  • Table Constraints (For table type only)

    Constraint Type Description
    requiredItems table Defines required keys (e.g., { "name", "age" }).
    additionalItems boolean Controls whether extra keys not defined in the schema are allowed.
    Defaults to true.
    maxItems number Maximum number of elements allowed in the table.
    minItems number Minimum number of elements required in the table.
    uniqueItems boolean Ensures all elements in the table are unique. Defaults to false.

How to use?

  1. Require

    • First you have to require the module (replace ‘script’ with the actual path) :
      local LSV = require(script.LSV)

  2. Initialization

    • Call the constructor method of the LSV class and provide a valid Schema as a parameter, if the schema is not valid (maybe syntax errors) it will return nil and make a warn, otherwise it will just return the LSV object:
      local schema = {
	items = {
		name = { type = "string", minLenght = 3, maxLenght = 20 },
		age = { type = "integer", minimum = 0, maximum = 100 },
		hobbies = {
    		type = "table",
    		minItems = 1,
    		maxItems = 10,
    		items = { type = "string" },
    		uniqueItems = true
		},
	},
additionalItems = false
}
local validator = LSV.new(schema) -- Calling the constructor

  3. Validation

    • Now that you have the LSV object you can just use the :ValidateTable(…) Method to check if the table given follows the schema :
      local data = {
	name = "SimoDevv",
	age = 19,
	hobbies = { "coding", "gaming" }
}

local isValid, errorMessage = validator:ValidateTable(data)

if isValid then
	print("Data is valid!")
else
	warn(errorMessage)
end

‎ ‎
‎
‎ --------------------------------------------------------------------------------------------------------------------------------------
‎

Looking for Feedback!

  • This is an experimental module, and I’d love to hear your thoughts!
    • Do you think this could be useful?
    • Any features you’d like to see added?
    • Spotted any bugs or issues?
2 Likes