aamva-decoder

Parse PDF-417 barcode data from US and Canadian driver's licenses. Supports AAMVA versions 1 through 11 (2025 standard).

Usage

import { parseLicense } from "aamva-decoder";

const barcodeData: string = /* scan PDF-417 barcode */;
const license = parseLicense(barcodeData);

console.log(license.firstName);      // "JOHN"
console.log(license.lastName);       // "PUBLIC"
console.log(license.dateOfBirth);    // Date object
console.log(license.state);          // "CA"
console.log(license.aamvaVersion);   // 11

If you already have a parsed BarcodeFile (from parseBarcodeString), you can skip re-parsing:

import { parseBarcodeString, parseLicenseFromBarcode } from "aamva-decoder";

const barcode = parseBarcodeString(barcodeData);
const license = parseLicenseFromBarcode(barcode);

Raw Element Access

Every License object includes a raw field containing all element key-value pairs from the barcode. This is useful for accessing jurisdiction-specific or future element IDs that aren't mapped to named fields:

const license = parseLicense(barcodeData);
console.log(license.raw["ZVA"]); // jurisdiction-specific element
console.log(license.raw["DCA"]); // raw vehicle class code

Installation

npm install aamva-decoder

AAMVA Standard

Supported Fields

| Name | Description | Element ID | Type | License Attribute | |:-----|:------------|:----------:|:-----|:--------------------| | First Name | Customer first name | DAC | string | firstName | | Last Name | Customer last name | DCS | string | lastName | | Middle Name | Customer middle name | DAD | string | middleName | | Name Suffix | Name suffix (JR, SR, etc.) | DCU | string | nameSuffix | | Name Prefix | Name prefix (DR, etc.) | DAF | string | namePrefix | | First Name (v2-3) | First name element used in v2-3 | DCT | string | firstNameV2 | | Date of Birth | Customer date of birth | DBB | Date | dateOfBirth | | Expiration Date | Document expiration date | DBA | Date | expirationDate | | Issue Date | Document issue date | DBD | Date | issueDate | | Sex | Customer sex | DBC | string | sex | | Eye Color | Customer eye color | DAY | string | eyeColor | | Hair Color | Customer hair color | DAZ | string | hairColor | | Height | Customer height | DAU | string | height | | Height (cm) | Height in centimeters | DAV | string | heightCm | | Weight | Customer weight (lbs) | DAW | string | weight | | Weight (kg) | Weight in kilograms | DAX | string | weightKg | | Weight Range | Weight range code (0-9) | DCE | string | weightRange | | Street Address | Customer street address | DAG | string | streetAddress | | Street Address 2 | Street address line 2 | DAH | string | streetAddress2 | | City | Customer city | DAI | string | city | | State | Customer state | DAJ | string | state | | Postal Code | Customer postal code | DAK | string | postalCode | | Country | Issuing country | DCG | string | country | | Document Number | Unique customer ID number | DAQ/DBJ | string | documentNumber | | Document Discriminator | Unique document ID number | DCF | string | documentDiscriminator | | Vehicle Class | Jurisdiction-specific vehicle class | DCA/DAR | string | vehicleClass | | Restriction Codes | Jurisdiction-specific restriction codes | DCB/DAS | string | restrictionCodes | | Endorsement Codes | Jurisdiction-specific endorsement codes | DCD/DAT | string | endorsementCodes | | Federal Commercial Vehicle Codes | Federal commercial vehicle codes | DCH | string | federalCommercialVehicleCodes | | Standard Vehicle Classification | Standard vehicle classification | DCM | string | standardVehicleClassification | | Standard Endorsement Code | Standard endorsement code | DCN | string | standardEndorsementCode | | Standard Restriction Code | Standard restriction code | DCO | string | standardRestrictionCode | | Vehicle Class Description | Text description of vehicle class | DCP | string | vehicleClassDescription | | Endorsement Code Description | Text description of endorsements | DCQ | string | endorsementCodeDescription | | Restriction Code Description | Text description of restrictions | DCR | string | restrictionCodeDescription | | Compliance Type | REAL ID compliance ("F"=compliant, "N"=non-compliant) | DDA | string | complianceType | | Card Revision Date | Most recent card revision date | DDB | Date | cardRevisionDate | | Limited Duration Document | Is this a limited duration document? | DDD | boolean | limitedDurationDocument | | Organ Donor | Is the cardholder an organ donor? | DDK/DBH | boolean | organDonor | | Organ Donor (legacy) | Organ donor indicator (older format, pre-DDK) | DBH | string | organDonorLegacy | | Veteran | Is the cardholder a veteran? | DDL | boolean | veteran | | First Name Truncation | Was first name truncated? ("T"/"N") | DDF | string | firstNameTruncation | | Middle Name Truncation | Was middle name truncated? ("T"/"N") | DDG | string | middleNameTruncation | | Last Name Truncation | Was last name truncated? ("T"/"N") | DDE | string | lastNameTruncation | | Place of Birth | Country/municipality/state of birth | DCI | string | placeOfBirth | | Audit Information | Identifies when, where, and by whom the card was made | DCJ | string | auditInformation | | Inventory Control Number | Identifies raw materials used in card production | DCK | string | inventoryControlNumber | | Last Name Alias | Other last name by which cardholder is known | DBN/DBO | string | lastNameAlias | | First Name Alias | Other first name by which cardholder is known | DBG/DBP | string | firstNameAlias | | Suffix Alias | Other suffix by which cardholder is known | DBS | string | suffixAlias | | Race/Ethnicity | Customer race/ethnicity (v3-v10, removed in v11) | DCL | string | raceEthnicity | | HAZMAT Endorsement Exp. | HAZMAT endorsement expiration date (v3-v10, removed in v11) | DDC | Date | hazmatEndorsementExpiration | | CDL Indicator | Is this a commercial driver's license? (v11+) | DDM | boolean | cdlIndicator | | Non-Domiciled Indicator | Is this a non-domiciled license? (v11+) | DDN | boolean | nonDomiciledIndicator | | Enhanced Document Indicator | Is this an enhanced document? (v11+) | DDO | boolean | enhancedDocumentIndicator | | Permit Indicator | Is this a permit? (v11+) | DDP | boolean | permitIndicator | | Issue Timestamp | Date and time of card issuance | DBE | string | issueTimestamp | | Number of Duplicates | Number of duplicate cards issued | DBF | string | numberOfDuplicates | | Non-Resident Indicator | Non-resident indicator | DBI | string | nonResidentIndicator | | Unique Customer ID | Unique customer identifier (v1, maps to DAQ) | DBJ | string | uniqueCustomerId | | Social Security Number | Social security number (deprecated) | DBK | string | socialSecurityNumber | | AKA Date of Birth | AKA date of birth | DBL | Date | akaDateOfBirth | | AKA Social Security Number | AKA social security number (deprecated) | DBM | string | akaSocialSecurityNumber | | Under 18 Until | Date cardholder turns 18 | DDH | Date | under18Until | | Under 19 Until | Date cardholder turns 19 | DDI | Date | under19Until | | Under 21 Until | Date cardholder turns 21 | DDJ | Date | under21Until |

