validation.uk-ni-number

def validate_uk_ni_number(value: str) -> UkNiNumber

@dataclass(frozen=True)
class UkNiNumber:
    """normalised is null when valid is false."""

    valid: bool
    #: nine characters, upper case, no spaces: "AB123456C"
    normalised: Optional[str]
    #: null when valid; empty, bad-character, bad-length, bad-format, bad-prefix or bad-suffix
    reason: Optional[str]

from fune.validation.uk_ni_number import validate_uk_ni_number  # validation.uk-ni-number@^2

from .validation_uk_ni_number_types import UkNiNumber

#: HMRC NIM39110: D, F, I, Q, U and V are never either letter of a prefix,
#: and O is never the second.
_BARRED_FIRST = "DFIQUV"
_BARRED_SECOND = "DFIOQUV"

#: Prefixes made of allowed letters that HMRC still never issues.
_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.
_SUFFIXES = "ABCD"


def _invalid(reason: str) -> UkNiNumber:
    return UkNiNumber(valid=False, normalised=None, reason=reason)


def _is_letter(ch: str) -> bool:
    return "A" <= ch <= "Z"


def _is_digit(ch: str) -> bool:
    return "0" <= ch <= "9"


def validate_uk_ni_number(value: str) -> UkNiNumber:
    """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.
    """
    if not isinstance(value, str):
        return _invalid("empty")
    compact = ""
    for ch in 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 "a" <= ch <= "z":
            ch = chr(ord(ch) - 32)
        if not _is_letter(ch) and not _is_digit(ch):
            return _invalid("bad-character")
        compact += ch
    if compact == "":
        return _invalid("empty")
    if len(compact) != 9:
        return _invalid("bad-length")
    if not (_is_letter(compact[0]) and _is_letter(compact[1]) and _is_letter(compact[8])):
        return _invalid("bad-format")
    if not all(_is_digit(ch) for ch in compact[2:8]):
        return _invalid("bad-format")
    if compact[0] in _BARRED_FIRST or compact[1] in _BARRED_SECOND or compact[0:2] in _BARRED_PREFIXES:
        return _invalid("bad-prefix")
    if compact[8] not in _SUFFIXES:
        return _invalid("bad-suffix")
    return UkNiNumber(valid=True, normalised=compact, reason=None)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./validation.uk-ni-number-2.0.0-python.fune, or fetch it from a terminal with fune pull validation.uk-ni-number@2.0.0:python.

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