Detailed output explanation

This page is currently only available in English

Detailed explanation of Output Elements in files

Identrix provides comprehensive document scanning capabilities, including Machine Readable Zone (MRZ) parsing and NFC chip reading for electronic identity documents like passports, ID cards, and driver’s licenses.

What is Scanned?

Identrix can extract data from two main sources:

  1. MRZ (Machine Readable Zone): The text block at the bottom of identity documents that contains machine-readable information
  2. NFC Chip: The embedded chip in electronic documents (e-passports, e-ID cards) that stores biometric data and additional information

Quick Start

The main output type is ScanResult, which combines data from both sources:

type ScanResult = {
  Mrz: MrzResult; // MRZ parsing results
  Nfc: NfcResult | null; // NFC chip data (if available)
  ProcessedOutput: ProcessedOutput | null; // Normalized data
  ProcessedChecks: ProcessedCheckOutputInfo | null; // Validation results
  CustomFields: StringMap; // Custom application fields
};

Machine Readable Zone (MRZ)

What is an MRZ?

The MRZ is a standardized text block found at the bottom of identity documents. It contains encoded information about the document holder and document itself, designed to be read by both machines and humans.

MRZ Document Types

Different documents use different MRZ formats:

TypeDescriptionFormat
TD1ID cards3 lines × 30 characters
TD2ID cards2 lines × 36 characters
TD3Passports2 lines × 44 characters
EUDLEU Driver’s LicensesVarious formats by country

The complete list of supported formats is available in the MRZType enum.

MRZ Configuration

Control how MRZ data is parsed using MrzSettings:

interface MrzSettings {
  AutoCleanParts: boolean; // Auto-normalize data
  UseCorrector: boolean; // Auto-correct OCR errors
  IgnoreFillerChecksNonZero: boolean; // Relaxed validation
  AllowExperimentalParsers: boolean; // Beta document support
  AddExtendedInfo: boolean; // Add / collect Additional metadata
  AddChecksInfo: boolean; // Add / collect Check details
  AgeTop: number; // Max age validation
  AgeBottom: number; // Min age validation
  TranslateIds: boolean; // Human-readable IDs
  OutputFormat: string; // Result format
}

MRZ Parsing Results

The MrzResult provides comprehensive parsing information:

Raw and Corrected Data

interface MrzData {
  RawData: string; // Original text as scanned
  Lines: string[]; // Split by line
  WasCorrected: boolean; // Whether corrections were applied
  CorrectedData: string; // Text after corrections
  InvalidChars: InvalidChar[]; // Validation errors
}

Parsed Fields

Individual fields are broken down in the Parts array:

interface MrzPart {
  Id: string; // Field name (e.g., "DocumentNumber")
  Line: number; // Which MRZ line (0-indexed)
  Offset: number; // Position in line
  Length: number; // Field length
  Corrector: MrzCorrectionType; // Correction type applied
  Raw: string; // Original value
  Overlapped: boolean; // Field boundary conflicts
}

Correction Types

Identrix can automatically correct potential common OCR errors:

enum MrzCorrectionType {
  NONE = 0, // No correction needed
  ALPHA = 1, // Alphabetic characters (A-Z)
  ALPHA_FILLER = 2, // Alphabetic with '<' fillers
  NUMERIC = 3, // Numeric characters (0-9)
  NUMERIC_FILLER = 4, // Numeric with '<' fillers
  GENDER = 5, // Gender field (M/F/X)
  DOCCODE = 6, // Document type codes
}

Check Digit Validation

MRZ data includes check digits to verify data integrity:

interface MrzCheckDigit {
  Id: string; // Field being validated
  Name: string; // Human-readable name
  FromData: string; // Data used for calculation
  Read: string; // Check digit from document
  Calc: string; // Calculated check digit
  IsValid: boolean; // Whether they match
}

Check digits validate fields like document number, date of birth, and expiry date.

Extracted Values

The Values field provides a simple key-value map of all extracted data:

{
  "DocumentNumber": "AB1234567",
  "DateOfBirth": "900115",
  "ExpiryDate": "251231",
  "Nationality": "USA",
  // ... and more
}

NFC Chip Reading

What is an NFC Chip?

