---
title: Validate claim record
summary: Applies the ClaimIntake rule set to a single claim record and returns every failure it produces.
status: draft
owner: Claims Systems Team
last_reviewed: 2026-08-14
library: SAIF.Framework.Validation
reference_type: package
operation_id: OP-001
trigger: ValidationEngine.Validate called by a consuming application on claim submission
---

# Validate claim record

This is the primary entry point of the library. When an operator submits the
claim entry screen in `SAIF.Claims.Intake`, the application hands the assembled
claim record to `ValidationEngine.Validate` with the rule set name `ClaimIntake`
and a context object carrying jurisdiction, policy period, and user identity.
The engine evaluates every rule in the set without stopping at the first
failure, so the operator sees the complete list of corrections in one pass, then
records an audit row for each blocking failure. The caller uses the returned
`ValidationResult` to decide whether the claim may be persisted.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-001 |
| **Trigger** | Caller request: `ValidationEngine.Validate(record, "ClaimIntake", context)` invoked on claim submission by `SAIF.Claims.Intake`. |
| **Inputs** | Claim record, rule set name `ClaimIntake`, `IValidationContext` supplying `JurisdictionCode`, `PolicyPeriod`, and `UserId`. |
| **Outputs** | `ValidationResult` carrying `IsValid`, the ordered failure collection, and the warning collection; one `ValidationFailureAudit` row per blocking failure. |
| **Primary components** | `ValidationEngine.Validate`, `ValidationRule.Evaluate`, `ValidationResult`, `ValidationAuditRepository.RecordOutcome` |
| **Entry point** | src/SAIF.Framework.Validation/ValidationEngine.vb |

## Steps

1. Confirm the engine has completed framework startup configuration before any rule is evaluated.
   - Read `IsInitialized` on the inherited component base and, when it is `False`, run framework startup configuration.†
   - Resolve the environment name and trace listener registration from framework configuration, then mark the component initialized.†

   > **Origin**: Steps 1.1–1.2 are implemented in `Initialize component` (`SAIF.Framework.Core`) and executed on behalf of this operation.

   - On failure: `FrameworkNotInitializedException` propagates to the caller and no rule is evaluated, so results are never produced under default settings.
2. Load the `ClaimIntake` rule set, materializing and caching its ordered `ValidationRule` collection on the first request in the process.
   - If the rule set is already cached: reuse the cached collection without re-reading the XML definition.
   - On failure: `RuleSetNotFoundException` propagates and nothing is cached, so a corrected deployment succeeds on the next call.
3. Reject the request when the caller supplied no jurisdiction code and the rule set contains at least one state-scoped rule.
   - Record a blocking failure and return immediately rather than silently skipping the state-scoped rules.
4. Load the active rule definitions for the supplied jurisdiction code (SQL-004, ValidationRuleDefinition, Jurisdiction).
   - Apply each jurisdiction-specific definition to the in-memory copy of the rule collection, adjusting severity for that run only; the cached rule set is left unchanged.
   - On failure: the read is advisory, so a timeout leaves the XML-declared severities in force and adds a warning to the result.
5. Evaluate each rule in declaration order against the claim record, appending every result to the accumulating collection without short-circuiting.
   - Check that the claim number is exactly eight digits ([VAL-014](../business-rules.md#val-014-claim-number-must-be-eight-digits)).
   - Check that the date of injury is not later than the current date ([VAL-021](../business-rules.md#val-021-date-of-injury-cannot-be-in-the-future)).
   - Check that the date of injury falls within the policy period supplied by the context.
   - If a rule's severity is warning: add the result to `ValidationResult.Warnings` and leave `IsValid` unchanged.
   - If a rule's severity is blocking: add the result to `ValidationResult.Failures` and set `IsValid` to `False`.
   - On failure: an exception raised inside a single rule is captured as a blocking failure for that rule, and evaluation continues with the remaining rules.
6. Emit a trace entry summarizing the rule set name, record identifier, and failure count.
   - Format the entry with the component name and current environment, then write it to the registered framework trace listener.†

   > **Origin**: Step 6.1† is implemented in `Write trace entry` in `SAIF.Framework.Diagnostics` (retrieved via the Legends CLI RAG service) and executed on behalf of this operation.
7. Record each blocking failure for audit reporting (SQL-001, ValidationFailureAudit).
   - Write the rule set name, claim number, evaluated rule count, blocking failure count, warning count, `UserId`, and the current timestamp.
   - On failure: the insert error is traced and swallowed; validation still returns its result so an audit outage cannot block claim intake.
8. Return the assembled `ValidationResult` to the caller, which blocks persistence when `IsValid` is `False` and otherwise displays any warnings as advisory text.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Validate called on claim submission]) --> Init[Ensure framework startup configuration is complete]
	Init --> Load[Load ClaimIntake rule set]
	Load --> Jur{Jurisdiction code supplied?}
	Jur -->|No| Blocked([Return invalid result: jurisdiction required])
	Jur -->|Yes| Overrides[Read active rule definitions for the jurisdiction]
	Overrides --> Evaluate[Evaluate every rule in declaration order]
	Evaluate --> Trace[Write trace entry with failure count]
	Trace --> Audit[Insert a validation failure audit row per blocking failure]
	Audit --> Outcome{Any blocking failure recorded?}
	Outcome -->|Yes| Invalid([Return invalid result with all failures])
	Outcome -->|No| Valid([Return valid result with any warnings])
```

## Failure and edge-case behavior

- Uninitialized component: `FrameworkNotInitializedException` propagates before any rule runs, so a misconfigured host fails loudly at first use rather than validating under default settings.
- Missing rule set definition: `RuleSetNotFoundException` propagates and no partial collection is cached, so redeploying the XML file resolves the failure without a process restart.
- Missing jurisdiction code: reported as a blocking failure carrying the jurisdiction field, not as a skipped rule, so the gap is visible to the operator.
- Rule definition read timeout: the operation continues with XML-declared severities and adds a warning, because a reporting-side outage must not stop claim intake.
- Exception inside a single rule: captured as a blocking failure for that rule only; the remaining rules still run so the operator receives a complete correction list.
- Audit insert failure: traced and swallowed. The caller always receives the `ValidationResult`, so audit availability never gates claim submission.
- Empty rule set: returns a valid result with no failures. The caller cannot distinguish this from a record that passed every rule, which is why the audit row records the evaluated rule count.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- Database tables

## Sources
- src/SAIF.Framework.Validation/ValidationEngine.vb
- src/SAIF.Framework.Validation/RuleSetLoader.vb
- src/SAIF.Framework.Validation/Rules/ValidationRule.vb
- src/SAIF.Framework.Validation/ValidationResult.vb
- src/SAIF.Framework.Validation/Jurisdiction/JurisdictionResolver.vb
- src/SAIF.Framework.Validation/Data/RuleDefinitionRepository.vb
- src/SAIF.Framework.Validation/Data/ValidationAuditRepository.vb
- src/SAIF.Framework.Validation/RuleSets/ClaimIntake.rules.xml