Identità does not have one single validation gate. It asks several different questions as an application moves from flow configuration to officer review:

1. Is the flow configuration valid?
2. Which documents does this application need?
3. Could the document values be extracted and represented correctly?
4. Does each document satisfy the applicable SOP rules?
5. Do values agree across documents?
6. What action should the findings recommend?

Keeping these questions separate is important. It lets the system preserve what a document actually says, explain why it is a problem, and give an officer the right review action.

Validation at a glance¶

The Run Detail page brings the outputs of all these layers together. A finding at one layer does not silently replace the results from another.

1. Configuration validation¶

Validation begins before a run exists.

Document fields¶

Each document field must use a supported type expression. Both field_type and an optional validation_field_type are checked when the field definition is saved. The field-type registry lists the supported names.

Flow conditions¶

Step conditions and profile-variable collection conditions must be valid rule expressions. The flow builder also limits operators according to the profile variable type. For example, a Yes/No variable supports:

• is yes;
• is no; and
• is answered.

It cannot be saved with a text equality condition such as needs_accommodation is "Yes". The stored profile value is a Boolean, not the word shown in the selector.

Conditions can combine rules with ALL, ANY, and negation. A condition is evaluated as true, false, or unknown. Unknown means that a referenced profile answer is not available yet.

Imported flow definitions¶

The supplied flow definition is validated as a complete graph before import. This catches unsupported actions and operators, duplicate requirements or check keys, unknown profile variables, invalid dependencies, and references to undeclared requirements.

Configuration validation prevents a broken rule from becoming a mysterious run-time result. It does not decide whether an applicant passes vetting.

2. Profile and manifest resolution¶

A Profile Variable is an application fact. It may be supplied by an operator, derived from a document, or overridden by an officer.

The effective profile is used to resolve the manifest:

• a true Required when condition includes the Step;
• a false condition makes it Not required;
• an unknown condition means the system cannot decide yet;
• an unconditional core Step is required; and
• a true Defer when condition allows a required document to arrive later.

This is completeness logic, not document-content validation. For example, needs_accommodation is yes answers whether an accommodation document belongs in the application. It does not prove that an uploaded lease is valid.

See Manifest Preview for testing conditions before creating a run, and Requirements for the manifest resolved from a real run.

3. Extraction and field validation¶

Once a file is classified, Identità builds a Pydantic model for its configured document fields.

Extraction model¶

The extraction model normally uses each field's field_type. Fields are made optional for AI extraction so the model can leave an unreadable or absent value empty instead of inventing one.

Field descriptions are part of that model. They tell the extraction service what to look for, such as a QR code rather than nearby printed text, or the currency and bounds of a salary band.

Some document types register an authoritative Pydantic model in code. When one exists, Identità uses it instead of generating a model from database metadata.

Validation model¶

After extraction, Identità validates the saved dictionary again. This model:

• makes fields marked as required mandatory;
• uses validation_field_type when one is configured;
• otherwise uses field_type; and
• omits extraction-only notes.

This is why a field can use a simple editor type but a more precise validator:

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

The first type controls the extracted value and UI shape. The second gives strict post-extraction validation instructions. See Field type and validation field type.

What happens when field validation fails¶

Pydantic errors are translated into readable messages, for example:

Overall Medical Coverage Limit must be a valid number. Found: "unknown".

The messages are stored on the run document alongside the extracted data. The file is not treated as a pipeline crash. It may still advance through the technical Extracted and Validated statuses while its validation errors remain open.

Those errors affect the program in three visible places:

• Requirements shows the matching Step as Received · issues, not Satisfied;
• Documents shows the errors beside the file and its editable fields; and
• Next actions lists the document under Documents received with validation issues.

Each open schema error contributes a Send back finding to the system recommendation. It is corrected by fixing the extracted value, document, or field configuration. It is not resolved with the document-rule override buttons.

The document-review form runs the same validation before saving. Invalid edited data is rejected inline, with the error placed next to the relevant field.

4. Per-document validation rules¶

A FlowValidationRule is attached to a Step and tests an extracted document against a business or SOP requirement. These rules preserve the observed value even when it does not meet policy.