Modern identity documents contain embedded NFC chips that store:

  • Biometric data (facial photo, fingerprints)
  • Complete document information
  • Digital signatures for authenticity verification

Access Methods

Establishing secure communication with the chip:

enum AccessMethodType {
  AccessMethodUnknown = 0,
  AccessMethodPlain = 1, // No encryption
  AccessMethodBAC = 2, // Basic Access Control
  AccessMethodPACE = 3, // Password Auth. Connection
  AccessMethodBAP = 4, // Basic Access Protocol
}

BAC (Basic Access Control): Uses data from the MRZ to create encryption keys PACE (Password Authenticated Connection Establishment): More secure alternative to BAC

Authentication

The chip can prove its authenticity through multiple methods:

interface AuthStatus {
  AccessMethod: AccessMethodType;
  ActiveAuthentication: AuthenticationInfo; // Chip proves it has private key
  ChipAuthentication: AuthenticationInfo; // Secure channel establishment
  PassiveAuthentication: AuthenticationInfo; // Certificate validation
  ChipAuthStatus: ChipAuthMethodType;
}

Each authentication method returns detailed information:

interface AuthenticationInfo {
  AuthState: AuthStateType; // None/Passes/Failed
  Info: string; // Details
  Reason: string; // Failure reason
  WasPerformed: boolean; // Whether attempted
}

Generic files and Data

A chip might contain multiple files and data structures that are used for different purposes, and are not included in the group data but can be extracted separately. The existence of these files depends on the type of document scanned. and the features of the chip.

Identrix support the following files:

FileDescription
CardAccessPACE configuration data
CardSecurityChip auth certificates
COMList of available DGs
SODSecurity Object Document
DIRDirectory file
AtrInfoChip Attribute data
CVCACertificate authority

Data Groups (DGs)

Chip data is organized into numbered Data Groups, that are read in order.

These groups slightly differ by document type, but in general:

For ICAO documents (e.g., passports, ID cards, Visa, etc) Identrix can return the following DGs, depending on the type of document scanned and the availability of the DG’s:

DGContents
DG1Data recorded in MRZ
DG2Encoded Identification Features - FACE (s)
DG5Displayed Identification Features - PORTRAIT
DG7Displayed Identification Features - SIGNATURE or USUAL MARK
DG11Additional Personal Detail(s)
DG12Additional Document Detail(s)
DG13Optional Detail(s)
DG14Secondary Security Info(s)
DG15Active Authentication Public Key Info
DG16Person(s) to Notify

For EU Drivers Licenses Identrix can return the following DGs, depending on the type of document scanned and the availability of the DG’s:

DGContents
DG1License Holder Demographic Data
DG5License Holder Signature Image
DG6License Holder Face Image
DG11Additional Personal Detail(s)
DG12Additional Document Detail(s)
DG13Active Authentication Public Key Info
DG14Secondary Security Info(s)

Data Group Validation

Each DG is validated against the Security Object Document (SOD):

interface DGInfoItem {
  Num: number; // DG number (1-16)
  OnChip: boolean; // Present on chip
  Read: boolean; // Successfully read
  SodHash: string; // Expected hash from SOD
  ReadHash: string; // Calculated hash
  Match: boolean; // Integrity check result
}

Certificate Chains

The chip’s authenticity is verified through X.509 certificate chains:

interface CertChainInfo {
  Raw: string; // Raw certificate data (base64)
  Info: X509OutputInfo; // Parsed certificate details
}

interface X509OutputInfo {
  Version: string;
  Serial: string;
  Issuer: string; // Who issued the certificate
  Subject: string; // Certificate owner
  NotBefore: string; // Valid from date
  NotAfter: string; // Valid until date
  SignatureAlgorithm: string;
  PublicKeyAlgorithm: string;
  Feature: string;
}

Two certificate chains are available:

  • CardSecCertChain: From the Card Security file
  • SodCertChain: From the Security Object Document

Extracted Data

Data Items

Structured information extracted from the chip:

interface DataItem {
  Dg: number; // Source Data Group
  Type: DataItemType; // int/string/bool/bytes
  Cat: DataItemCategory; // holder/document/vehicle/etc.
  Name: string; // Field name
  Value: string; // String representation
  Raw: string; // Raw bytes (base64)
}

