5 Ways to Validate Phone Numbers in Joi

Ensuring phone numbers are valid is a frequent task in Joi schemas for data integrity. You can approach this in several ways. We'll look at five methods with code examples, discuss the shortcomings of common libraries, and then show how Abstract API offers a more dependable alternative.

How to Implement Phone Number Validation in Joi

This section covers four distinct methods to validate phone numbers in Joi. Each approach has a different implementation, from simple regular expressions to more advanced, feature-rich library extensions.

Regex-Only Schema

This method uses Joi’s native .pattern() function, which runs fast and has zero runtime dependencies. When you need to accept multiple national formats, you can create several regular expressions or wrap them in Joi.alternatives().

const Joi = require('joi');

const e164 = /^\+?[1-9]\d{1,14}$/;           // accepts +15551234567 etc.
const schema = Joi.string().pattern(e164).required();

schema.validate('+15551234567'); // { value: '+15551234567' }  
schema.validate('555-1234');     // ValidationError

Salesflare joi-phone-number Extension

The joi-phone-number extension is a wrapper around google-libphonenumber. It supports features like defaultCountry, a strict mode, and four canonical output formats: e164, international, national, and rfc3966. It also integrates with Joi’s convert option, which can rewrite the value to the desired format before it reaches your business logic.

const BaseJoi   = require('joi');  
const extension = require('joi-phone-number');  
const Joi       = BaseJoi.extend(extension);

const schema = Joi.string().phoneNumber({ defaultCountry: 'US',
                                          format: 'e164',   // output conversion
                                          strict: true });  // reject impossible numbers

schema.validate('415-555-1212');      // => '+14155551212'  
schema.validate('+99 123');           // ValidationError

@tepez/joi-phone-number-extensions

This extension exposes libphonenumber capabilities directly. These include defaultRegion versus an explicit region, line-type filters, and runtime formatting. It provides a first-class Joi type, Joi.phoneNumber(), which makes the schema’s intent clearer than a standard string validation.

const BaseJoi = require('joi');  
const ext     = require('@tepez/joi-phone-number-extensions');  
const Joi     = BaseJoi.extend(ext);

const schema = Joi.phoneNumber()                   // dedicated type, not string()
                 .defaultRegion('US')              // assume US if no ‘+’
                 .region('US')                     // enforced country
                 .type('MOBILE')                   // only mobile lines
                 .format('E164');                  // normalised output

schema.validate('+1 541-754-3010');  // '+15417543010'

Custom Rule with libphonenumber-js

You can build a custom rule with libphonenumber-js to avoid a third-party Joi plugin. This approach gives you full control over the conversion logic and error messages. You can also select the metadata package size (core, min, or max). The rule can be wrapped in Joi.extend() to create a reusable .phone() function across different schemas.

const Joi = require('joi');  
const { isValidNumber, parsePhoneNumber } = require('libphonenumber-js/max'); // use max metadata

const phoneSchema = Joi.string().custom((value, helpers) => {
  const parsed = parsePhoneNumber(value, 'US'); // default region
  if (!parsed || !parsed.isValid()) {
    return helpers.error('any.invalid');
  }
  return parsed.number; // convert to E.164
}, 'libphonenumber validation');

phoneSchema.validate('(415) 555-1212'); // '+14155551212'

Challenges of Phone Number Validation in Joi

While the previous methods offer structural checks, they share inherent limitations that can compromise data quality. These drawbacks stem from outdated dependencies, flawed logic, and an inability to verify real-world status.

• The `joi-phone-number` plugin often lags behind `google-libphonenumber` updates. This causes the rejection of valid new dialing codes because the wrapper does not have the latest numbering plan information.
• The `joi-phone-number` extension has historically bypassed core checks. This oversight allows syntactically correct but non-existent numbers to pass validation, a flaw that can reappear as the plugin evolves.
• A regex-only schema struggles with diverse global formats. The variety of lengths and prefixes across 200+ national plans makes a single, comprehensive regular expression nearly impossible to create and maintain.
• Joi's synchronous nature limits validation to format and structure. It cannot perform real-time checks to detect deactivated or disposable numbers, which means it only confirms syntax, not actual reachability.