validation.vin

def validate_vin(value: str) -> VinCheck

@dataclass(frozen=True)
class VinCheck:
    """The result of checking a VIN. Strings and checkDigitMatches are null when valid is false; reason is null when it is true."""

    valid: bool
    #: upper case, no spaces
    normalised: Optional[str]
    #: the world manufacturer identifier, the first three characters
    wmi: Optional[str]
    #: whether position 9 holds the computed check digit
    check_digit_matches: Optional[bool]
    #: empty, bad-character, bad-length, forbidden-letter or bad-check-digit
    reason: Optional[str]

from fune.validation.vin import validate_vin  # validation.vin@^1

from .validation_vin_types import VinCheck

#: Letter values from 49 CFR 565.15, indexed by letter A-Z. I, O and Q are
#: never used and hold -1; the others run 1-9 in three passes (A-I, J-R, S-Z)
#: with the forbidden letters' slots skipped.
_LETTER_VALUES = (1, 2, 3, 4, 5, 6, 7, 8, -1, 1, 2, 3, 4, 5, -1, 7, -1, 9, 2, 3, 4, 5, 6, 7, 8, 9)

#: Position weights; position 9 is the check digit itself and weighs nothing.
_WEIGHTS = (8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2)


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


def validate_vin(value: str) -> VinCheck:
    """Check a 17-character VIN.

    The check digit is enforced only for North American VINs (first character
    1-5), where the law requires it; elsewhere a mismatch is reported in
    check_digit_matches but does not make the VIN invalid, because many
    European and Asian VINs never carried one. Validators answer rather than
    raise.
    """
    if not isinstance(value, str):
        return _invalid("empty")

    # Folded by hand: str.upper() is Unicode-aware and Rust's ASCII fold is not.
    vin = "".join(chr(ord(ch) - 32) if "a" <= ch <= "z" else ch for ch in value if ch != " ")
    if not vin:
        return _invalid("empty")
    if any(not ("0" <= ch <= "9" or "A" <= ch <= "Z") for ch in vin):
        return _invalid("bad-character")
    if len(vin) != 17:
        return _invalid("bad-length")

    total = 0
    for i, ch in enumerate(vin):
        if ch <= "9":
            n = ord(ch) - 48
        else:
            n = _LETTER_VALUES[ord(ch) - 65]
            # I, O and Q read as 1, 0 and 0, so the standard never issues them.
            if n < 0:
                return _invalid("forbidden-letter")
        total += n * _WEIGHTS[i]
    remainder = total % 11
    expected = "X" if remainder == 10 else str(remainder)
    matches = vin[8] == expected

    # WMIs starting 1-5 are North American, where 49 CFR 565 makes the check
    # digit mandatory; anywhere else it is optional, so only report it.
    if not matches and "1" <= vin[0] <= "5":
        return _invalid("bad-check-digit")

    return VinCheck(valid=True, normalised=vin, wmi=vin[:3], check_digit_matches=matches, 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.vin

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

The whole function, every language, is one file too: validation.vin-1.0.0.fune, 17,748 bytes, sha256 310dc9072c78fe16ddf0e7f98d75b9535b807ba32c97aed2874a45be9b7b36c6. It installs into a project of any language.

# fune: before validation.vin

# fune: after validation.vin

# fune: step validation.vin after <n|label>

More from the author

THE CALCULATION: each character becomes a number (digits are themselves; A-H are 1-8, J-N 1-5, P 7, R 9, S-Z 2-9, skipping the forbidden letters), is multiplied by the weight for its position (8 7 6 5 4 3 2 10 0 9 8 7 6 5 4 3 2), and the sum is taken modulo 11; a remainder of 10 is written `X`. Position 9, the check digit itself, has weight 0.

FORBIDDEN LETTERS: I, O and Q never appear in a VIN because they read as 1, 0 and 0. They get their own reason, `forbidden-letter`, because they almost always mean a transcription slip that the user can fix by retyping that one character.

ACCEPTED INPUT: letters in either case (folded to upper case) and digits; ASCII spaces are ignored anywhere. Hyphens and anything else are refused, because VINs are never printed with them.

| reason | meaning | |--------------------|----------------------------------------------------------| | `empty` | nothing but spaces, or not a string at all | | `bad-character` | anything other than A-Z, a-z, 0-9 and spaces | | `bad-length` | not exactly 17 characters | | `forbidden-letter` | contains I, O or Q | | `bad-check-digit` | a North American VIN (starts 1-5) whose check digit is wrong |

The checks run in that order; the first failure is the reason. Validators answer rather than throw.

Out of scope: decoding the model year (position 10), the plant, or the manufacturer's name from the WMI, and pre-1981 VINs, which were not 17 characters.

Sources: ISO 3779:2009 "Road vehicles - Vehicle identification number (VIN) - Content and structure"; US 49 CFR 565.15 "Content requirements" (check digit, transliteration and weight tables), https://www.ecfr.gov/current/title-49/subtitle-B/chapter-V/part-565/subpart-B/section-565.15.

Files