ValidatedMRZ Class Reference

Description

Class encapsulating validated data read from a machine-readable zone (MRZ)

This class parses and validates data read from an MRZ, and guarantees that any object of this type contains data that is fully conformant with the data formats laid out in ICAO 9303. Refer to MRZ_Format for the list of supported formats and brief details of each one.

Objects of this class are constructed from MRZ_Data objects, which encapsulate raw and unvalidated MRZ data. The constructor determines the format of the MRZ and performs full validation, checking the validity of each field and verifying each check digit against the associated source data.

Invariant

All fields are fully valid to the full extent defined by ICAO 9303 for the format in question. Successful construction also strongly implies (although does not 100% guarantee) that the MRZ reader correctly identified all characters in the MRZ.

Thread safety: This class is immutable, and therefore fully thread-safe.

Public Member Functions
	ValidatedMRZ (@NonNull MRZ_Data rawData)
	Construction - takes raw MRZ data and attempts to validate it. More...
String	dateOfBirth ()
	Obtain the bearer's date of birth field for the MRZ. More...
String	documentCode ()
	Obtain the document code for the MRZ. More...
String	documentNumber (boolean convertFiller)
	Obtain the document number field for the MRZ. More...
String	expiryDate ()
	Obtain the expiry date field for the MRZ. More...
MRZ_Format	format ()
	Query the format of the MRZ. More...
String	gender ()
	Obtain the bearer's gender field for the MRZ. More...
String	issuerCode ()
	Obtain the issuing state or organisation code for the MRZ. More...
String	issuerName ()
	Obtain the issuing state or organisation name for the MRZ. More...
String	nationCode ()
	Obtain the bearer's nation code field for the MRZ. More...
String	nationName ()
	Obtain the bearer's nation name for the MRZ. More...
String	optionalData ()
	Obtain the optional data field for the MRZ, if present. More...
String	primaryName (boolean convertFiller)
	Obtain the primary name field for the MRZ. More...
String	secondaryName (boolean convertFiller)
	Obtain the secondary name field for the MRZ. More...

Static Public Member Functions
static String	issuerName (@NonNull String code)
	Obtain the issuer string for a given issuer code. More...

Static Public Attributes
static final char	Filler
	Filler/delimiter character ('<') defined by ICAO 9303.

Constructor & Destructor Documentation

ValidatedMRZ()

ValidatedMRZ

(

@NonNull MRZ_Data

rawData

)

Construction - takes raw MRZ data and attempts to validate it.

Successful construction implies that all validation checks passed successfully for the format in question.

Parameters

rawData

Data received from an MRZ scan

Exceptions

IllegalArgumentException

if any of the validation checks failed (e.g. check digit mismatch)

Member Function Documentation

dateOfBirth()

String dateOfBirth

(

)

Obtain the bearer's date of birth field for the MRZ.

The MRZ format encodes dates of birth as six-digit strings:

• The first two digits are the year, modulo 100 - e.g. 1942 is encoded as "42"
• The next two digits are the month number, range 1-12 - e.g. July is encoded as "07"
• The final two digits are the day number, range 1-31 - e.g. 2nd is encoded as "02"

If any of the fields are unknown then they may be replaced by Filler characters.

Returns

Date string (6 chars in length)

documentCode()

String documentCode

(

)

Obtain the document code for the MRZ.

The document code designates the type of MRZ and, if valid, is either one or two characters in length. It occupies the first two characters of line 1 in all MRZ types.

The first letter of the code is specified as follows:

• P - passport (type TD3)
• A, C or I - official travel documents (types TD1 or TD2)
• V - visa (type MRV-A or MRV-B)

The second letter of the code is optional; if omitted (i.e. replaced by a Filler in the MRZ text) then it will not be included in the output of this function. If present, it must conform to the following:

• Character must be from the uppercase alphabet
• If first letter is A, C or I, then second letter must not be V

The second letter of the code is at the discretion of the issuing organisation, and may be omitted (i.e. replaced by a Filler in the MRZ text).

Returns

Document code (1-2 chars in length)

documentNumber()

String documentNumber

(

boolean

convertFiller

)

Obtain the document number field for the MRZ.

This field encodes a passport number, visa number, or other document number of up to nine digits. Typically it is fully numeric, but alphabetic characters and the Filler character are permitted.

Parameters

convertFiller

If true (recommended), any Filler characters in the field are converted to spaces in the output of this function; if false, they are left as-is

Returns

Document number (up to 9 characters in length)

expiryDate()

String expiryDate

(

)

Obtain the expiry date field for the MRZ.

The MRZ format encodes dates of birth as six-digit strings:

• The first two digits are the year, modulo 100 - e.g. 1942 is encoded as "42"
• The next two digits are the month number, range 1-12 - e.g. July is encoded as "07"
• The final two digits are the day number, range 1-31 - e.g. 2nd is encoded as "02"

If any of the fields are unknown then they may be replaced by Filler characters.

Returns

Date string (6 chars in length)

format()

MRZ_Format format

(

)

Query the format of the MRZ.

