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. Notice that some fields are required while others aren't. For the fields not required, you may either leave them out of your configuration all together or set the value of the field to an empty string. Setting the value of the field to null is not allowed and will result in an error.

{
...
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.
labelstringRequired 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.
validatorsarray[object]This is an array of validators for the field. See configuration details below.
type"checkbox"/"select"Optional (if not provided, defaults to text). Specifies the input type for the field. Currently only "checkbox" 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[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 must be an array of objects with a value and label key as follows:
  • [{value: '#F00', label: 'red'}, ...]

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 string with a valid regular expression to compare the field against, see examples provided below. Note: be sure that your regex are properly JSON string escaped. If you need help, here is an additional resource.
regexFlagsoptional regex based validators. Can be used with regex_matches and regex_excludes. This is an object with keys of ignoreCase, multiline, dotAll and unicode which all take a boolean value (defaulted to false when not provided), and allow for use of the i, m, s, and u regex flags.

Examples

validators: [
{
validate: "regex_matches",
regex: "^[a-z]+$",
regexFlags: {ignoreCase: true},
error: "Must only contain alphabet characters"
},
{
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.
uniqueThis verifies that each value in a given field is unique as compared to all the other values within that field.
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 all of the fields specified in an array of valid field keys are missing.
required_with_valuesThe field must be present and not empty only if one OR another of the fields specified in an array of valid field keys are present and have the specified value.
required_without_valuesThe field must be present and not empty only if one OR another of the fields specified in an array of valid field keys are present and do NOT have the specified value.
required_with_all_valuesThe field must be present and not empty only if ALL of the fields specified in an array of valid field keys are present and have the specified values.
required_without_all_valuesThe field must be present and not empty only if ALL of the fields specified in an array of valid field keys are present and do NOT have the specified values.
regex_matchesThe field value must match the given regular expression.
regex_excludesThe field value must not match the given regular expression.

Regex for 'email'

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