validation.uk-ni-number

export function validateUkNiNumber(value: string): UkNiNumber

/** normalised is null when valid is false. */
export interface UkNiNumber {
  readonly valid: boolean;
  /** nine characters, upper case, no spaces: "AB123456C" */
  readonly normalised: string | null;
  /** null when valid; empty, bad-character, bad-length, bad-format, bad-prefix or bad-suffix */
  readonly reason: string | null;
}

import { validateUkNiNumber } from "#fune/validation.uk-ni-number@^2";

import { type UkNiNumber } from "./validation_uk_ni_number_types.ts";

/** HMRC NIM39110: D, F, I, Q, U and V are never either letter of a prefix, and O is never the second. */
const BARRED_FIRST = "DFIQUV";
const BARRED_SECOND = "DFIOQUV";

/** Prefixes made of allowed letters that HMRC still never issues. */
const BARRED_PREFIXES = ["BG", "GB", "KN", "NK", "NT", "TN", "ZZ"];

/** The suffix records the quarter a contribution card was once returned in, and is always one of these four. */
const SUFFIXES = "ABCD";

function invalid(reason: string): UkNiNumber {
  return { valid: false, normalised: null, reason };
}

function isLetter(ch: string): boolean {
  return ch >= "A" && ch <= "Z";
}

function isDigit(ch: string): boolean {
  return ch >= "0" && ch <= "9";
}

/**
 * Check a National Insurance number's shape and prefix rules.
 *
 * There is no check digit in a NINO, so a pass means "could have been issued",
 * never "belongs to this person". The checks run in a fixed order (characters,
 * length, shape, prefix, suffix) so that every language reports the same first
 * reason.
 */
export function validateUkNiNumber(value: string): UkNiNumber {
  if (typeof value !== "string") return invalid("empty");
  let compact = "";
  for (let ch of value) {
    // Only the ASCII space is ignored: NINOs are printed in pairs.
    if (ch === " ") continue;
    // ASCII-only upper-casing, so no language's Unicode rules can turn a stray
    // character into a letter that passes.
    if (ch >= "a" && ch <= "z") ch = String.fromCharCode(ch.charCodeAt(0) - 32);
    if (!isLetter(ch) && !isDigit(ch)) return invalid("bad-character");
    compact += ch;
  }
  if (compact === "") return invalid("empty");
  if (compact.length !== 9) return invalid("bad-length");
  if (!isLetter(compact[0]) || !isLetter(compact[1]) || !isLetter(compact[8])) return invalid("bad-format");
  for (let i = 2; i < 8; i++) {
    if (!isDigit(compact[i])) return invalid("bad-format");
  }
  if (
    BARRED_FIRST.includes(compact[0]) ||
    BARRED_SECOND.includes(compact[1]) ||
    BARRED_PREFIXES.includes(compact.slice(0, 2))
  ) {
    return invalid("bad-prefix");
  }
  if (!SUFFIXES.includes(compact[8])) return invalid("bad-suffix");
  return { valid: true, normalised: compact, reason: null };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add validation.uk-ni-number

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./validation.uk-ni-number-2.0.0-typescript.fune, or fetch it from a terminal with fune pull validation.uk-ni-number@2.0.0:typescript.

The whole function, every language, is one file too: validation.uk-ni-number-2.0.0.fune, 16,329 bytes, sha256 64cd5b29cb5b59b7db384f18e0d7d3705f1b70d3e382266a9a09b96170171293. It installs into a project of any language.

// fune: before validation.uk-ni-number

// fune: after validation.uk-ni-number

// fune: step validation.uk-ni-number after <n|label>

More from the author

## 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.

Files