V1 Legacy Fields

These fields use v1-specific element IDs. Their values are also normalized into the modern field names above as fallbacks.

| Name | Description | Element ID | License Attribute | |:-----|:------------|:----------:|:--------------------| | Last Name (v1) | Last name (v1 element ID) | DAB | lastNameV1 | | Name Suffix (v1) | Name suffix (v1 element ID) | DAE | nameSuffixV1 | | Classification Code (v1) | Vehicle classification (v1 element ID) | DAR | classificationCodeV1 | | Restriction Code (v1) | Restriction code (v1 element ID) | DAS | restrictionCodeV1 | | Endorsement Code (v1) | Endorsement code (v1 element ID) | DAT | endorsementCodeV1 | | Residence Street Address | Residence street address (v1) | DAL | residenceStreetAddress | | Residence Street Address 2 | Residence street address line 2 (v1) | DAM | residenceStreetAddress2 | | Residence City | Residence city (v1) | DAN | residenceCity | | Residence Jurisdiction Code | Residence state/province (v1) | DAO | residenceJurisdictionCode | | Residence Postal Code | Residence postal code (v1) | DAP | residencePostalCode | | AKA Last Name (v1) | AKA last name (v1 element ID) | DBO | akaLastNameV1 | | AKA First Name (v1) | AKA first name (v1 element ID) | DBP | akaFirstNameV1 | | AKA Middle Name | AKA middle name | DBQ | akaMiddleName | | AKA Suffix (v1) | AKA suffix (v1 element ID) | DBR | akaSuffixV1 |