Categories organize data by type:

  • Holder: Personal information (name, DOB, etc.)
  • Document: Document details (number, expiry, etc.)
  • Vehicle: Vehicle registration data
  • License: Driver’s license information
  • Other/Raw: Miscellaneous data

Image Items

Biometric images stored on the chip:

interface ImageItem {
  Dg: number; // Source Data Group
  Kind: ImageItemKind; // Face/Signature/Finger/Iris
  Type: LDSImageType; // JPEG/JPEG2000/WSQ
  Name: string; // Descriptive name
  Raw: string; // Image data (base64)
}

Image Formats:

  • JPEG/JPEG2000: Used for facial photos and signatures
  • WSQ (Wavelet Scalar Quantization): Fingerprint compression standard

Special Files

The chip contains several special files with metadata:

interface SpecialFilesRead {
  CardAccess: boolean; // PACE configuration
  CardSecurity: boolean; // Chip auth certificates
  COM: boolean; // List of available DGs
  SOD: boolean; // Security Object Document
  DIR: boolean; // Directory file
  AtrInfo: boolean; // Answer To Reset info
  CVCA: boolean; // Certificate authority
}

Processed Output

Identrix normalizes data from both MRZ and NFC into a standardized format.

Processed Data Items

interface ProcessedOutputItem {
  Key: string; // Standardized key
  SourceKey: string; // Original field name
  Value: string; // Normalized value
  Category: ProcessedOutputItemCategory; // Data category
  Type: ProcessedOutputItemType; // Data type
}

Data Categories

enum ProcessedOutputItemCategory {
  TC_HOLDER = "holder", // Person information
  TC_DOC = "document", // Document metadata
  TC_VEHICLE = "vehicle", // Vehicle data
  TC_GENERAL = "general", // General information
  TC_OTHER = "other", // Uncategorized
  TC_LICENSE = "license", // License info
  TC_LICENSE_CAT = "licensecat", // License categories
  TC_DISPLAY = "display", // Display-formatted
  TC_CUSTOM = "custom", // Application-specific
}

Data Types

enum ProcessedOutputItemType {
  TTUnknown = 0,
  TTInt = 1, // Integer values
  TTString = 2, // Text
  TTBytes = 3, // Binary data
  TTBool = 4, // Boolean
  TTDate = 5, // Date values
}

Validation Checks

Identrix can perform various validation checks on the processed data.

Check Results

interface ProcessedCheckItem {
  Id: string; // Unique identifier
  Name: string; // Human-readable name
  Desc: string; // What was checked
  Reason: string; // Result explanation
  Ok: boolean; // Simple pass/fail
  State: ProcessedCheckItemState; // Detailed state
}

Check States

enum ProcessedCheckItemState {
  PCI_Unknown = 0, // Unknown state
  PCI_Success = 1, // Passed
  PCI_Failed = 2, // Failed
  PCI_Warning = 3, // Passed with issues
  PCI_Not_PERFORMED = 4, // Not executed
}

Check Summary

interface ProcessedCheckOutputInfo {
  Checks: ProcessedChecks; // Individual results
  OverallState: ProcessedCheckItemState; // Summary state
}

Common checks include:

  • Document expiry validation
  • Check digit verification
  • Age requirement validation
  • Data consistency between MRZ and NFC
  • Certificate validity
  • Digital signature verification

Common Use Cases

1. Basic MRZ Scanning

For applications that only need to read the MRZ:

const result: ScanResult = await scanDocument(image);
const mrz = result.Mrz;

// Access parsed values
const docNumber = mrz.Values["DocumentNumber"];
const name = mrz.Values["Name"];
const dob = mrz.Values["DateOfBirth"];

// Check if data is valid
const isValid = mrz.CheckDigits.every((cd) => cd.IsValid);

2. Full Document Verification

For security-critical applications that need chip authentication:

const result: ScanResult = await scanDocument(image, { readNfc: true });

// Check chip authentication
const authPassed =
  result.Nfc?.AuthStatus.PassiveAuthentication.AuthState ===
  AuthStateType.AuthStatePasses;

// Verify data integrity
const allDGsValid = result.Nfc?.DGInfos.every((dg) => dg.Match) ?? false;

