Schema & Advanced Field Configuration

Flatfile Portal allows you to define your unique schema, and return the imported data in this format. This means that you can expect the same format of valid results for each and every import no matter how your users bring data to you. The minimum requirement for each field for the schema is a

label
and a
key
value, whick allows your users to map each field/column in their data to the appropriate key you set up in your fields. Although optional, it is also recommended to add additional validation, normalization, and options. This allows the data you receive to be pulled into your system with minimal or no additional processing needed. You can do this using Flatfile's additional field configuration options. Starting with only required settings, we can see what the expected results will be, and add more validation from there. Here's a configuration that accepts Name, Email, City, State, Zip Code, Age and Currently Employed.

The table below is an example of what a 4 record file might look like when using the above example data model/schema:

NameEmailCityStateZip CodeAgeCurrently Employed?
John Smith[email protected]OrlandoFL1234521Yes
Jill Shaw[email protected]SeattleWash.2546oldSelf-employed
David BoskovitzDenverColorado98765-4321forty-fiveFileflat CEO
Eric Crenshaw[email protected]AtlantaGA5432137False

Using this configuration and example file, you would expect to see the following as the returned results in

results.validData
:

One of the benefits of our importer is that you can re-order each field in the example file and the output results will be the same. The drawback of this very basic configuration is that it only helps map the fields appropriately and doesn't take advantage of any of the validation options we offer. In the

validData
above, one record's email address is the same as another record's. One record doesn't have an email address. There are three different ways the states are being presented. There are three different formats for zip codes including one that doesn't have enough characters. There's only one numeric value for age. It also appears that "Employment status?" meant something a little different in each record. Below, we will introduce some of additional configuration options to help clean this up before allowing the data to be submitted.


label

Type
string
Required
DescriptionAs stated in the basic setup guide,
label
is a required field type that will display in the header row as the field name that the user will see while doing an import.

key

Type
string
Required
DescriptionThe
key
value is what your application is expecting a field to be called. This is not displayed to the client, and can match the value that you call it in the rest of your application.

description

Type
string
DescriptionThe
description
option gives you the ability to provide more details about a particular field to users. This will display an info icon in the importer, and displays the message you provide when hovering over the field's header.

alternates

Type
[ string, ... ]
DescriptionThe
alternates
option is a way for you to provide an alternate matching option to help with matching fields automatically for users. For example, let's say you have an email field, but you know that there are a significant number of your users that upload files that have "electronic mail" for the header. You could provide "electronic mail" as one of the alternates to help the matching process.

Flatfile uses AI to help with the matching process. What that means for you is that previous match history seen by Flatfile helps your users with the matching step. So while you could provide 'name' as an alternate to a field for full name, you shouldn't have to do so for the matching to simply work. We recommend using this sparingly and for uncommon situations with your particular data set.


validators

Type
[ ValidatorObject, ... ]
DescriptionThe
validators
option is where Flatfile starts to become very useful in making sure you have clean data. This lets you set conditions for how the data should be formatted, and provides error messaging to the user identifying what the problem is and how to fix it.

The

validators
option is an array of objects with each object having a total of 4 keys that could be used. The keys are:
validates
,
error
,
regex
and
regexFlags

  • validate: string
    - (required with
    validators
    )
    - This is the type of validation you wish to have for the field.
    • required - usage:
      validate: "required"
      - This designates the field as a required field and will invalidate/error the record if nothing is provided in this field.
    • unique - usage:
      validate: "unique"
      - This field will require that no two records in the field contain the same value. It will not provide an error on the first use of the value, but will provide an error for any subsequent usage, meaning, if the same value appears 3 times in this field, the first use will be valid and the second and third uses would have an error.
    • regex_matches - usage:
      validate: "regex_matches"
      - Using this will require the field to match the regex validation provided in the
      regex
      key. If using this option, you must also provide a JSON escaped regex string in the
      regex
      key.
    • regex_excludes - usage:
      validate: "regex_excludes"
      - Using this will require the field to NOT match the regex validation provided in the
      regex
      key. If using this option, you must also provide a JSON escaped regex string in the
      regex
      key.
    • required_with - usage:
      validate: "required_with"
      - The field must be present and not empty only if any of the fields specified in an array of valid field keys are present.
    • required_without - usage:
      validate: "required_without"
      - The field must be present and not empty only if any of the fields specified in an array of valid field keys are missing.
    • required_with_all - usage:
      validate: "required_with_all"
      - The field must be present and not empty only if all of the fields specified in an array of valid field keys are present.
    • required_without_all - usage:
      validate: "required_without_all"
      - The 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_values - usage:
      validate: "required_with_values"
      - The 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_values - usage:
      validate: "required_without_values"
      - The 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_values - usage:
      validate: "required_with_all_values"
      - The 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_values - usage:
      validate: "required_without_all_values"
      - The 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.
  • error: string
    - This is how you can display a custom error message to users if the value fails validation. Not required, but if not provided, users will get a default error message based on type of validator. Example:
    validate: "required"
    returns an error message that simply says "Required."
  • fields: [string, ...]
    - (required if using
    validate
    with
    required_with
    ,
    required_without
    ,
    required_with_all
    ,
    required_without_all
    ,
    required_with_values
    ,
    required_without_values
    ,
    required_with_all_values
    or
    required_without_all_values
    )
    - This is a list of the fields that should be considered/compared to the field using this validation type.
  • regex: string
    - (required if using
    validate
    with
    regex_matches
    or
    regex_excludes
    as the value for the
    validate
    key)
    - This is where you would write the regular expression that you want to validate against. Please note that this regular expression must be JSON escaped and a string. If you need help with testing your regex and/or JSON escaping it, we recommend checking out this resource. We also have put together a guide for working with regex in Flatfile in our Regex Validation documentation.
  • regexFlags: { key: boolean, ... }
    - This key allows you to provide the
    i
    ,
    m
    ,
    u
    and
    s
    regex flags as a key and boolean value as opposed to writing them in your regex string. Please note that to use flags, you will need to enable them with this option. Writing them directly in your regex string will not work and may cause errors.
    • ignoreCase: boolean
      - Case insensitive flag (regex flag
      i
      )
    • dotAll: boolean
      - Matches all including any line breaks (regex flag
      s
      )
    • multiline: boolean
      - Multiline flag (regex flag
      m
      )
    • unicode: boolean
      - Unicode flag (regex flag
      u
      )

type

Type
'checkbox'
or
'select
DescriptionThe
type
option allows you to designate the field as a
checkbox
or
select
field. The
checkbox
field will render a checkbox, but accept boolean or boolean-like values (
true
/
false
,
0
/
1
,
yes
/
no
,
y
/
n
,
on
/
off
,
enabled
/
disabled
) as the field's response. The true-like values within parentheses will render a checkbox that is checked. The false-like values will render a checkbox that is unchecked. In either case, the end result data will provide back to you the actual file value as the data, unless it is updated, then it will return a "true" or "false" value. The
select
field will render a dropdown menu and match the values to a pre-defined list of
options
that are provided.

options

Type
[ SelectOptionsObject, ... ]
Requiredrequired with
type: 'select'
DescriptionThe
options
option is required with and can only be used when
type
is set to
"select"
. This is going to be an array of objects, each object being one option in the dropdown containing a
value
and
label
for the option.
  • value
    (required) - This is the actual value that will come through in the data.
  • label
    (required) - This is what the user sees in the dropdown menu.