V1 Fallback Behavior

When parsing v1 barcodes, the library normalizes v1 element IDs into their modern equivalents:

• firstName = DAC, then DCT, then parsed from DAA
• lastName = DCS, then DAB, then parsed from DAA
• documentNumber = DAQ, then DBJ
• vehicleClass = DCA, then DAR (trimmed)
• restrictionCodes = DCB, then DAS (trimmed)
• endorsementCodes = DCD, then DAT (trimmed)
• lastNameAlias = DBN, then DBO
• firstNameAlias = DBG, then DBP
• organDonor = DDK, then DBH

Space-padded v1 fields are automatically trimmed; all-whitespace values become null.

All fields return null when not present in the barcode data.

Additional Parsed Metadata

These fields are derived from the barcode header, not from element IDs:

| Name | Description | Type | License Attribute | |:-----|:------------|:-----|:--------------------| | Issuer ID | 6-digit IIN of the issuing jurisdiction | number | issuerId | | AAMVA Version | AAMVA version number (1-11) | number | aamvaVersion | | Jurisdiction | Full name of the issuing jurisdiction | string | jurisdiction | | Raw Elements | All element key-value pairs from the barcode | Record<string, string> | raw |

AAMVA Element IDs by Version

Bold = mandatory in that version. -- = not included. New in v11: DDM, DDN, DDO, DDP. Removed in v11: DCL, DDC, DBN, DBG, DBS.

