6.0.0 Release Notes

[Marsup]

Summary

Joi 6.0.0 changes error messages to be more accurate and adds a few exciting features on array, number and string.

• Upgrade time: low to high depending on how you used error messages
• Complexity: medium, most of the changes should be straightforward, unless once again you relied on error messages
• Risk: medium, the change of behavior on concat and array options may break some things

Breaking changes

Messages

The most noticeable change of this release is all the messages have been modified to be friendlier to developers, including more details, characters to help readability of the message and so on.

If you relied on Joi to generate user-facing text or if you parsed those strings to make sense out of it, you would better rely on the details property of the error Joi provides as the text of the errors are designed for developers. Even though undocumented, this array existed in previous versions of Joi, it contained the hierarchy of errors with their details. This is now a flat array containing only the errors that happened in leafs so you don't have to traverse anything to get a list of the failures. Each error contains :

• message: this is the text of the error
• path: the dotted path of the value that failed
• type: an error code in the form of a string
• context: an object that gives some context about the error, this one depends on the type of error you have

All of this is still very undocumented and will have to be in the coming weeks/months, any help is welcome.

any().options(options)

Options are now checked for validity, it shouldn't be a breaking change but some of you might see errors if you provided wrong options before (eg. in case of a typo).

The language strings also now accept a prefix !! so that if you want to redefine the error strings without the key of the value as prefix, you can.

any().concat()

Concatenation of multiple schemas is now more clever if objects contain the same key. It could before produce invalid schemas like requiring a key to be both a string and a number. This kind of error will be raised at concat time instead of letting you generate a schema that can only fail. Sadly this inconsistency seems to have been used unknowingly by some, sometimes with success, I'll try to fix those who broke case by case.

array().includes() and array().excludes()

Those functions are now removed in favor of items. See below for more details.

abortEarly and stripUnknown on arrays

These options were completely ignored when it came to arrays before, you may now have more than one error on arrays if you use abortEarly: false, and you may remove elements that do not match the types you declared in items() by setting stripUnknown: true.

New features

any()

default(fn, [description])

Default can now finally accept a factory as value. That factory function will either have to have a description property, or the second argument will be required. This is mandatory because, even though this is not a well known feature of Joi, we have to be able to export information about what your validations are doing, and a function is meaningless without a proper description of what it is doing.

In addition to being able to generate values, if your function declares any parameter at all, Joi will provide as first argument the parent object of your value so that you can build your default based on other keys (eg. full name based on first name and last name). WARNING: Since we don't want people to tamper with original objects, that parameter is a clone, and indeed cloning has a slight cost, so use it wisely. The order, as before, is not guaranteed, so if your default relies on another property setting its default, you might have unexpected behaviors.

only()

This is a new alias to valid() to express the intent more clearly.

disallow()

This is as well a new alias to invalid().

strip()

This will strip the key or array element from the final result Joi will return. Be careful that this does not make Joi skip validation.

array()

items(items)

This will supersede includes() and excludes() from now on.

Schemas of arrays are defined as they were before, but the presence flag will now be checked :

• required: that schema is expected to be found at least once in the values
• forbidden: that schema cannot exist in the values
• optional or nothing : that schema may be found in the values

Example :

var apple = Joi.string().only('apple').forbidden();
var banana = Joi.string().only('banana').required();
var orange = Joi.string().only('orange');
var boolean = Joi.boolean();

var schema = Joi.array().items(banana, banana, boolean, orange, apple);

For an array to match this schema, it:

• will have to contain at least 2 strings "banana"
• may contain booleans
• may contain strings "orange"
• cannot contain strings "apple"

A matching array could be :

[true, 'orange', 'banana', true, 'banana', 'orange', false]

number()

multiple(number)

Checks whether numbers are multiple of another number.

string()

hex()

Checks if the string contains only hexadecimal characters.

email(options)

This rule now accepts options that will be provided to isemail. Most options are supported, with the exception of checkDNS because of its asynchronicity which Joi currently cannot handle.

uri(schemes)

Checks if a string is an URI, optionally specifying the expected schemes (eg. ftp, http, git, ...).

Contributors

The contributors to this release are @nlf, @nlindley, @johnbrett, @martinheidegger, @DavidTPate and myself.