Implementing Request Validation in AdonisJS 5 with Schema Files

Implementing Request Validation in AdonisJS 5 with Schema Files

The common pain point when building APIs is receiving malformed JSON payloads that cause runtime errors or security issues. The useful takeaway is that AdonisJS 5 provides a built‑in, type‑safe validation layer that lets you describe request shapes in separate schema files and automatically enforce them in controllers.

Prerequisites

• Node.js version 18 or newer – required for the TypeScript compiler used by AdonisJS 5.
• AdonisJS 5 installed via npm: npm i adonisjs@5 (run in the project root).
• A .env file containing APP_KEY – this secret key encrypts password hashes and signs tokens.
• Access to the source directory with write permission (typically a developer account).

Step‑by‑step Procedure

1. Create a validator file. In the project root run:
   

   touch app/Validators/userValidator.ts

   Open the file and extend the Schema class:
   

   import { Schema, rules } from '@ioc:Adonis/Core/Validator';
   import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext';
   
   export default class UserValidator extends Schema {
     public async validate(params: HttpContextContract['params'], rules: SchemaParams) {
       return this.object(params, {
         username: rules.string({ minLength: 3, maxLength: 30 }).required(),
         email: rules.email({ email: true }).required(),
         age: rules.number({ minValue: 18, maxValue: 99 }).optional(),
       });
     }
   }

   The object method defines rules for the request body (or query parameters if you use query instead of params).
2. Invoke the validator in a controller method. Example controller (app/Controllers/Http/UserController.ts):
   

   import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext';
   import UserValidator from 'App/Validators/UserValidator';
   import User from 'App/Models/User';
   
   export default class UserController {
     public async create({ request, response }: HttpContextContract) {
       const payload = await validate(request, new UserValidator());
       const user = await User.create(payload);
       return response.created(user);
     }
   }

   The await validate call throws a ValidationException when any rule fails.
3. Handle the exception and return a structured error response. Add a try/catch block:
   

   try {
     const payload = await validate(request, new UserValidator());
     const user = await User.create(payload);
     return response.created(user);
   } catch (error) {
     if (error instanceof HttpException && error.status === 422) {
       return response.response(422, {
         message: 'The submitted data did not pass validation.',
         errors: error.messages,
       });
     }
     // unexpected errors
     console.error(error);
     return response.response(500, { message: 'Internal server error' });
   }

   The error.messages object contains field‑specific messages generated from the schema rules.

Expected Checks

• Successful creation returns HTTP 201 with the newly created user JSON.
• When validation fails, the endpoint returns HTTP 422 and a JSON payload containing errors mapped to each field.
• Inspect the request object after validation – the validated data is automatically merged into request.all() for downstream use.

Recovery Options

• Wrap the validate call in a try/catch block as shown above; this prevents the request from crashing and lets you log detailed error information.
• Log the error object (including error.messages) to your application logger; this aids troubleshooting without exposing sensitive data to the client.
• Return a consistent JSON error shape, e.g., { message: '...', errors: { email: ['The email must be valid.' }] }, so API consumers can programmatically handle failures.

Verification & Testing

1. Unit test: create a test that sends an invalid payload (e.g., missing username) and asserts that the response status is 422 and that response.json().errors.username contains the expected message. Example command:
   

   npm run test --test=user.validation.test.ts

   The test should pass if the validation layer behaves as documented.
2. Manual test: use Postman or curl to call POST /users with a valid payload:
   

   curl -X POST http://localhost:3333/users \
     -H \"Content-Type: application/json\" \
     -d '{\"username\":\"john\",\"email\":\"[contact removed]\",\"age\":25}'
   

   Check that the response code is 201 and that the returned JSON contains the created user fields.

Limitations & Risks

• Node.js < 18 may break TypeScript compilation and cause runtime mismatches with AdonisJS 5 features.
• Missing APP_KEY prevents encryption of password hashes and token signing, leading to authentication failures.
• Incorrect schema rules (e.g., using rules.string() without length constraints) can allow unexpected data shapes, potentially causing silent corruption downstream.

Practical Way to Check the Result

After implementing the validator, run the unit test suite and manually invoke the endpoint with a tool like Postman. Verify that a 422 response includes the correct error structure and that a 201 response returns the expected JSON body. If any discrepancy appears, review the schema definition for typo‑related rule names and ensure the APP_KEY is set.

Conclusion

By defining request shapes in dedicated schema files and using the validate helper, AdonisJS 5 eliminates the need for manual checks scattered across controllers. The approach is declarative, type‑safe, and integrates cleanly with the framework’s middleware pipeline, making API development more reliable and maintainable.