Five different validation questions
| Question | Typical method | What it proves |
|---|---|---|
| Can the input be parsed? | Country-aware parser | The string can be interpreted. |
| Is the structure possible? | Length and prefix metadata | The shape fits a numbering plan. |
| Is it currently valid? | Maintained numbering metadata | The range is recognized by the library. |
| Is it reachable? | Carrier or delivery attempt | A route may currently exist. |
| Does the user control it? | Consent-based OTP or call | The user completed a challenge. |
The GetPhoneNum validator intentionally answers only the basic structural question and labels that limitation in the result.
Normalize before comparing
Two strings can represent the same destination: +1 202 555 0123, (202) 555-0123 and 2025550123 may be equivalent when the default country is the United States. Parse with country context, normalize to E.164 and then compare canonical values. Do not deduplicate on raw input.
Use a maintained library in production
National numbering plans change, use variable lengths and contain special services that are difficult to model with a single expression. Google's libphonenumber project supplies parsing, formatting and validation metadata for many regions. Use an actively maintained binding for your language, pin and review updates, and test changes against your fixture suite.
A browser can give immediate feedback, but the server should repeat security- or business-critical checks. Treat client validation as usability, not a trust boundary.
Design useful error states
- Missing country: ask for region context instead of guessing silently.
- Too short or too long: explain the expected national digit range.
- Unsupported type: distinguish a business rule from a malformed number.
- Verification failed: do not imply the number itself is invalid.
Keep the user's original input visible while showing the normalized interpretation. This makes corrections easier and exposes bad country assumptions.
Build a validation test matrix
For every supported country, include a valid national form, valid E.164 form, pasted punctuation, leading trunk prefix, one digit too short, one digit too long, an impossible prefix, extension input and non-ASCII whitespace. Add regression fixtures whenever a real support case reveals a parser edge.
Use the bulk fixture generator for positive structural fixtures and deliberately author invalid cases rather than creating them at random.
Operational review before launch
Write down which validation layer blocks submission and which layer only shows a warning. For example, a missing country may block a form, while an unverified number may still be saved as a draft but cannot be used for account recovery. Server logs should record region, result category and metadata version without storing full phone strings in routine analytics.
After every numbering-library update, rerun the country fixture matrix and review changed results manually. A newer metadata release can legitimately change a classification, but it can also expose an assumption in your product rules. Treat those changes as data-review work rather than silent dependency noise.
How this guide connects to the toolkit
This page is written as an implementation reference, not a generic glossary. Use it with the interactive tools when you need to turn an idea into a testable behavior: generate a fixture, format it, validate the structural claim, then record the country and expected result beside your product test. Keeping the explanation and tool output connected helps future reviewers understand why a number was accepted or rejected.
If you copy an example into your own documentation, also copy the safety context. A phone string without its country, source note and limitation can look like a contactable number. The surrounding guidance is part of the value of the fixture.