ws.validations

WorksheetValidation

Sub-API for data validation operations on a worksheet.

13 methods

set

→ Promise<ValidationSetReceipt>

set(address: string, rule: ValidationRule): Promise<ValidationSetReceipt>;

Parameter	Type	Required
address	string	required
rule	ValidationRule	required

Set a validation rule on a cell or range. @param address - A1-style cell or range address (e.g. "A1", "A1:B5") @param rule - Validation rule to apply

ValidationRule ValidationSetReceipt

remove

→ Promise<void>

remove(address: string): Promise<void>;

Parameter	Type	Required
address	string	required

Remove validation from a cell (deletes any range schema covering the cell). @param address - A1-style cell address

get

→ Promise<ValidationRule | null>

get(address: string): Promise<ValidationRule | null>;

Parameter	Type	Required
address	string	required

Get the validation rule for a cell. @param address - A1-style cell address @returns The validation rule, or null if none

ValidationRule

peek

→ ValidationRule | null | undefined

peek(address: string): ValidationRule | null | undefined;

Parameter	Type	Required
address	string	required

Synchronously read a validation rule when this sheet's validation cache is already hydrated. Returns `undefined` when the sheet cache is cold, `null` when it is warm and no rule covers the cell, or the covering rule when one exists.

ValidationRule

has

→ Promise<boolean>

has(address: string): Promise<boolean>;

Parameter	Type	Required
address	string	required

Check if a cell has a validation rule. @param address - A1-style cell address @returns True if the cell has a validation rule

getCount

→ Promise<number>

getCount(): Promise<number>;

Get the total number of validation rules on this sheet. @returns The count of validation rules

getDropdownItems

→ Promise<string[]>

getDropdownItems(address: string): Promise<string[]>;

Parameter	Type	Required
address	string	required

Get dropdown items for a cell with list validation. @param address - A1-style cell address @returns Array of dropdown item strings

list

→ Promise<ValidationRule[]>

list(): Promise<ValidationRule[]>;

List all validation rules on the sheet. @returns Array of validation rules

ValidationRule

clear

→ Promise<void>

clear(range?: string): Promise<void>;

Parameter	Type	Required
range	string	optional

Clear all validation rules from the sheet. When called with a range argument, clears only rules overlapping that range (deprecated — use {@link clearInRange} for range-scoped clearing). @param range - (Optional) A1-style range string. If omitted, removes ALL rules.

clearInRange

→ Promise<void>

clearInRange(range: string | CellRange): Promise<void>;

Parameter	Type	Required
range	string \| CellRange	required

Clear validation rules that overlap a range. @param range - A1-style range string (e.g. "A1:B5") or CellRange object

CellRange

removeById

→ Promise<void>

removeById(id: string): Promise<void>;

Parameter	Type	Required
id	string	required

Remove a validation rule by its ID. @param id - Validation rule / range schema ID

validate

→ Promise<ValidationCheckResult>

validate(row: number, col: number, value: string): Promise<ValidationCheckResult>;

Parameter	Type	Required
row	number	required
col	number	required
value	string	required

Validate a candidate value for a cell against the rule covering it. Stateless — does not mutate any cell. Delegates to the compute layer, which evaluates the covering schema (including `allowBlank`, type checks, and range/list constraints). @param row - Row index (0-based) @param col - Column index (0-based) @param value - Candidate value (stringified — same form committed by the editor) @returns Validation result. `errorStyle` is "none" when no rule covers the cell.

ValidationCheckResult

getErrorsInRange

→ Promise<Array<{ row: number; col: number }>>

getErrorsInRange(
    startRow: number,
    startCol: number,
    endRow: number,
    endCol: number,
  ): Promise<Array<{ row: number; col: number }>>;

Parameter	Type	Required
startRow	number	required
startCol	number	required
endRow	number	required
endCol	number	required

Get cells with validation errors in a range. @param startRow - Start row (0-based) @param startCol - Start column (0-based) @param endRow - End row (0-based) @param endCol - End column (0-based) @returns Array of {row, col} for cells with errors