NID Field Definitions

Every field extracted from a a Vietnamese NID — National Identity Card, known locally as Căn cước công dân (CCCD) or Thẻ căn cước (TCC) through OCR, QR parsing and MRZ parsing, with its canonical format, source, validation rules and normalization requirements.

Data Model

The extraction pipeline aggregates three independent sources into one unified dataset:

What	Description
OCR	Optical character recognition of the printed card surface.
QR	The official pipe-delimited QR payload encoded on the card.
MRZ	The ICAO 9303-compliant machine-readable zone.
Image metadata	Card bounding box and preprocessing references produced during extraction.

{
  "code": 0,
  "success": true,
  "data": {
    "image1": {},
    "image2": {},
    "status": "success",
    "request_id": "uuid",
    "card_information": []
  }
}

Identity Fields

Field	Type	Description
id	string	The 12-digit Citizen Identification Number (Mã số định danh cá nhân). Format ^[0-9]{12}$. Source: OCR, QR, MRZ. Unique per citizen; encodes province, gender-century marker and a random sequence. MRZ checksum is optional.
id_1	string	Legacy 9-digit CMND number. Format ^[0-9]{9}$. Source: QR only. Optional — present only if the citizen previously held an old ID card.
id_last_9	string	Last 9 digits of the full NID number. Format ^[0-9]{9}$. Source: MRZ, which requires the truncated form.
gender	string	Nam (male) or Nữ (female). Source: OCR, QR, MRZ. Map MRZ M → Nam and F → Nữ.
dob	string	Date of birth. DD/MM/YYYY from OCR/MRZ, DDMMYYYY from QR. Must produce a valid ISO date; transform to canonical YYYY-MM-DD.
nationality	string	Fixed value Việt Nam. Source: OCR (front).

Name fields

Field	Type	Description
name	string	Full legal name. Unicode. Source: OCR, QR, MRZ. Uppercase from OCR, Title Case from QR/MRZ — normalize to Title Case.
last_name	string	Family name, e.g. NGUYỄN. Unicode. Source: OCR/MRZ. The first component.
middle_name	string	Middle name, e.g. VĂN. Unicode. Source: OCR/MRZ. Zero or more components.
first_name	string	Given name, e.g. A. Unicode. Source: OCR/MRZ. The last component.

Name normalization is required: remove extra spaces, convert to NFC Unicode, and standardize casing to your product rules.

Address Fields

Vietnamese addresses are hierarchical, from the province down to the residential group:

Level 1 → Level 2 → Level 3 → Level 4
Province → District → Ward → Hamlet/Group

Field	Type	Description
address	string	Full printed residence address. Free text. Source: OCR. Used as a fallback when the hierarchical components cannot be reconstructed.
address_level_1_(city)	string	Province or centrally-managed city, e.g. TP. Hồ Chí Minh.
address_level_1_(city)_code	string	Provincial administrative code, e.g. 79.
address_level_2_(district)	string	District-level administrative area, e.g. Quận 1.
address_level_2_(district)_code	string	District administrative code, e.g. 760.
address_level_3_(ward)	string	Ward, commune or township, e.g. Phường Bến Nghé.
address_level_3_(ward)_code	string	Ward administrative code, e.g. 26740.
address_level_4	string	Smallest administrative unit — hamlet or residential group, e.g. Tổ 1.
native_place	string	Quê quán — the citizen's registered birthplace, which is not necessarily their current residence. Usually <Ward/Commune>, <District>, <Province>. Source: OCR or QR.

Card Issuance Fields

Field	Type	Description
issue_date	string	Date the card was issued. DD/MM/YYYY from OCR, DDMMYYYY from QR. Normalize to ISO YYYY-MM-DD.
expiry_date	string	Date the card expires — 20 years from issuance for ages 14–59, no expiration above 60. Format DD/MM/YYYY. Must be later than the issue date.
issue_place	string	Authority that issued the card, e.g. CỤC TRƯỞNG CỤC CẢNH SÁT QUẢN LÝ HÀNH CHÍNH VỀ TRẬT TỰ XÃ HỘI.
issue_place_code	string	Encoded issuer ID. Format ^[0-9]{4}$, e.g. 7740 for the national police administration.
signature	string	Signature of the issuing officer, on the back of the card.

Card Metadata Fields

Field	Type	Description
card_type	string	Card version/type used for OCR processing, e.g. vn.cccd_new.
card_label	string	Front or back card type used by the OCR engine, e.g. vn.cccd_new.front, vn.cccd_new.back.

QR Code Fields

The official QR payload is a pipe-delimited string:

<NID>|<Legacy_ID>|<Name>|<DOB>|<Gender>|<Native_Place>|<Issue_Date>

Example:

001xxxxxxxxx|xxxxxxxxx|Nguyễn Văn A|12121990|Nam|Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh|01012021

