validation.nhs-number

Check an NHS number's modulus 11 check digit and normalise it to ten digits.

2.0.0 · published 2026-10-03 by charlie · Anterra

Pinned by 17 tests, run in TypeScript, Python and Rust.

What it does

Checks the modulus 11 check digit of an NHS number (England, Wales and the Isle of Man) and returns it as ten plain digits and in the 3-3-4 form the NHS displays it in.

A PASS IS NOT A PATIENT. The check digit catches a mistyped digit and most transpositions. Whether the number was issued, and to whom, is a Personal Demographics Service question.

For example

validate_nhs_number(9434765919) → valid true, normalised 9434765919, formatted 943 476 5919, reason — the NHS's own example number, as digits
validate_nhs_number(943 476 5919) → valid true, normalised 9434765919, formatted 943 476 5919, reason — the same number in the 3-3-4 display form
validate_nhs_number( 943-476-5919 ) → valid true, normalised 9434765919, formatted 943 476 5919, reason — hyphenated, with stray spaces around it

The function

The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.

def validate_nhs_number(value: str) -> NhsNumber

value	string	ten digits, optionally spaced or hyphenated: "943 476 5919"
returns	NhsNumber

The type it declares, generated into your project

@dataclass(frozen=True)
class NhsNumber:
    """normalised and formatted are null when valid is false."""

    valid: bool
    #: ten digits, no separators: "9434765919"
    normalised: Optional[str]
    #: the 3-3-4 display form: "943 476 5919"
    formatted: Optional[str]
    #: null when valid; empty, bad-character, bad-length, bad-check-digit or placeholder
    reason: Optional[str]

Your code names it in one line, in the file that uses it

from fune.validation.nhs_number import validate_nhs_number  # validation.nhs-number@^2

impl/python.py · 53 lines · open · raw

from typing import List

from .validation_nhs_number_types import NhsNumber

#: NHS Data Dictionary, NHS NUMBER: the first nine digits are weighted 10
#: down to 2.
_WEIGHTS = (10, 9, 8, 7, 6, 5, 4, 3, 2)


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


