10.0.0 Release Notes

[Marsup]

Summary

This release breaks Joi.boolean() behavior and extracts Joi.date().format() in an external module.

• Upgrade time: moderate
• Complexity: low
• Risk: moderate

Breaking changes

Joi.boolean()

In the previous versions, with convert set to true, Joi supported the use of equivalent values for true or false, namely "true", "false", "yes", "no", "on", "off", 1, 0, "1" and "0". This is not the case anymore, it will only support true, false, "true" and "false" by default, with the possibility to disable string conversion by using strict(). There are now escape hatches for the other cases if you still want this, so the previous schema can now be expressed as :

Joi.boolean().truthy('yes', 1, '1').falsy('no', 0, '0')

You can put any value in those if you want, though it will not try to do a deep comparison.

Removal of Joi.date().format()

Removing this was important to streamline the core of joi, it didn't make much sense to impose moment on you when you might not even be using it. It might as well simplify the bundling process if you were using joi through webpack/browserify/rollup/....

You can still get the feature by using joi-date-extensions, read the docs there about how to use it. The behavior should be very close to previous joi versions, though I can't absolutely it is strictly the same, as I tried to not only split code but do an extension that "felt right". If it's not perfect, don't worry, having it in a separate module will allow it to evolve way more quickly than joi core can.

New features

Joi.version

Exposes the version of the joi module being used, could be useful for some operations or debugging.

Joi.string().uri({ relativeOnly: true })

Now the URI check accepts a new option to validate only relative URIs.

Joi.string().base64()

As the name says, it checks whether a string is a valid base64 string.

Joi.string().regex(pattern, name | options)

The regex rule can now take an options object that can contain :

• name : as before, the friendly name of the regular expression.
• invert : a new boolean flag that indicates whether we want to match the regular expression, or its opposite. It obviously defaults to false.

Contributors

The contributors to this release are @WesTyler, @lamchakchan, @chris--young, @ptrckc and myself.

[maxbeatty]

Thank you for continuing to publish these release notes issues. It makes upgrading so much easier 🤗

[wraithgar]

Thank you for publishing joi-date-extensions already, it made today WAY easier than it would have been otherwise. You're awesome.

[indreek]

Hi

There is mistake in manual. Date format does not exist anymore.
https://github.com/hapijs/joi/blob/v10.0.5/API.md

const schema = {
timestamp: Joi.date().format('YYYYMMDD').raw()
};

[AdriVanHoudt]

@indreek It is mentioned here and it is not in the api.md file you linked.

[indreek]

@AdriVanHoudt

It's under any.raw explanation

Indrek

[AdriVanHoudt]

@indreek that is indeed wrong, can you open a separate issue for this?

[gordysc]

For personal understanding, what was the motivation behind the changes to Joi.boolean()? This broke several routes for me (and thank you for calling it out in this documentation) when trying to validate query parameters on HapiJS. Having to specify:

query: {
  flag: Joi.boolean().truthy('true').falsy('false')
}

vs

query: {
  flag: Joi.bool()
}

seems a bit verbose. Were people unsatisfied by the assumptions for other truthy & falsy values?

[galenandrew]

@gordysc it appears Issue #991 and Pull Request #998 are the two recent discussions around the API change.

[Marsup]

Also relevant #1049 (comment).

[gordysc]

Fair enough. I might be off base, but I imagine this being a HapiJS library, a majority of the people using it would leverage it for validation in HapiJS. Given the parsing in HapiJS is going to provide string values on query parameters for 'true' and 'false', those values to me seem like a good compromise, but I can work around it.

[galenandrew]

#1049 is a scenario where the parameter value will never be a strict boolean due to query string parsing.

Because of this change in behavior, developers now need to explicitly define truthy/falsy values for every parameter instance in order to properly validate a boolean.

If I understand your reasoning for the behavior change you did so because "people wanted to provide their own values" to boolean(). Doesn't .valid() and .invalid() accomplish this?

With this change, boolean validation went from this…

// loose validation
Joi.boolean()

// strict validation
Joi.boolean().strict()

// custom values
Joi.boolean().valid('mytruthy').invalid('true')

…to this…

// loose validation and custom values (to pass validation)
Joi.boolean().truthy('true', 'yes', 1, '1').falsy('false', 'no', 0, '0')

// strict validation
Joi.boolean()

To be honest, the new API is much messier and cumbersome for developers.

[galenandrew]

Also, is there any difference between Joi.boolean() and Joi.boolean().strict() now?

[Marsup]

Doesn't .valid() and .invalid() accomplish this?

Nope, they change the outcome of the validation, and are the exact opposites of one another, it's a completely different thing.

Also, is there any difference between Joi.boolean() and Joi.boolean().strict() now?

This is a fair point, convert should have been used, at least for the "true" and "false" cases. I'm tempted to consider this a bug and restore only those 2 cases when convert is true, does anyone disagree with that ?

[galenandrew]

@Marsup You're absolutely correct. I should clarify my statement about valid/invalid – I wasn't equating them to the new truthy/falsy functions, but instead was pointing out that someone could use valid to whitelist custom values and invalid to blacklist custom values. As you pointed out though, there would still be a conversion issue with valid/invalid values to a strict boolean true/false. This is definitely a good reason for the new truthy/falsy functions!

As for the loose vs strict boolean checking when convert is true, I'm in total agreement.

[Marsup]

Fixed as of #1065 and published. Update the text above. Forgot about the API.md so it will be published on the next version.