validation.uk-utr

export function validateUkUtr(value: string): UkUtr

/** normalised is null when valid is false. */
export interface UkUtr {
  readonly valid: boolean;
  /** ten digits, no spaces and no K */
  readonly normalised: string | null;
  /** null when valid; empty, bad-character, bad-length, thirteen-digits or bad-check-digit */
  readonly reason: string | null;
}

import { validateUkUtr } from "#fune/validation.uk-utr@^2";

import { type UkUtr } from "./validation_uk_utr_types.ts";

/**
 * Weights for the second to tenth digits; the first digit is the check digit.
 * From HMRC's own reference checker (hmrc/domain, UtrReferenceChecker).
 */
const WEIGHTS = [6, 7, 8, 9, 10, 5, 4, 3, 2];

/**
 * The check digit for each remainder of the weighted sum modulo 11. It is
 * 11 - remainder except that remainders 0 and 1 give 2 and 1, so a check digit
 * is always a single digit and no reference is impossible.
 */
const CHECK_DIGITS = [2, 1, 9, 8, 7, 6, 5, 4, 3, 2, 1];

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

/**
 * Check a Unique Taxpayer Reference (Self Assessment or Corporation Tax).
 *
 * A pass means the reference is well formed, not that HMRC issued it to this
 * taxpayer. Checks run in a fixed order (characters, length, check digit) so
 * every language gives the same first reason.
 */
export function validateUkUtr(value: string): UkUtr {
  if (typeof value !== "string") return invalid("empty");
  let compact = "";
  for (const ch of value) if (ch !== " ") compact += ch;
  if (compact === "") return invalid("empty");
  // Self Assessment shows the UTR with a K after it and some letters put it
  // in front; one K at either end is stripped, as HMRC's checker does.
  if (compact[0] === "K" || compact[0] === "k") compact = compact.slice(1);
  else if (compact.endsWith("K") || compact.endsWith("k")) compact = compact.slice(0, -1);

  const digits: number[] = [];
  for (const ch of compact) {
    if (ch < "0" || ch > "9") return invalid("bad-character");
    digits.push(ch.charCodeAt(0) - 48);
  }
  if (digits.length === 13) return invalid("thirteen-digits");
  if (digits.length !== 10) return invalid("bad-length");

  let total = 0;
  for (let i = 0; i < 9; i++) total += digits[i + 1] * WEIGHTS[i];
  if (CHECK_DIGITS[total % 11] !== digits[0]) return invalid("bad-check-digit");
  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-utr

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

The whole function, every language, is one file too: validation.uk-utr-2.0.1.fune, 15,621 bytes, sha256 e5dd2f390ffd7aa5941f98bbbec6482e0408926ba489ebfb849fb1f8d16a147f. It installs into a project of any language.

// fune: before validation.uk-utr

// fune: after validation.uk-utr

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

More from the author

## The check

The first digit is the check digit. Multiply the second to tenth digits by 6, 7, 8, 9, 10, 5, 4, 3 and 2, add them up and take the remainder on dividing by 11. The check digit for remainders 0 to 10 is 2, 1, 9, 8, 7, 6, 5, 4, 3, 2, 1: that is 11 minus the remainder, except that remainders 0 and 1 give 2 and 1. The often-quoted shortcut "(11 - remainder) mod 11" gets those two remainders wrong and rejects real references such as HMRC's own test reference 2234567890.

HMRC has not published the algorithm as a specification. The weights and the remainder table here are taken from HMRC's own open-source reference checker, and its valid and invalid test references are vectors here.

## Input

HMRC's design pattern for asking for a UTR allows spaces and a K at the start or end ("1234567890K" is how Self Assessment online shows it). ASCII spaces are ignored anywhere, and one K (either case) is removed from the start or, failing that, the end. Anything else is `bad-character`.

The same pattern allows 13-digit forms and says to remove "extra digits", but does not say which three digits are extra. Rather than guess, a 13-digit value is refused with its own reason, `thirteen-digits`, so a form can ask for the ten-digit reference.

| reason | meaning (checked in this order) | |---|---| | `empty` | nothing but spaces, or not a string | | `bad-character` | a character other than a digit or space, after one K is removed | | `thirteen-digits` | a 13-digit form (see above) | | `bad-length` | any other length than ten digits | | `bad-check-digit` | the first digit does not match |

## Sources

- HMRC, hmrc/domain on GitHub, `referencechecker/ReferenceChecker.scala` (`UtrReferenceChecker`, `SelfAssessmentReferenceChecker`) and `ModulusCheckerSpec.scala`, read 23 September 2026: https://github.com/hmrc/domain - HMRC design patterns, "Unique Taxpayer Reference": https://design.tax.service.gov.uk/hmrc-design-patterns/unique-taxpayer-reference/

2.0.0 renames the function from `ukUtr` to `validateUkUtr` (`validate_uk_utr` 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.

## Notices

The UTR check method follows HMRC's domain library (https://github.com/hmrc/domain, referencechecker/ReferenceChecker.scala), Copyright HM Revenue & Customs, licensed under the Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0). This capability implements the same check in TypeScript, Python and Rust.

2.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files