A document field has a field type. The field type tells Identità what kind of value to extract, how to validate it, and which input and output controls to show.

Field types answer whether a value is present and correctly shaped. Business or SOP decisions belong to flow validation rules instead. See How validation works for the full path from flow configuration to officer decision.

For example:

DocumentField(
    name="identity_document_number",
    field_type="MaltaIDCardNumber",
)

Use the exact, case-sensitive name shown in the registry below.

Field type and validation field type¶

Most fields need only field_type:

DocumentField(
    name="expiry_date",
    field_type="SixMonthsToFutureDate",
)

When extraction and validation need different shapes, use validation_field_type as well:

DocumentField(
    name="advertised_job_titles",
    field_type="StringList",
    validation_field_type="JobTitleList",
)

Here, StringList supplies the editor and display, while JobTitleList gives the extraction model more precise instructions.

Do not use a strict field constraint for a policy threshold that may legitimately be missed by the source document. Store the truthful value, then evaluate the threshold as a named flow validation rule. See Where should a new rule live?.

Supported field-type registry¶

Every name in this table is checked automatically against the running application. A documented name must resolve, and every supported field type must appear here.

Important specialised types¶

Recent and future dates¶

The *SincePastDate types accept a date before today and within the named calendar-month window. Their *OrToday variants also accept today.

The future-window types are inclusive at both ends:

Calendar months are used instead of a fixed number of days. This matters around months of different lengths.

MoneyAmount¶

MoneyAmount stores a single non-negative EUR amount with up to 12 digits and 2 decimal places. Its JSON value remains a plain number:

1248.50

The extractor follows these rules:

• amounts already printed in EUR are returned without conversion;
• an explicitly non-EUR amount is converted with the convert_money_to_eur tool, using a three-letter ISO 4217 source code and embedded European Central Bank rates;
• when a date clearly governs the amount, such as a statement, pay-period, policy-effective, or contract-effective date, that historical date is used;
• without a clear date, the latest rate bundled with the application is used; and
• if the source currency or rate cannot be established, the field is omitted and the reason is added to the extraction notes. An unconverted foreign amount must never be returned as EUR.

The converter uses the last known rate for a missing day such as a weekend or bank holiday. It does not substitute a rate when the requested date is outside the currency's available history. Converted values are rounded to euro cents.

The editor and output component always show a fixed EUR indicator. Manual entries are therefore also interpreted as EUR. Source currency, exchange rate, and conversion date are not persisted.

SalaryBand¶

SalaryBand keeps a printed salary range as structured data:

{
  "currency": "EUR",
  "minimum": "15000",
  "maximum": "20000"
}

• currency is a three-letter ISO 4217 code. Symbols are converted, such as € to EUR.
• minimum and maximum are decimal amounts without currency symbols or thousands separators.

The field description helps the extraction model split a printed range into these three values.

Signature¶

Signature records the signature's position:

{
  "page_number": 1,
  "x_coord": 120,
  "y_coord": 640,
  "length": 260,
  "height": 90
}

The page number starts at 1. Coordinates and dimensions use a page-normalised 0–1000 coordinate system. Width and height must be positive, and the complete box must fit on the page.

SkillsPassQRCode¶

SkillsPassQRCode stores:

{
  "url": "https://certificates.skillspass.org.mt/certificate/9277e4221f965968af52ca5bcf32cd34?format=json",
  "valid": true
}

The extraction model is told to read the URL encoded in the QR image near the bottom of the Skills Pass certificate. It must not copy a nearby printed website address.

Identità adds format=json to the URL and verifies the downloaded certificate data. Verification checks the expected Skills Pass host and certificate path, valid Blockcerts-shaped JSON, and a matching certificate identifier. The valid value records that result; it is not a cryptographic proof of the underlying blockchain claim.

Maltese identifiers¶

MRZStr is specifically TD3 passport MRZ line 2. It normalises the text and checks the ICAO check digits.

Parties and relevant people¶

Use Party for a natural person or legal entity acting as a party to a property or accommodation document. It contains the printed name, party type, identifier, optional VAT number, and whether the party is foreign. Use PartyList when the document can contain co-lessors, co-lessees, co-vendors, or co-purchasers.

RelevantPerson contains the common details used by corporate and compliance records: name, identification number, address, nationality, date of birth, and person class. Role-specific types such as Director, Shareholder, and Trustee add the fields needed for that role. Their plural forms are the corresponding collection types.

Validation-only helpers¶

These types provide precise extraction or validation instructions but do not have their own dedicated editor and output component. Pair them with a renderable field_type through validation_field_type.

Adding a field type¶

Adding a field type is a four-part change:

1. Define the type in backend/src/apps/zf_documents/field_types.py.
2. Add it to this registry.
3. Add its input component under backend/src/templates/cotton/field_types/input/.
4. Add its output component under backend/src/templates/cotton/field_types/output/.

Component filenames use the snake-case form of the type name. For example, SalaryBand uses salary_band.html in both component directories.

The input component receives field, value, errors, and the generated form-field name. The output component receives field and value. Reuse an existing component only when the value has the same shape and interaction.