Field	Type	Description
id	string	Position 1 — NID number, 12 digits.
id_1	string	Position 2 — legacy ID number, 9 digits. Optional.
name	string	Position 3 — full name. Unicode.
dob	string	Position 4 — date of birth, DDMMYYYY.
gender	string	Position 5 — Nam or Nữ.
native_place	string	Position 6 — place of origin. Free text.
issue_date	string	Position 7 — issue date, DDMMYYYY.

MRZ Fields

The MRZ follows the ICAO 9303 standard for ID cards:

IDVNMxxxxxxxxxx001xxxxxxxxx<<x9012123M3012121VNM<<<<<<<<<<<xNGUYEN<<VAN<A<<<<<<<<<<<<<<<<<

Field	Type	Description
document_type	string	Document type — ID.
country_code	string	Issuing country — VNM.
id	string	NID number.
id_last_9	string	Last nine digits of the NID number.
dob	string	Date of birth, YYMMDD.
gender	string	M or F.
expiry_date	string	Expiry date, YYMMDD.
name	string	Name in LAST<<MIDDLE<FIRST form.

Image Metadata

Field	Type	Description
card_box	object	Bounding box of the card within the input image, used for perspective correction, cropping and alignment.
transformed_image_id	string	Internal reference ID for the processed and normalized image.

{
  "top_left": { "x": 44, "y": 309 },
  "top_right": { "x": 734, "y": 309 },
  "bottom_left": { "x": 44, "y": 758 },
  "bottom_right": { "x": 734, "y": 758 }
}

Confidence Metrics

Field	Type	Description
confidence_score	float	Probability from 0 to 1 that OCR read this field correctly.
confidence_verdict	string	Optional label — SURE for high certainty, empty for a normal reading.
digit_confidence_scores	float[]	Per-digit probabilities, used for numeric fields such as ID codes.

Minimum recommended acceptance thresholds:

Field	Type	Description
Critical fields	id, name, dob	>= 0.90
Secondary fields	address, signature	>= 0.80

Field Priority and Merge Rules

When the same field arrives from more than one source, prefer them in this order — most to least reliable:

1. QR — encoded at issuance, not subject to recognition error.
2. MRZ — machine-readable and checksum-protected.
3. OCR — recognition of the printed surface, the most error-prone.

if QR.dob is valid: use QR
else if MRZ.dob is valid: use MRZ
else use OCR

Address reconstruction follows the same fallback logic:

address = join(level_4, level_3, level_2, level_1)
if OCR.address exists and structured parts fail: fallback to OCR.address

Error Handling Requirements

Field	Type	Description
CARD_NOT_DETECTED	string	Card not found in the image. Behavior: request a rescan.
QR_PARSE_ERROR	string	The QR code could not be parsed. Behavior: continue with OCR/MRZ.
INCOMPLETE_DATA	string	A critical field (id, name, dob) is missing. Behavior: fail the extraction.
LOW_CONFIDENCE	string	A field scored below its threshold. Behavior: return a warning label.

Output Normalization Rules

• All dates → YYYY-MM-DD
• Names → Title Case
• Address components → Title Case
• Unicode normalization → NFC
• Remove duplicate spaces and punctuation inconsistencies

Recommended Database Schema

Field	Type	Description
id	VARCHAR(12)	Primary key — the NID number.
id_legacy	VARCHAR(9)	Legacy CMND number. Nullable.
full_name	TEXT	Full legal name.
last_name	TEXT	Family name.
middle_name	TEXT	Middle name.
first_name	TEXT	Given name.
gender	ENUM('Male','Female')	Normalized gender.
dob	DATE	Date of birth.
nationality	TEXT	Nationality.
native_place	TEXT	Registered birthplace.
address	TEXT	Fallback address string.
ward	TEXT	Level 3 ward name.
ward_code	VARCHAR(10)	Level 3 administrative code.
district	TEXT	Level 2 district name.
district_code	VARCHAR(10)	Level 2 administrative code.
province	TEXT	Level 1 province name.
province_code	VARCHAR(10)	Level 1 administrative code.
issue_date	DATE	Card issue date.
expiry_date	DATE	Card expiry date.
issue_place	TEXT	Issuing authority.
issue_place_code	VARCHAR(10)	Issuing authority code.
signature	TEXT	Issuing officer's signature.
confidence_overall	FLOAT	Aggregate extraction confidence.

WARNING

Every column above is personal data under Vietnamese data protection rules, and face_image from the chip is biometric. Encrypt at rest, restrict read access to callers with a business reason, and apply a retention policy — do not keep identity records longer than the relationship requires.

Suggested Additional Validations

• Look up province, district and ward codes against the Vietnam administrative database.
• Check date consistency — date of birth must be on or before the issue date.
• Cross-check gender between the MRZ and the QR.

Next Steps

• Read NFC — the API that returns these fields from the chip
• Overview — the full transaction lifecycle