| Field | v1 | v2 | v3 | v4 | v5 | v6 | v7 | v8 | v9 | v10 | v11 | |:------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:---:|:---:| | First Name | DAC | DCT | DCT | DAC | DAC | DAC | DAC | DAC | DAC | DAC | DAC | | Last Name | DAB | DCS | DCS | DCS | DCS | DCS | DCS | DCS | DCS | DCS | DCS | | Middle Name | DAD | DAD | DAD | DAD | DAD | DAD | DAD | DAD | DAD | DAD | DAD | | Name Suffix | DBN | DCU | DCU | DCU | DCU | DCU | DCU | DCU | DCU | DCU | DCU | | Date of Birth | DBB | DBB | DBB | DBB | DBB | DBB | DBB | DBB | DBB | DBB | DBB | | Expiration Date | DBA | DBA | DBA | DBA | DBA | DBA | DBA | DBA | DBA | DBA | DBA | | Issue Date | DBD | DBD | DBD | DBD | DBD | DBD | DBD | DBD | DBD | DBD | DBD | | Sex | DBC | DBC | DBC | DBC | DBC | DBC | DBC | DBC | DBC | DBC | DBC | | Eye Color | DAY | DAY | DAY | DAY | DAY | DAY | DAY | DAY | DAY | DAY | DAY | | Height | DAU | DAU | DAU | DAU | DAU | DAU | DAU | DAU | DAU | DAU | DAU | | Street Address | DAG | DAG | DAG | DAG | DAG | DAG | DAG | DAG | DAG | DAG | DAG | | Street Address 2 | DAH | DAH | DAH | DAH | DAH | DAH | DAH | DAH | DAH | DAH | DAH | | City | DAI | DAI | DAI | DAI | DAI | DAI | DAI | DAI | DAI | DAI | DAI | | State | DAJ | DAJ | DAJ | DAJ | DAJ | DAJ | DAJ | DAJ | DAJ | DAJ | DAJ | | Postal Code | DAK | DAK | DAK | DAK | DAK | DAK | DAK | DAK | DAK | DAK | DAK | | Country | -- | DCG | DCG | DCG | DCG | DCG | DCG | DCG | DCG | DCG | DCG | | Document Number | DAQ | DAQ | DAQ | DAQ | DAQ | DAQ | DAQ | DAQ | DAQ | DAQ | DAQ | | Document Discriminator | -- | DCF | DCF | DCF | DCF | DCF | DCF | DCF | DCF | DCF | DCF | | Compliance Type | -- | -- | -- | DDA | DDA | DDA | DDA | DDA | DDA | DDA | DDA | | Card Revision Date | -- | -- | -- | DDB | DDB | DDB | DDB | DDB | DDB | DDB | DDB | | Limited Duration | -- | -- | -- | DDD | DDD | DDD | DDD | DDD | DDD | DDD | DDD | | Organ Donor | -- | -- | -- | -- | -- | -- | -- | DDK | DDK | DDK | DDK | | Veteran | -- | -- | -- | -- | -- | -- | -- | DDL | DDL | DDL | DDL | | First Name Truncation | -- | DDF | -- | DDF | DDF | DDF | DDF | DDF | DDF | DDF | DDF | | Middle Name Truncation | -- | DDG | -- | DDG | DDG | DDG | DDG | DDG | DDG | DDG | DDG | | Last Name Truncation | -- | DDE | -- | DDE | DDE | DDE | DDE | DDE | DDE | DDE | DDE | | Place of Birth | -- | -- | DCI | DCI | DCI | DCI | DCI | DCI | DCI | DCI | DCI | | Audit Information | -- | -- | DCJ | DCJ | DCJ | DCJ | DCJ | DCJ | DCJ | DCJ | DCJ | | Inventory Control | -- | -- | DCK | DCK | DCK | DCK | DCK | DCK | DCK | DCK | DCK | | Hair Color | DAZ | DAZ | DAZ | DAZ | DAZ | DAZ | DAZ | DAZ | DAZ | DAZ | DAZ | | Weight | DAW | DAW | DAW | DAW | DAW | DAW | DAW | DAW | DAW | DAW | DAW | | Last Name Alias | DBO | DBN | DBN | DBN | DBN | DBN | DBN | DBN | DBN | DBN | -- | | First Name Alias | DBP | DBG | DBG | DBG | DBG | DBG | DBG | DBG | DBG | DBG | -- | | Suffix Alias | DBR | -- | DBS | DBS | DBS | DBS | DBS | DBS | DBS | DBS | -- | | Race/Ethnicity | -- | -- | DCL | DCL | DCL | DCL | DCL | DCL | DCL | DCL | -- | | HAZMAT Endorsement Exp. | -- | -- | -- | DDC | DDC | DDC | DDC | DDC | DDC | DDC | -- | | CDL Indicator | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | DDM | | Non-Domiciled Indicator | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | DDN | | Enhanced Document | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | DDO | | Permit Indicator | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | DDP |

Low-Level API

For advanced use cases, you can parse the raw barcode structure:

import { parseBarcodeString } from "aamva-decoder";

const barcode = parseBarcodeString(barcodeData);
console.log(barcode.header.aamvaVersion); // 11
console.log(barcode.header.issuerId);     // 636014

for (const subfile of barcode.subfiles) {
  console.log(subfile.subfileType);  // "DL", "ZC", etc.
  console.log(subfile.elements);     // Record<string, string>
}

Utility Exports

parseWeightRange(code: string): WeightRange

Parses a weight range code (0-9) from the DCE element into a descriptive object:

import { parseWeightRange } from "aamva-decoder";

const range = parseWeightRange("5");
// { code: "5", description: "191-220 lbs (87-100 kg)", lbs: "191-220", kg: "87-100" }

The WEIGHT_RANGES constant array is also exported for enumeration.

License

MIT