> For the complete documentation index, see [llms.txt](https://marblejs.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://marblejs.gitbook.io/docs/other/api-reference/middleware-joi.md).

# @marblejs-contrib/middleware-joi

<div align="center"><img src="/files/-LLYJsPvN01UHocjSg46" alt=""></div>

[Joi](https://github.com/hapijs/joi) is an object schema description language and validator for JavaScript objects. Using its schema language, you can validate things like:

* HTTP request headers
* HTTP body parameters
* HTTP request query parameters
* URL parameters

You can find detailed API reference for Joi schemas [here](https://github.com/hapijs/joi/blob/v13.6.0/API.md).

{% hint style="warning" %}
**Deprecation warning**

Since version 4.0 `@marblejs-contrib/middleware-joi` package is deprecated and won't be maintained anymore.
{% endhint %}

{% hint style="warning" %}
Since version 4.0, the middleware is a part of contrib packages. If you really want to use this middleware you can reach it via `@marblejs-contrib/middleware-joi`.
{% endhint %}

{% hint style="warning" %}
For more advanced request or event validation purposes we highly recommend to use [@marblejs/middleware-io](/docs/other/api-reference/middleware-io.md) package instead. It can better handle type inference for complex schemas.
{% endhint %}

### Installation

```bash
yarn add @marblejs-contrib/middleware-joi
```

Requires `@marblejs/core` to be installed.

### Importing

```typescript
import { validator$ } from '@marblejs-contrib/middleware-joi';
```

### Type declaration

```
validator$ :: (Schema, Joi.ValidationOptions) -> HttpMiddlewareEffect
```

### **Parameters**

| *parameter* | definition                                                                                                            |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| *schema*    | `Schema`                                                                                                              |
| *options*   | \<optional> `Joi.ValidationOptions` (see: [Joi API reference](https://github.com/hapijs/joi/blob/v13.6.0/API.md#joi)) |

#### ***Schema***

| *parameter* | definition        |
| ----------- | ----------------- |
| *headers*   | \<optional> `any` |
| *params*    | \<optional> `any` |
| *query*     | \<optional> `any` |
| *body*      | \<optional> `any` |

### Usage

**1.** Example of using middleware on a *GET* route to validate query parameters:

{% code title="foo.effect.ts" %}

```typescript
import { r } from '@marblejs/http';
import { validator$, Joi } from '@marblejs-contrib/middleware-joi';

const foo$ = r.pipe(
  r.matchPath('/'),
  r.matchType('GET'),
  r.useEffect(req$ => req$.pipe(
    use(validator$({
      query: Joi.object({
        id: Joi.number().min(1).max(10),
      })
    }));
    // ...
  )));
```

{% endcode %}

Example above will validate each incoming request connected with `foo$` *Effect*. The validation blueprint defines that the `id` query parameter should be a number between *<1..10>*. If the schema requirements are not satisfied the middleware will throw an error with description what went wrong.

```typescript
{
  error: {
    status: 400,
    message: '"id" is required'
  }
}
```

**2.** Example of validating all incoming requests:

{% code title="app.ts" %}

```typescript
import { validator$, Joi } from '@marblejs-contrib/middleware-joi';

const middlewares = [
  // ...
  validator$(
    {
      headers: Joi.object({
        token: Joi.string().token().required(),
        accept: Joi.string().default('application/json')
      })
    },
    { stripUnknown: true },
  )
];

const effects = [
  endpoint1$,
  endpoint2$,
  ...
];

const app = httpListener({ middlewares, effects });
```

{% endcode %}

### Credits

Middleware author: [Lucio Rubens](https://github.com/luciorubeens)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://marblejs.gitbook.io/docs/other/api-reference/middleware-joi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.