Extend Flatfile validation capabilities with custom validation logic for complex field and sheet-level constraints
validator
key in the blueprint with a corresponding handler registered in the listener.
externalConstraint
), add a constraint object to a field’s constraints
array:
Parameter | Type | Required | Description |
---|---|---|---|
type | string | Yes | Must be set to ‘external’ to indicate it’s a custom validation rule |
validator | string | Yes | A unique name for your validator used to link the blueprint rule to the validation logic |
config | object | No | An arbitrary object containing any parameters or settings your validation logic needs |
externalSheetConstraint
), add a constraint object to the sheet’s top-level constraints
array:
Parameter | Type | Required | Description |
---|---|---|---|
type | string | Yes | Must be set to ‘external’ |
validator | string | Yes | A unique name for your sheet-level validator |
fields | string[] | Yes | An array of field keys that this constraint applies to |
config | object | No | An arbitrary object with settings for your validation logic |
external
type constraints are defined in the blueprint, the plugin will have no effect. The validation logic only runs when a matching validator
is found in the blueprint for the current sheet.
external
constraint in the blueprint.
Signature:
validator
(string): The name of the validator. This must match the validator
property in the field’s constraint configuration in the blueprint.cb
(function): A callback function that contains the validation logic. It receives:
value
(any): The value of the cell being validatedkey
(string): The key of the field being validatedsupport
(object): An object containing helpful context:
config
(any): The config
object from the blueprint constraintrecord
(FlatfileRecord): The full record object, which can be used to get other values or add errorsproperty
(Flatfile.Property): The full property (field) definition from the sheet schemaevent
(FlatfileEvent): The raw event that triggered the validationexternal
constraint in the sheet’s top-level constraints
array.
Signature:
validator
(string): The name of the validator. This must match the validator
property in the sheet’s constraint configuration.cb
(function): A callback function that contains the validation logic. It receives:
values
(Record<string, TRecordValue>): An object where keys are the field keys from the constraint’s fields
array and values are the corresponding cell values for the current recordkeys
(string[]): An array of the field keys this constraint applies to (from the fields
property in the blueprint)support
(object): An object containing helpful context:
config
(any): The config
object from the blueprint constraintrecord
(FlatfileRecord): The full record objectproperties
(Flatfile.Property[]): An array of the full property (field) definitions for the fields involved in this constraintevent
(FlatfileEvent): The raw event that triggered the validationvalidator
string in your blueprint constraint exactly matches the string you passed to externalConstraint
or externalSheetConstraint
in your listener.type: 'external'
.externalSheetConstraint
, make sure the sheet-level constraint in the blueprint includes the fields
array, listing the keys of all fields involved in the validation.commit:created
event). For very high-frequency operations, this could be a performance consideration, but for most use cases, it is not an issue.@flatfile/plugin-record-hook
to process records in bulk.record.addError(key, message)
to add an error to a specific field. This is useful for sheet-level constraints where you might want to flag only one of the involved fields.throw new Error(message)
or throw "message"
. The plugin will catch the thrown error. For externalConstraint
, the error is added to the field being validated. For externalSheetConstraint
, the same error message is added to all fields listed in the constraint’s fields
array.