> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.instabase.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server.

# Validating packets

> Ensure data quality and consistency across documents in a packet with cross-class validation rules.

Enterprise

Validation rules for [cross-class fields](/automate/packet-schema) ensure data quality and consistency across documents within a packet. While class-level validation rules verify individual field results, cross-class validation rules verify relationships between fields, selection logic, and data consistency.

## Understanding cross-class validation rules

Cross-class validation rules focus on relationships and consistency across documents.

Cross-class validation rules flag results where input fields failed validation or were inconsistent across the packet.

Each cross-class validation rule must be associated with a specific cross-class field. This association determines where validation failures appear in human review and run results, making it clear which field needs attention. For referenced field rules, the associated field is the one being validated. For custom validation functions, the associated field is where failures display, though your custom function logic can validate any aspect of the packet.

## Creating cross-class validation rules

Create cross-class validation rules to flag questionable results for human review.

1. From the **Cross-class** tab, select **Validations**.

2. Click **Add cross-class rule**.

3. Select a validation rule type.

4. Select the cross-class field that the validation rule applies to, and click **Save**.

> **Tip**
>
> Cross-class validation results aren't automatically recalculated when you modify input field validations. To update cross-class validation results, refresh the page.

## Cross-class validation rule types

Choose the validation rule type that matches how you want to validate data across classes.

* **Validate selected field** -- Checks that the field selected by ranking logic is valid. Applies only to ranked, not derived, fields. Use this rule type when your selection criteria is based on confidence score rather than validation status, ensuring that the final selected value meets quality standards even if it was chosen based on confidence rather than validity.
* **Validate all input fields** -- Checks that every input field used to calculate the cross-class field is valid. Use this rule type when you want to verify packet integrity and ensure all documents in the packet contain valid data.
* **Require matching fields** -- Checks that all input field results match each other exactly. Use this rule type to detect inconsistencies across documents that might indicate data entry errors, fraud, or incorrectly grouped documents.
* **Validation function** -- Uses a custom Python function to validate cross-class field results. Use this rule type for complex validation logic that can't be achieved with quick validation rules. For more details, see [Cross-class validation function](#cross-class-validation-function).

### Cross-class validation function

For advanced validation requirements involving complex business logic, external data verification, or mission-critical results, create a custom cross-class validation function in Python.

When creating a validation function, you first select which cross-class field the rule applies to. This determines where validation failures are displayed in human review and run results. Your custom function logic can validate any aspect of the packet, not just the selected field. To use other fields in your custom function, click **+ Add argument** and select the field from the dropdown. A `'class_fields'` argument is added to your custom function, which you can use to access the field.

For example, you might use a validation function to verify that values across multiple documents fall within acceptable ranges:

```python
def validate_income_consistency(applicant_income, context, class_fields):
    """
    Validates that income values across documents are reasonably consistent.
    Checks that the applicant income from the cross-class field falls within
    an acceptable variance when compared to supporting documents.
    """
    # Skip validation if input is empty
    if not applicant_income:
        return "Income value is missing"

    try:
        # Convert income to float for comparison
        income_value = float(applicant_income.replace(',', '').replace('$', ''))

        # Collect all income values from input documents
        income_values = []
        for class_name, fields in class_fields.items():
            if 'income' in fields:
                field_value = fields['income'].get('value')
                if field_value:
                    clean_value = float(field_value.replace(',', '').replace('$', ''))
                    income_values.append(clean_value)

        # Check if values are within 10% variance
        if income_values:
            max_income = max(income_values)
            min_income = min(income_values)
            variance = (max_income - min_income) / max_income

            if variance > 0.10:
                return f"Income values vary by more than 10% across documents"

        # Validation passed
        return None

    except (ValueError, AttributeError):
        return f"Invalid income format: {applicant_income}"
```

Cross-class validation functions accept these parameters:

| Parameter                  | Required? | Description                                                                                                                                                                          |
| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `<field-name>`             | Required  | Value of the cross-class field that the function is associated with.                                                                                                                 |
| `context`                  | Required  | Stores metadata about the packet.                                                                                                                                                    |
| `context['class_fields']`  | Optional  | Access to input field values organized by class name and field name. Use `context['class_fields']['Class Name']['Field Name']['value']` to retrieve values.                          |
| `context['document_text']` | Optional  | Retrieves the entire text of all documents in the packet.                                                                                                                            |
| `context['file_path']`     | Optional  | Retrieves the path to the uploaded packet.                                                                                                                                           |
| `keys`                     | Optional  | Access custom variables and [organization secrets](/admin/secret-management). Use `keys['custom']['<key-name>']` for custom keys and `keys['secret']['<key-name>']` for secret keys. |
| `<additional-field-name>`  | Optional  | Click **Add argument** to select additional cross-class fields to use in the function.                                                                                               |

Validation functions must return `None` if the validation rule passes, and an error string if the validation rule fails. For table and list fields, you can use [cell-level validation](/automate/validating-documents#cell-level-validation) to flag specific cell ranges as invalid.

For additional guidance about custom functions, see [Writing custom functions](/automate/custom-functions).

## Best practices for packet validation

Choose validation rules that align with your quality requirements and use case.

| Validation rule type          | Best for                        | Notes                                                                                                                                                                                                                    |
| ----------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Validate selected field**   | Data quality assurance          | Ensures the final output meets quality standards. Particularly useful when selection logic prioritizes confidence scores over validation status, catching situations where high-confidence results are actually invalid. |
| **Validate all input fields** | Packet integrity verification   | Verifies that the entire packet contains high-quality data, not just the field that was selected. Helps identify incomplete documents, poor quality scans, or missing information across the packet.                     |
| **Require matching fields**   | Consistency and fraud detection | Detects inconsistencies that might signal fraud, data entry errors, or incorrect document grouping. Critical for compliance-focused use cases where document consistency is a key verification requirement.              |
| **Validation function**       | Complex business logic          | Enables external data verification, multi-step business rules, or calculations that can't be achieved with quick validation rules. Allows domain-specific logic and integration with external systems.                   |

Consider the cost of sending invalid results downstream versus the cost of human review when configuring validation rules. Stricter validation rules like **Validate all input fields** or **Require matching fields** catch more potential issues but send more packets to review. Less strict rules like **Validate selected field** minimize review burden but might miss edge cases. Choose validation strategies that align with your risk tolerance and review capacity.