validation.uk-utr

pub fn validate_uk_utr(value: &str) -> UkUtr

/// normalised is null when valid is false.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UkUtr {
    pub valid: bool,
    /// ten digits, no spaces and no K
    pub normalised: Option<String>,
    /// null when valid; empty, bad-character, bad-length, thirteen-digits or bad-check-digit
    pub reason: Option<String>,
}

fune!(validation.uk-utr@^2);  // then call validate_uk_utr(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one

/// 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: [i64; 9] = [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: [i64; 11] = [2, 1, 9, 8, 7, 6, 5, 4, 3, 2, 1];

fn invalid(reason: &str) -> UkUtr {
    UkUtr {
        valid: false,
        normalised: None,
        reason: Some(reason.to_string()),
    }
}

/// 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.
pub fn validate_uk_utr(value: &str) -> UkUtr {
    let mut compact: Vec<char> = value.chars().filter(|ch| *ch != ' ').collect();
    if compact.is_empty() {
        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.remove(0);
    } else if compact[compact.len() - 1] == 'K' || compact[compact.len() - 1] == 'k' {
        compact.pop();
    }

    let mut digits: Vec<i64> = Vec::new();
    for ch in &compact {
        if !ch.is_ascii_digit() {
            return invalid("bad-character");
        }
        digits.push(*ch as i64 - 48);
    }
    if digits.len() == 13 {
        return invalid("thirteen-digits");
    }
    if digits.len() != 10 {
        return invalid("bad-length");
    }

    let total: i64 = digits[1..].iter().zip(WEIGHTS.iter()).map(|(d, w)| d * w).sum();
    if CHECK_DIGITS[(total % 11) as usize] != digits[0] {
        return invalid("bad-check-digit");
    }
    UkUtr {
        valid: true,
        normalised: Some(compact.iter().collect()),
        reason: None,
    }
}

/// Object keys are camelCase to match the shared vectors, and so that a
/// capability building on this one can reuse the same shape.
pub fn uk_utr_to_value(result: &UkUtr) -> Value {
    let text = |field: &Option<String>| match field {
        Some(s) => Value::str(s),
        None => Value::Null,
    };
    Value::obj(vec![
        ("valid", Value::Bool(result.valid)),
        ("normalised", text(&result.normalised)),
        ("reason", text(&result.reason)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    // A non-string argument arrives here as an empty string, which is exactly
    // the answer TypeScript and Python give for a non-string: empty.
    uk_utr_to_value(&validate_uk_utr(args[0].as_str()))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. 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 Rust implementation. Install it without the registry with fune add ./validation.uk-utr-2.0.0-rust.fune, or fetch it from a terminal with fune pull validation.uk-utr@2.0.0:rust.

The whole function, every language, is one file too: validation.uk-utr-2.0.0.fune, 14,818 bytes, sha256 f866c1a37886789ae2812344db45fc881ddf574927be7389c4fc7aa24e409948. 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.

Files