Returns

MRZ format, guaranteed to be one of the five defined in ICAO 9303 (i.e. not UNKNOWN)

gender()

String gender

(

)

Obtain the bearer's gender field for the MRZ.

Three values are considered valid for this field - 'F' for female, 'M' for male, and Filler for unspecified gender.

Returns

Gender string (1 character in length)

issuerCode()

String issuerCode

(

)

Obtain the issuing state or organisation code for the MRZ.

The issuing state or organisation is encoded as a three-letter code in the MRZ according to the rules specified in ICAO 9303 part 3 section 5. It occupies characters 3 to 5 of line 1 in all MRZ types.

No validity checks are performed on this code beyond ensuring that either it consists of 1-3 uppercase characters followed by 0-2 Filler characters, with an overall length of 3. That is, even if the code does not match a value defined by ICAO 9303, it will still be accepted if it meets that basic format.

Returns

Issuer code (3 chars in length) if this MRZ is of one of the known formats and contains a code which meets basic formatting checks, otherwise an empty string. Any trailing Filler characters will be retained, e.g. code for Germany will be "D<<".

See also

issuerString() for a human-readable equivalent

issuerName() [1/2]

String issuerName

(

)

Obtain the issuing state or organisation name for the MRZ.

This is the equivalent to issuerCode(), except a human-readable string is returned rather than a three-digit code - e.g. if issuerCode() would return "AUS", this function would return "Australia".

If there is no valid code, or the code provided is not listed in ICAO 9303 part 3 section 5, then an empty string will be returned.

Returns

Human-readable name of this MRZ's issuer if known and valid, otherwise an empty string

issuerName() [2/2]

static String issuerName ( @NonNull String  code )

static

Obtain the issuer string for a given issuer code.

This function returns the name of an issuer given by the supplied code. The names and codes are defined in ICAO 9303 part 3 section 5.

It may also be used to generate strings for nationality codes, as those are a subset of the issuer codes.

Parameters

code	Issuer code; must be a three-character uppercase string matching one of the values defined by ICAO 9303 part 3 section 5

Returns

Human-readable name of given issuer code if known and valid, otherwise the string "Unknown"

nationCode()

String nationCode

(

)

Obtain the bearer's nation code field for the MRZ.

The bearer's nationality is encoded as a three-letter code in the MRZ according to the rules specified in ICAO 9303 part 3 section 5.

No validity checks are performed on this code beyond ensuring that either it consists of 1-3 uppercase characters followed by 0-2 Filler characters, with an overall length of 3. That is, even if the code does not match a value defined by ICAO 9303, it will still be accepted if it meets that basic format.

Returns

Nation code (3 chars in length). Any trailing Filler characters will be retained, e.g. code for Germany will be "D<<".

See also

nationName() for a human-readable equivalent, or issuerString(const string&) for a function which converts these codes (which are a subset of the issuer codes) to human-readable strings.

nationName()

String nationName

(

)

Obtain the bearer's nation name for the MRZ.

This is the equivalent to NationCode(), except a human-readable string is returned rather than a three-digit code - e.g. if NationCode() would return "AUS", this function would return "Australia".

If there is no valid code, or the code provided is not listed in ICAO 9303 part 3 section 5, then an empty string will be returned.

Returns

Human-readable name of this MRZ bearer's nation

optionalData()

String optionalData

(

)

Obtain the optional data field for the MRZ, if present.

On passports (TD3 format) this is typically used to store a personal number given to the bearer by the issuing state or organisation. On all formats it may be used to store other optional data at the discretion of this organisation.

There are no restrictions on the format of this data aside from the basic character set requirements of all MRZ data. Consequently, it is not validated beyond those basic checks.

On the TD1 format the content of this field is split across two separate lines; the output of this function takes the field contents from the first line (excluding trailing check digit) and appends the field contents from the second line to it. Other formats hold the entirety of this field in a single location.

Returns

Optional data field (variable length depending on format)

primaryName()

String primaryName

(

boolean

convertFiller

)

Obtain the primary name field for the MRZ.

The primary name is typically a bearer's surname (family name), and forms part of the name field along with the secondary name field (see secondaryName()).

The primary name field must start with an uppercase alphabetic character. It may then be followed by any number of additional characters which may be either uppercase alphabetic characters or Filler characters, subject to the restriction that no two Filler characters may be directly adjacent.

Parameters

convertFiller

If true (recommended), any Filler characters in the name are converted to spaces in the output of this function; if false, they are left as-is

Returns

Primary name (1-39 chars in length)

secondaryName()

String secondaryName

(

boolean

convertFiller

)

Obtain the secondary name field for the MRZ.

The secondary name typically contains a bearer's given name(s), and forms part of the name field along with the primary name field (see primaryName()).

The secondary name field may be an empty string, implying the user has only one name (which is primary). If non-empty, it must follow the same rules as the primary name.

Parameters

convertFiller

If true (recommended), any Filler characters in the name are converted to spaces in the output of this function; if false, they are left as-is

Returns

Secondary name (0-36 chars in length)