def validate_nhs_number(value: str) -> NhsNumber:
    """Check an NHS number's modulus 11 check digit.

    A pass means the number is well formed, not that it was issued or that it
    belongs to the patient in front of you: that is a Personal Demographics
    Service trace. Checks run in a fixed order (characters, length, check
    digit, placeholder) so every language reports the same first reason.
    """
    if not isinstance(value, str):
        return _invalid("empty")
    digits: List[int] = []
    for ch in value:
        # NHS numbers are displayed 3-3-4 with spaces, and some systems print
        # hyphens; both are ignored anywhere.
        if ch == " " or ch == "-":
            continue
        if ch < "0" or ch > "9":
            return _invalid("bad-character")
        digits.append(ord(ch) - 48)
    if not digits:
        return _invalid("empty")
    if len(digits) != 10:
        return _invalid("bad-length")

    total = sum(d * w for d, w in zip(digits, _WEIGHTS))
    check = 11 - total % 11
    # 11 means a check digit of 0. 10 means no number with these first nine
    # digits is ever issued, so there is nothing the tenth digit can match.
    if check == 11:
        check = 0
    if check == 10 or check != digits[9]:
        return _invalid("bad-check-digit")

    # 0000000000 and 1111111111 both satisfy the arithmetic and are the
    # placeholders people type to get past a mandatory field.
    if all(d == digits[0] for d in digits):
        return _invalid("placeholder")

    text = "".join(chr(d + 48) for d in digits)
    return NhsNumber(valid=True, normalised=text, formatted="%s %s %s" % (text[0:3], text[3:6], text[6:10]), 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.nhs-number

Download for Python validation.nhs-number-2.0.0-python.fune · 9,924 bytes sha256 f4eef894f042f82dfb5f980983e92d61054ab98b0caf276796437678b4268849

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

The whole function, every language, is one file too: validation.nhs-number-2.0.0.fune, 15,159 bytes, sha256 2787086483e4c4f9358958bfcb526f16f58d415a0a524be114297c20def61b5e. It installs into a project of any language.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

# fune: before validation.nhs-number

after — your function gets the result and the arguments, and returns the final result.

# fune: after validation.nhs-number

replace — it requires no other capability, so there is no dependency to replace.

step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show validation.nhs-number --steps.

# fune: step validation.nhs-number after <n|label>

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.

Case	Arguments		Expected
the NHS's own example number, as digits	9434765919	→	valid true, normalised 9434765919, formatted 943 476 5919, reason —
the same number in the 3-3-4 display form	943 476 5919	→	valid true, normalised 9434765919, formatted 943 476 5919, reason —
hyphenated, with stray spaces around it	943-476-5919	→	valid true, normalised 9434765919, formatted 943 476 5919, reason —
an England and Wales range number whose check digit is simply 4	4000000004	→	valid true, normalised 4000000004, formatted 400 000 0004, reason —
remainder 0 gives 11, which becomes check digit 0	4000000020	→	valid true, normalised 4000000020, formatted 400 000 0020, reason —
remainder 1 gives 10: no tenth digit can make this number valid, not even 0	4000000080	→	valid false, normalised —, formatted —, reason bad-check-digit
remainder 1 gives 10, so a tenth digit of 1 fails too	4000000081	→	valid false, normalised —, formatted —, reason bad-check-digit
the example with its check digit off by one	9434765918	→	valid false, normalised —, formatted —, reason bad-check-digit
the example with its first two digits transposed	4934765919	→	valid false, normalised —, formatted —, reason bad-check-digit
all zeros passes the arithmetic but is a placeholder	0000000000	→	valid false, normalised —, formatted —, reason placeholder

Show the other 7 tests

Case	Arguments		Expected
all ones passes the arithmetic too, and is also a placeholder	111 111 1111	→	valid false, normalised —, formatted —, reason placeholder
nine digits	943476591	→	valid false, normalised —, formatted —, reason bad-length
eleven digits	94347659190	→	valid false, normalised —, formatted —, reason bad-length
a letter O typed for a zero	4OOOOOOOO4	→	valid false, normalised —, formatted —, reason bad-character
a dot is not an accepted separator	943.476.5919	→	valid false, normalised —, formatted —, reason bad-character
the empty string		→	valid false, normalised —, formatted —, reason empty
separators and nothing else	-	→	valid false, normalised —, formatted —, reason empty

More from the author

## The check (NHS Data Dictionary, NHS NUMBER)

Multiply the first nine digits by 10, 9, 8, 7, 6, 5, 4, 3 and 2 and add them up. Take the remainder on dividing by 11 and subtract it from 11. A result of 11 means a check digit of 0. A result of 10 means the number is invalid, and no tenth digit can rescue it: an implementation that folds 10 into 0 would wrongly accept "4000000080". Otherwise the result must equal the tenth digit.

## Beyond the Data Dictionary

Numbers made of one repeated digit are refused as `placeholder`, even though 0000000000 and 1111111111 satisfy the arithmetic, because they are what people type to get past a mandatory field. This is the one rule here that the Data Dictionary does not state.

Nothing else is refused by range. Scotland's CHI numbers and Northern Ireland's Health and Care numbers use the same ten-digit modulus 11 scheme, so they pass too; if you need England and Wales numbers only, check the issuing range yourself. Test numbers in the 999 range pass as well.

## Input and result

ASCII spaces and hyphens are ignored anywhere. Any other character is `bad-character`. Validators answer rather than throw.

| reason | meaning (checked in this order) | |---|---| | `empty` | nothing but separators, or not a string | | `bad-character` | a character other than a digit, space or hyphen | | `bad-length` | not ten digits | | `bad-check-digit` | the modulus 11 check fails, including the "10" case | | `placeholder` | all ten digits the same |

## Source

NHS England, NHS Data Model and Dictionary, attribute "NHS NUMBER" (page published 15 July 2026, read 22 September 2026): https://www.datadictionary.nhs.uk/attributes/nhs_number.html

2.0.0 renames the function from `nhsNumber` to `validateNhsNumber` (`validate_nhs_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

Path	Bytes
README.md	2,345
impl/python.py	2,020
impl/rust.rs	3,043
impl/typescript.ts	1,983
vectors.json	3,046