chassi

Offline VIN decoder library.

Installation

npm install chassi

Usage

Library

import { decodeVin, validateVin } from "chassi";

decodeVin("WVWZZZ3CZWE123456");
// {
//   vin: 'WVWZZZ3CZWE123456',
//   valid: true,
//   manufacturer: 'Volkswagen',
//   country: 'Germany',
//   countryCode: 'DE',
//   year: 2014,
//   possibleYears: [1984, 2014],
//   model: 'Golf',
//   confidence: 1,
//   disclaimer: '...'
// }

validateVin("WVWZZZ3CZWE123456");
// {
//   valid: true,
//   vin: 'WVWZZZ3CZWE123456',
//   normalizedVin: 'WVWZZZ3CZWE123456',
//   errors: [],
//   details: {
//     lengthValid: true,
//     charactersValid: true,
//     checkDigitValid: true,
//     providedCheckDigit: 'Z',
//     calculatedCheckDigit: 'Z'
//   }
// }

CLI

npx chassi decode WVWZZZ3CZWE123456

# === VIN Decode Result ===
#
# VIN:          WVWZZZ3CZWE123456
# Valid:        Yes
# Manufacturer: Volkswagen
# Country:      Germany
# Year:         2014
# Model:        Golf
# Confidence:   100%
#
# Components:
#   WMI:        WVW
#   VDS:        ZZZ3CZ
#   VIS:        WE123456
#   Year Code:  W
#   Plant Code: E
#   Sequential: 123456

npx chassi validate WVWZZZ3CZWE123456

# === VIN Validation Result ===
#
# VIN:           WVWZZZ3CZWE123456
# Valid:         Yes
# Length OK:     Yes
# Characters OK: Yes
# Check Digit:   Valid

npx chassi check 1HGBH41JXMN109186

# === Check Digit Verification ===
#
# VIN:        1HGBH41JXMN109186
# Provided:   X
# Calculated: X
# Applicable: Yes (North American)
# Valid:      Yes

CLI Fields

Field	Command	Description
VIN	all	The normalized (uppercase) VIN
Valid	decode/validate/check	Whether the VIN passes all applicable validations
Manufacturer	decode	Manufacturer name or "Unknown"
Country	decode	Country of origin or "Unknown"
Year	decode	Most likely model year or "Unknown"
Model	decode	Inferred model or "Unknown"
Confidence	decode	How much data was matched (0-100%)
Length OK	validate	Whether the VIN has exactly 17 characters
Characters OK	validate	Whether all characters are valid (no I, O, Q, or special chars)
Check Digit	validate	Whether the check digit at position 9 is correct
Provided	check	The character at position 9 of the VIN
Calculated	check	The expected check digit per ISO 3779 weighted sum mod 11
Applicable	check	Whether check digit validation applies — only North American VINs (US, CA, MX) require it

VIN Structure

Position	Name	Description
1-3	WMI	World Manufacturer Identifier
4-9	VDS	Vehicle Descriptor Section
9	Check	Check digit (ISO 3779)
10	Year	Model year code
11	Plant	Assembly plant
12-17	Seq	Sequential number

API Reference

decodeVin(vin, options?)

Returns decoded vehicle information from the VIN.

Field	Type	Description
vin	string	The original VIN provided
valid	boolean	Whether the VIN passes all applicable validations (structure + check digit)
manufacturer	string?	Manufacturer name (e.g. "Volkswagen")
country	string?	Country of origin (e.g. "Germany")
countryCode	string?	ISO country code (e.g. "DE")
year	number?	Most likely model year
possibleYears	number[]	All possible model years (year codes cycle every 30 years)
model	string?	Inferred model name, if a known VDS pattern matches
confidence	number	Confidence score from 0 to 1 based on how much data was matched
components	object?	VIN components (WMI, VDS, VIS, etc.). Only present if includeComponents: true
disclaimer	string	Legal disclaimer about the inferred data

Options:

Option	Type	Default	Description
strict	boolean	false	Reject VINs with invalid check digit (even non-NA)
includeComponents	boolean	false	Include parsed VIN components in the result

validateVin(vin, options?)

Returns detailed validation results for a VIN.

Field	Type	Description
valid	boolean	Whether the VIN passes all applicable validations
vin	string	The original VIN provided
normalizedVin	string	Uppercase, stripped of spaces and dashes
errors	array	List of validation errors (see below)
details.lengthValid	boolean	Whether the VIN has exactly 17 characters
details.charactersValid	boolean	Whether all characters are valid (A-H, J-N, P, R-Z, 0-9)
details.checkDigitValid	boolean	Whether the check digit (position 9) is correct
details.checkDigitApplicable	boolean	Whether check digit validation applies to this VIN's region
details.providedCheckDigit	string?	The check digit character found at position 9
details.calculatedCheckDigit	string?	The expected check digit calculated via ISO 3779

Options:

Option	Type	Default	Description
strictCheckDigit	boolean	false	When true, enforces check digit validation for all VINs

Check digit applicability: North American vehicles (US, CA, MX) require check digit validation per 49 CFR § 565. European and other regions do not use the ISO 3779 check digit system, so the check digit position may contain any valid character. When checkDigitApplicable is false, the check digit is not validated and checkDigitValid is always true.

Error Codes

Code	Description
VIN_EMPTY	No VIN was provided
INVALID_LENGTH	VIN does not have exactly 17 characters
FORBIDDEN_CHARACTER	VIN contains I, O, or Q (not allowed by ISO 3779)
INVALID_CHARACTER	VIN contains a character outside A-HJ-NPR-Z0-9
INVALID_CHECK_DIGIT	Check digit at position 9 does not match expected

Data Sources

Standards

Standard	Description
ISO 3779:2009	VIN content and structure
ISO 3780:2009	WMI code assignment
SAE J853	VIN systems specification
49 CFR § 565	U.S. federal VIN requirements

Databases

Source	Usage
NHTSA vPIC	WMI validation, manufacturer data

Notes

• WMI codes: Assigned by SAE International under ISO 3780
• Model patterns: Community-sourced from observed VINs (not official)
• Year codes: Defined by ISO 3779, cycle every 30 years

⚠️ Model inference is approximate. Always verify with official sources for critical applications.