hapi — Query Parameter Validation With Joi

As an application developer, you should never trust the data provided by users. At any possible input! That doesn’t only apply for request payload send within the request body, but also for query parameters.

This guide shows you how to apply query parameter validation for a given route in your hapi server using the joi plugin.

hapi Series Overview

Prepare Your Project and Install Joi

You’ll use the joi module from within hapi’s plugin ecosystem to validate provided query parameters on a given route. Before defining the validation itself, you need to add joi as a dependency to your project:

npm i -S joi  

Installation process finished successfully? Your project is ready to make use of joi for input validation.

Use Joi for Query Parameter Validation

Query parameters aren’t defined within your route setup and users can provide any kind of value if they know what parameter keys you’re evaluating and processing within your app. Within the following code snippet, you can see how the actual query parameter validation is applied to a specific route.

In case you’ve the query parameter validation configured, hapi applies the defined constraints. Depending on whether the given parameter data passes the validation process successfully, the request will be proceeded by calling the route handler. If validation already fails, hapi will reply with a detailed boom error object including the reason why validation didn’t finish correctly.

var Joi = require('joi')

  method: 'GET',
  path: '/tutorials',
  config: {
    handler: …,
    validate: {
      query: {
        filter: Joi.array().items(Joi.string().valid('premium', 'video')).single()

As you can see within the code snippet above, to enable validation on your route, you need to define a config.validate object. The query parameter validation is used with the help of the query property.

The snippet shows an exemplary query parameter validation for the filter key, like https://futurestud.io/tutorials?filter=video. The actual validation rule looks kind of complex, but it just says that users are only allowed to use the premium or video or both values with the filter parameter. If users provide other values than allowed, the validation will fail and users will see an error message.

You can find all applicable methods and constraints within joi’s API reference.

Notice: if you apply validation for one of your query parameters, you need to define rules for every other as well. Joi will validate every query parameter if you’re activating one or many for a given route. If you’re going to use the route from above, you can’t use another query parameter (like ?page=20), because joi only expects filter.

Validate Multiple Query Parameters on a Route

In the paragraph above, you’ve read that if you apply validation to a single query parameter, you need to validate all of them. And that’s kind of straight forward by adding your query parameter keys to the validate.query object in your hapi route.

Let’s extend the previous example with another query parameter, called page. Assumingly you’re going to use the page parameter for pagination through your list of tutorials. That means you’re expecting a number greater than zero.

validate: {  
  query: {
    filter: Joi.array().items(Joi.string().valid('premium', 'video')).single(),
    page: Joi.number().min(1)

If you want to validate further query parameters, just add them to the query object within validate.


We hope you see the need and benefits of query parameter validation in your hapi project. Don’t trust user data and make sure to validate the input if there’s a chance to provide malicious information.

And please keep in mind, that once you apply validation for a single query parameter, you need to add the rules for all possible keys as well. Otherwise, the validation for those keys will fail.

To complete the validation on request data, follow along to learn the basics on path parameter validation in hapi.

Do you have any question or just want to leave a message? Use the comments below or find us on Twitter @futurestud_io

Make it rock & enjoy coding!

Additional Resources

Explore the Library

Find interesting tutorials and solutions for your problems.