ValidationRule\<P\>

A validation rule declares a single validation concern: which fields must be present, which additional optional fields trigger re-evaluation, which field displays errors, and the sync/async check functions.

Rules declare topology only — no debounce timings, no UI concerns. Those belong in the integration layer (e.g., useIncrementalValidation config).

Rules are evaluated in array order. For a given errorField, the first rule with a non-empty result wins (priority = array index).

Within a single rule, sync acts as a gate for async: if sync returns issues, async does not fire.

First-party rules are created with defineValidationRule, which narrows callback values to their declared topology and rejects undeclared property reads at runtime. The structural interface remains public so external rule objects stay compatible with the runner.

Type Parameters

Type Parameter
P

Properties

async?

readonly optional async?: (values, ctx, signal) => Promise<ValidationIssue[]>;

Async check — runs when deps present and sync passes. Return [] for valid.

Parameters

Parameter	Type
values	Partial<P>
ctx	SDKContext
signal	AbortSignal

Returns

Promise<ValidationIssue[]>

---

dependsOn

readonly dependsOn: readonly keyof P[];

Required fields for this rule. The rule only fires when every dependency is non-nullish, and each dependency automatically triggers incremental re-validation when its value changes.

---

errorField

readonly errorField: keyof P;

Field to display errors on in the UI (slot routing). Individual ValidationIssue.field values returned by sync/async may name sub-fields for diagnostic detail, but the runner uses errorField to decide which UI slot receives the issues.

---

errorFields?

readonly optional errorFields?: readonly keyof P[];

Top-level UI fields a multi-field rule may emit. When provided, useIncrementalValidation routes each issue to the matching declared field and uses errorField as the fallback for unmatched/sub-field issues.

Omit this for the usual single-slot rule behavior.

---

revalidateOn?

readonly optional revalidateOn?: readonly keyof P[];

Additional fields whose changes trigger incremental re-validation without gating the rule. Use this for optional inputs, XOR selections, and other values the rule reads but does not require to be present.

runValidation remains eager and therefore does not use this property.

---

sync?

readonly optional sync?: (values, ctx) => ValidationIssue[];

Sync check — runs immediately when deps are present. Return [] for valid.

Parameters

Parameter	Type
values	Partial<P>
ctx	SDKContext

Returns

ValidationIssue[]