The tulip.pkg.validator module exports the validator package.

#Configuration

None.

#API Extensions

Registering this package provides the following method and field extensions.

#ok, err|vt = App:validate(t, schema)

Validates the table t based on the schema definition.

Args:

• t: table = the table to validate
• schema: table = the schema definition, see below for details.

Returns:

• ok: boolean = true on success
• err: Error|nil = if ok is falsy, the EINVAL error, with the field and value set to the field that failed validation.
• vt: table = if ok is true, vt contains the flattened validated values under the same keys as the keys or paths in schema. E.g. if schema as "name" and "user.birth.country" as keys, then vt would have their validated values under vt["name"] and vt["user.birth.country"] (flattened under that exact key). Validated values can be slightly different from the raw ones (e.g. converted to another type, normalized).

The schema is a dictionary where the key is a key name or path in t (e.g. "email" or "user.age"), and the value is a table that defines the validations to apply to that field. Possible fields on that validations table are:

• type: string = the type of that value, fails if it is not of that type if present ('integer', 'string', 'boolean')
• min, max: number = the minimum and maximum value for integers, or the minimum and maximum length in bytes for strings.
• mincp, maxcp: number = the minimum and maximum number of codepoints for utf-8 strings. Fails if the string is not valid utf8.
• trim_ws: boolean = for strings, if true, trims leading and trailing whitespace. This happens after the validation for min/max bytes, but before validation of min/max codepoints, so that a trim is not attempted on an exaggerately long string (via the bytes validation), but one can still require a minimum number of code points to be present after trim.
• normalize_ws: boolean = for strings, if true, all spaces are normalized prior to validation for control characters, so that tabs and newlines are turned into standard spaces.
• allow_cc: boolean = for strings, if true, allows control characters. By default, control characters raise an error.
• required: boolean = fails if the value is not present (nil).
• pattern: string = if set, strings must match this pattern.
• enum: array = if set, value must match one of those values (can be of any type, must match the type of the field to possibly succeed).

Booleans are a bit different, none of the previous schema validations apply to them. By default, they follow Lua's definition of true/false, so unless the value is nil or false, it is true. But the following schema fields can alter the result of the validation:

• true_value: any = if set, only this value is considered true, everything else is false unless false_value is set.
• false_value: any = if set, only this value is considered false, everything else is true unless true_value is set. If both are set, then any value that isn't one of those two is considered invalid (basically, this is like an enum for booleans, with the added semantics that one means true, the other false).

#ok, err|vt = Request:validate_body(schema[, force_ct])

Validates the decoded body of the Request based on schema. The behaviour is the same as App:validate. This is registered by the middleware, which must be enabled for that extension to be installed. If force_ct is provided, it is passed to the call to Request:decode_body.

#Registered Middleware

The following middleware are registered and can be referenced by name in the configuration.

#tulip.pkg.validator

Must be added before any handler that needs to call Request:validate_body, as it registers that extension. Not registered if the middleware package is not registered (does not raise an error, as some apps may use App:validator without the need for the middleware).

Back to index