# validation.uk-ni-number

Checks that a UK National Insurance number (NINO) has the shape HMRC issues
and uses none of the prefix letters HMRC rules out, and returns it upper case
with the spaces removed, the form payroll submissions (RTI) carry.

A NINO HAS NO CHECK DIGIT. A pass means the number could have been issued;
only HMRC or DWP can say it was, and to whom. Treat this as typo-catching at
the keyboard.

## The rules (HMRC NIM39110)

- Two prefix letters, six digits, one suffix letter.
- D, F, I, Q, U and V are never used as either prefix letter.
- O is never the second prefix letter. It may be the first: "OA123456B" passes,
  and a validator that bans O everywhere gets this wrong.
- BG, GB, KN, NK, NT, TN and ZZ are never used as prefixes.
- The suffix is always A, B, C or D. Some older systems accept a blank
  suffix; HMRC's manual says the suffix is always present, so it is required.

HMRC's printed example, "QQ 12 34 56 A", is deliberately invalid (Q is barred),
and is a vector here.

Administrative references that look like NINOs are not rejected by name. OO
(tax credits) and TN (retired temporary numbers) already fail the letter
rules and PP999999P fails on its suffix. FY, NC, PY and PZ are
administrative prefixes the manual describes as out of use, but it does not
list them as barred, so they pass. Temporary Reference Numbers ("11 a1 11 11")
are not NINOs and fail.

## Input and result

Case is ignored and ASCII spaces are ignored anywhere. Anything else that is
not an ASCII letter or digit (hyphens, dots, non-breaking spaces, accented
letters) is `bad-character`. Validators answer rather than throw.

| reason | meaning (checked in this order) |
|---|---|
| `empty` | nothing but spaces, or not a string |
| `bad-character` | a character other than an ASCII letter, digit or space |
| `bad-length` | not nine characters once spaces are removed |
| `bad-format` | not two letters, six digits and a letter |
| `bad-prefix` | a barred letter or prefix |
| `bad-suffix` | the last letter is not A, B, C or D |

## Source

HMRC National Insurance Manual, NIM39110 "National Insurance Numbers (NINOs):
Format and Security: What a NINO looks like", read 22 September 2026:
https://www.gov.uk/hmrc-internal-manuals/national-insurance-manual/nim39110

2.0.0 renames the function from `ukNiNumber` to `validateUkNiNumber` (`validate_uk_ni_number` in Python and
Rust), so every validator that returns a result record is `validateX` and
every one that returns a bool is `isX`. Nothing else changed; 1.0.0 stays
published under the old name.