Supported deterministic checks include:

A field may use a dotted path, such as verification_code.valid, when a structured field contains the value being checked.

A rule may also have a profile condition, an SOP reference, reviewer instructions, and a configured failure action.

The stored result is one of:

• Pass;
• Fail;
• Needs human review; or
• Insufficient data.

An officer can review the evidence and record Confirm as passing, Confirm failure, or Not applicable, with a required reason. The computed result remains available for provenance. If reprocessing changes the computed status, the stale resolution is cleared.

These results appear under Checks → Document checks and feed the findings on Next actions.

5. Cross-document checks¶

A cross-document check compares a shared fact across two or more sources. A field set identifies either document fields or resolved Profile Variables; multiple values can be joined into one comparison value.

This preserves profile provenance. In the Single Permit flow, fields extracted from the Residence Application Form populate derived nidms_* Profile Variables. Cross-checks then use the resolved NIDMS profile as the authoritative reference. Routing facts absent from the form remain defined/set Profile Variables.

A check may also have a Run when profile condition. A false condition removes that check result for the run; for example, the residence-card number check runs for a renewal but not a first-time application.

The configured match type decides how the values are compared:

• Exact for stable identifiers and already standardised values;
• Fuzzy for names or wording with harmless variation;
• Range for dates or periods that must cover a reference;
• Signature for signature evidence;
• External system when another source must adjudicate the result; and
• specialised money comparison where either side uses a monetary field type.

For the normalisation rules, thresholds, and outcomes of each match type, see Cross-document match types.

A result can be Pass, Mismatch, Needs review, or No data. Mismatches use the check's configured failure action; undecidable and insufficient-data results flag the case for an officer.

An officer can mark a mismatch as OK, confirm it, or ignore a non-applicable check. A reason is required. Reprocessing preserves the override while the computed status stays the same and clears it when the evidence produces a different status.

See Cross-Document Checks for configuration and Checks → Cross-document checks for the officer view.

6. Recommendation and officer decision¶

After validation and cross-checking, Identità aggregates every unresolved finding. The most serious configured action wins:

1. Recommend rejection
2. Send back
3. Flag to officer
4. Proceed

Missing required Steps, document validation errors, failed document rules, cross-document mismatches, unresolved profile conflicts, and technical classification findings can all contribute.

This is a deterministic system recommendation, not the final decision. The officer reviews the evidence and records Proceed, Send back, or Reject with a reason. See System recommendation and officer decision.

Where should a new rule live?¶

Use the layer that matches the question being asked:

Example: medical coverage threshold¶

Suppose a policy states a coverage limit of EUR 50,000 while the SOP requires at least EUR 100,000.

Use a decimal or money field type to store 50000, then use a minimum_number document rule with an expected value of 100000.

This produces an explainable result:

• the factual extracted value remains EUR 50,000;
• the check Medical cover is at least EUR 100,000 fails;
• the SOP reference and expected value are visible;
• the configured failure action contributes to the recommendation; and
• an officer can review and resolve the rule with a reason.

Do not put ge=100000 on the general money field type. That would mix a policy threshold into the data shape. It could reject the truthful value, present the problem as a generic document validation error, and—if it replaces the flow rule—remove the named SOP check and its officer-resolution workflow.

If an extraction field itself carries that constraint, the AI output must also satisfy it. A truthful below-threshold value can then fail parsing or be dropped from the filtered result. Separating factual extraction from policy evaluation avoids that loss.

Corrections, reprocessing, and audit¶

When an officer corrects extracted data, changes the profile, replaces a file, or requests reprocessing, dependent results are recalculated.

• Manifest Step states are refreshed from the effective profile and evidence.
• Document validation runs again.
• Per-document and cross-document results are updated.
• Overrides whose underlying result changed are cleared.
• A previous final decision is cleared when the evidence is changed or a full reprocess is requested.
• Officer actions and changed fields are recorded in Activity.

A technical pipeline failure is different from a validation finding. Failed classification or extraction changes the run to Failed and must be corrected and reprocessed; it is not an applicant rejection.

For the complete officer-facing workflow, see the safe review sequence.