Field Configuration

Fields allow the user to map their data to your data model. You can add validation, format hinting and more with these configuration settings.

{
...
fields: [
{
label: "Email",
key: "email",
alternates: ["nom"],
validators: [{...}]
}
]
}

Settings

SettingFormatDescription
keystringRequired The JSON key you want to map the data to in the final output.
labelstringOptional (if not provided, label will be the same as key). This is displayed in the table header when entering, editing, and reviewing data.
descriptionstringThis is a short description of the field which will be displayed as a tooltip in the header of the associated column.
alternatesarray[string]Alternates are a powerful way to increase the accuracy of the automatic column matching. This is an array of strings that will help hint at the matching of the column. For example you may include surname as an alternate for a name column. If your user's file has a column with the heading "surname" the importer will suggest it as a match. While Flatfile learns from experience, alternates will increase the match confidence and allow you to provide a more accurate match to your customers.
validatorobject/string/regexA single validator for the field. See configuration details below.
validators[object/string/regex]This is an array of validators for the field. See configuration details below.
type"boolean"/"select"Optional (if not provided, defaults to text). Specifies the input type for the field. Currently only "boolean" and "select" are supported, which change the input to checkboxes and dropdowns respectively. If the input type is "select," you must also provide an options array to populate the dropdown with.
optionsarray[string/object]Required if type is set to "select". Specifies the array of options that will populate the dropdown when the type setting is set to "select." This array can take two forms:
  1. ['red', 'green', ...]
  2. [{value: '#F00', label: 'red'}, ...]
The latter allows a display value to be shown in the dropdown but another value to be stored in the data.

Validation Objects

Each field can have one or more validators associated with it. Each validator must be an object with the following minimal format: {validate: "validator_name"}.

Parameters

OptionDescription
validaterequired The value you provide here must be the name of one of the validators we provide.
errorThe message to display in the tooltip if this validation fails. Default: Field failed validation
fieldsrequired for required_ validators with related fields An array of valid field keys, see examples provided below.
regexrequired for regex based validators A valid regular expression to compare the field against, see examples provided below.

Examples

validators: [
{
validate: 'regex_matches',
regex: /^[\w ]+$/,
error: 'Must only contain alphanumeric characters or spaces'
},
{
validate: 'required'
},
{
validate: 'required_without',
fields: ['id', 'surname']
}
]

Available Validators

ValidatorDescription
requiredThe field under validation must be present in the input data and not empty. A field is considered "empty" if one of the following conditions are true:
  • The value is not provided.
  • The value is an empty string.
  • The value is an uploaded file with no path.
required_withThe field must be present and not empty only if any of the fields specified in an array of valid field keys are present.
required_with_allThe field must be present and not empty only if all of the fields specified in an array of valid field keys are present.
required_withoutThe field must be present and not empty only if any of the fields specified in an array of valid field keys are missing.
required_without_allThe field must be present and not empty only if al of the fields specified in an array of valid field keys are missing.
regex_matchesThe field value must match the given regular expression.
regex_excludesThe field value must not match the given regular expression.

Validation Regex Examples

Regex for 'email'

We use this awesome regex from http://emailregex.com/ for testing email validity.

/^(([^<>()\[\]\\.,;:\[email protected]"]+(\.[^<>()\[\]\\.,;:\[email protected]"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/

Regex for 'boolean'

For handling the values for the checkbox inputs, we use this regex internally, but you can also use it without the checkbox functionality.

/^$|^(1|0|yes|no|true|false|on|off|enabled|disabled)$/i

We're working on building out more robust validation tools that will also clean and format data for you. In the meantime, you can research and provide your own regexes for any validation you need.