// Use processed output for normalized data
const holderData = Object.values(result.ProcessedOutput ?? {}).filter(
  (item) => item.Category === ProcessedOutputItemCategory.TC_HOLDER
);

3. Biometric Extraction

For applications needing facial photos or fingerprints:

const result: ScanResult = await scanDocument(image, { readNfc: true });

// Get facial photo
const faceImage = result.Nfc?.imageitems?.find(
  (img) => img.Kind === ImageItemKind.Face
);

if (faceImage) {
  const imageData = atob(faceImage.Raw); // Decode base64
  // Display or process the image
}

4. License Category Verification

For driver’s license validation:

const result: ScanResult = await scanDocument(image);

// Get license categories from processed output
const licenseCategories = Object.values(result.ProcessedOutput ?? {}).filter(
  (item) => item.Category === ProcessedOutputItemCategory.TC_LICENSE_CAT
);

// Check if holder can drive a specific vehicle type
const canDriveTruck = licenseCategories.some(
  (cat) => cat.Value.includes("C") || cat.Value.includes("CE")
);

Error Handling

Invalid Characters

If OCR fails to read certain characters:

interface InvalidChar {
  Char: string; // The problematic character
  Line: number; // MRZ line number
  Offset: number; // Position in line
}

Check MrzData.InvalidChars to identify reading issues.

NFC Errors

If chip reading fails:

if (result.Nfc?.Error) {
  console.error("NFC reading failed:", result.Nfc.Error);
  // Fall back to MRZ-only data
}

Failed Checks

Review validation failures:

const failedChecks = result.ProcessedChecks?.Checks.filter(
  (check) => check.State === ProcessedCheckItemState.PCI_Failed
);

failedChecks?.forEach((check) => {
  console.warn(`${check.Name}: ${check.Reason}`);
});

Best Practices

1. Always Validate Check Digits

const allCheckDigitsValid = result.Mrz.CheckDigits.every((cd) => cd.IsValid);
if (!allCheckDigitsValid) {
  // Data may be corrupted or misread
}

2. Verify Document Expiry

const expiryDate = result.ProcessedOutput?.ExpiryDate?.Value;
const isExpired = new Date(expiryDate) < new Date();

3. Use Processed Output for Display

The ProcessedOutput provides normalized, human-readable data:

// Instead of parsing raw MRZ dates (YYMMDD)
const rawDate = result.Mrz.Values["DateOfBirth"]; // "900115"

// Use processed date
const displayDate = result.ProcessedOutput?.DateOfBirth?.Value; // "1990-01-15"

4. Check Authentication for High Security

For applications requiring strong security:

const isAuthentic =
  result.Nfc?.AuthStatus.PassiveAuthentication.AuthState ===
    AuthStateType.AuthStatePasses &&
  result.Nfc?.DGInfos.every((dg) => dg.Match) &&
  result.ProcessedChecks?.OverallState === ProcessedCheckItemState.PCI_Success;

5. Handle Optional Data Gracefully

Not all documents contain all data:

// Use optional chaining and nullish coalescing
const middleName = result.ProcessedOutput?.MiddleName?.Value ?? "N/A";
const fingerprints =
  result.Nfc?.imageitems?.filter((img) => img.Kind === ImageItemKind.Finger) ??
  [];

Utility Types

StringMap

A simple key-value string mapping shared throughout the result types:

type StringMap = { [key: string]: string };

Type Arrays

Several types are exported as arrays for convenience:

type MrzPartList = MrzPart[];
type MrzCheckDigitList = MrzCheckDigit[];
type CertChain = CertChainInfo[];
type CheckInfoList = CheckInfoType[];
type ProcessedChecks = ProcessedCheckItem[];

Supported Document Types

Identrix recognizes various document formats:

Travel Documents

  • Passports (TD3)
  • ID Cards (TD1, TD2)
  • Visas

Driver’s Licenses

  • EU Driver’s Licenses (multiple countries)
  • Swiss Driver’s Licenses
  • Country-specific formats

Vehicle Documents

  • Vehicle registrations (multiple countries)
  • Certificate of registration

Specialized Documents

  • French National ID Cards
  • Australian Visas
  • And more…

See the MRZType enum for the complete list of supported document types.