validation.nhs-number

export function validateNhsNumber(value: string): NhsNumber

/** normalised and formatted are null when valid is false. */
export interface NhsNumber {
  readonly valid: boolean;
  /** ten digits, no separators: "9434765919" */
  readonly normalised: string | null;
  /** the 3-3-4 display form: "943 476 5919" */
  readonly formatted: string | null;
  /** null when valid; empty, bad-character, bad-length, bad-check-digit or placeholder */
  readonly reason: string | null;
}

import { validateNhsNumber } from "#fune/validation.nhs-number@^2";

import { type NhsNumber } from "./validation_nhs_number_types.ts";

/** NHS Data Dictionary, NHS NUMBER: the first nine digits are weighted 10 down to 2. */
const WEIGHTS = [10, 9, 8, 7, 6, 5, 4, 3, 2];

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

/**
 * 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.
 */
export function validateNhsNumber(value: string): NhsNumber {
  if (typeof value !== "string") return invalid("empty");
  const digits: number[] = [];
  for (const ch of value) {
    // NHS numbers are displayed 3-3-4 with spaces, and some systems print
    // hyphens; both are ignored anywhere.
    if (ch === " " || ch === "-") continue;
    if (ch < "0" || ch > "9") return invalid("bad-character");
    digits.push(ch.charCodeAt(0) - 48);
  }
  if (digits.length === 0) return invalid("empty");
  if (digits.length !== 10) return invalid("bad-length");

  let total = 0;
  for (let i = 0; i < 9; i++) total += digits[i] * WEIGHTS[i];
  let 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 || 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 (digits.every((d) => d === digits[0])) return invalid("placeholder");

  const text = digits.join("");
  return { valid: true, normalised: text, formatted: `${text.slice(0, 3)} ${text.slice(3, 6)} ${text.slice(6)}`, 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.nhs-number

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

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.

// fune: before validation.nhs-number

// fune: after validation.nhs-number

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

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