Summary

This major version introduces a lot of breaking changes, trying to fix some long lasting quirks. Most of the breaking changes should be edge cases but I encourage you to read those notes carefully as you may be exposed.

• Upgrade time: medium to high
• Complexity: low
• Risk: high

👥 Contributors

The code contributors to this release are : @BolajiOlajide and myself.

Special thanks to @nearform who sponsored most of my time on this release!

⚠️ Breaking changes

stripUnknown: true defaults to not strip array items (#1614)

This flag now gets what everyone seems to expect, that is strip object keys, but not invalid array items. I guess you can all go back to stripUnknown: true.

Stricter and safer parsing of numbers (#1113, #1504, #1544)

From now on, numbers are checked to be within range of what JavaScript considers safe (see Number.isSafeInteger). You can disable this behavior by doing Joi.number().unsafe() but I would personally advice against that.

Also, numbers, when converted from strings, will check for conversion fidelity, meaning there will be errors if you lost some precision on the way.

And finally, numbers written in another base (0xA, 0o7, ...) were improperly converted, they will be denied from now on. An option to support that in the future could be added but there hasn't been much demand.

Fixed output result of Joi.string().valid(...).insensitive() (#1191)

valid is used to provide a white-list of values, and insensitive could influence how strings are matched inside that list, but the previous behavior was only to check whether it matched, and then return the input. This is wrong because what you most likely expect is to get a string that is inside that white-list, not some upper-cased version of it. This is now fixed and you'll get exactly what you white-listed.

Nested paths on object.or/nand/and/xor/with/without() (#1477, #1554)

Nested paths on those functions are now supported. I consider this a breaking change as you may (but you really really shouldn't) have used dotted paths in those validations because you wanted to check dotted properties. If that's your case there is currently no migration path but we can discuss that in an issue.

Examples are now validated again and can be replaced (#1478, #1555)

Examples used to be validated, then they were not, and now they are again, but with a specific format for schemas with references. Read the docs to know more.

Also, any new call to example() will replace previous examples, it's not additive anymore.

Lazy schemas are now less lazy by default (#1258)

Joi.lazy is now caching the result of its function call, this could lower the overhead if you were generating schemas in those. If you want to disable it for whatever reason, use Joi.lazy(fn, { once: false }).

array.min/max/length will be overridden by last call (#1127)

Joi.array().min(3).min(2) is now strictly equivalent to Joi.array().min(2), it used to be Joi.array().min(3), so now the last one wins for all those rules.

object.pattern and string.regex now preserve most of the flags (#1429)

Previously, all flags but i were ignored for regular expressions, now you can pass any flag but g (global) or y (sticky).

Single year is now parsed correctly for ISO dates (#1247)

When expecting a Joi.date().iso(), single numbers (as numbers or strings) such as '2013' were considered as epoch while the ISO format allows for that, now it's correctly considered as 2013-01-01T00:00:00.000Z.

Correctly apply labels to alternatives schemas (#1364)

Error messages could look weird when you chain a label with an alternative, say Joi.when('foo', { ... }).label('myLabel'). Now it is correctly dealt with.

Error message override is also applied to individual errors (#1568)

A value can fail for many reasons, especially if you use abortEarly: false. Error overrides used to take over for the main error message but leave alone the individual errors that were exposed in the details array. Now it is assumed that you want to override all pertaining to the same value.

✨ New features

New features were introduced as part of breaking changes, but none otherwise.