Version: v2.0

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 accept 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.

fields: [
  {
    label: "Name",
    key: "fullName",
  },
  {
    label: "Email",
    key: "email",
  },
  {
    label: "City",
    key: "city",
  },
  {
    label: "State",
    key: "state",
  },
  {
    label: "Zip Code",
    key: "zipCode",
  },
  {
    label: "Age",
    key: "age",
  },
  {
    label: "Currently Employed?",
    key: "employmentStatus",
  },
];

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

Name	Email	City	State	Zip code	Age	Currently employed?
John Smith	john@flatfile.com	Orlando	FL	12345	21	yes
Jill Shaw	john@flatfile.com	Seattle	Wash.	2456	old	self-employed
David Boskovitz		Denver	Colorado	98765-4321	forty-five	Fileflat CEO
Eric Crenshaw	bige@something.com	Atlanta	GA	54321	37	false

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

[
  {
    "fullName": "John Smith",
    "email": "john@flatfile.com",
    "city": "Orlando",
    "state": "FL",
    "zipCode": "12345",
    "age": "21",
    "employmentStatus": "Yes"
  },
  {
    "fullName": "Jill Shaw",
    "email": "john@flatfile.com",
    "city": "Seattle",
    "state": "Wash.",
    "zipCode": "2546",
    "age": "old",
    "employmentStatus": "Self-employed"
  },
  {
    "fullName": "David Boskovitz",
    "email": "",
    "city": "Denver",
    "state": "Colorado",
    "zipCode": "98765-4321",
    "age": "forty-five",
    "employmentStatus": "Fileflat CEO"
  }
  {
    "fullName": "Erik Crenshaw",
    "email": "bige@something",
    "city": "Atlanta",
    "state": "GA",
    "zipCode": "54321",
    "age": "37",
    "employmentStatus": "False"
  }
]

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
Description	As 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
Description	The `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`
Description	The `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, ... ]`
Description	The `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.

note

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, ... ]`
Description	The `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: validate, 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.
```
fields: [
  {
    key: "email",
    label: "Email",
    validators: [{ validate: "required" }, { validate: "unique" }],
  },
];
```
- 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 or required_without_all) - This is a list of the fields that should be considered/compared to the field using this validation type. Below is an example using required_with but the same syntax can be used with required_without, required_with_all and required_without_all.
```
fields: [
  {
    key: "city",
    label: "City",
  },
  {
    key: "state",
    label: "State",
    validators: [
      {
        validate: "required_with",
        fields: ["city"],
      },
    ],
  },
];
```
- fieldValues: {fieldName: string, ...} - (required if use validate with required_with_values, required_without_values, required_with_all_values or required_without_all_values) - This is an object that has a key that related to the field name of the field you want to target and the value you are wanting to validate against as the value. Below is an example using required_with_values but the same syntax can be used with required_without_values, required_with_all_values and required_without_all_values.
```
fields: [
  {
    key: "reason",
    label: "Reason for signing up",
  },
  {
    key: "more_description",
    label: "Tell us more about why you signed up",
    validators: [
      {
        validate: "required_with_values",
        fieldValues: { reason: "Other" },
      },
    ],
  },
];
```
- 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 )

info

See the next document, "Regex and Flatfile," for code examples and more detailed information on using regular expressions in Flatfile.

type

Type 'checkbox' or 'select'

Description The 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.

Type	`'checkbox'` or `'select'`
Description	The `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.

matchStrategy

Type	`'fuzzy'` or `'exact'`
Description	The `matchStrategy` key can define the automatic matching strategy of the importer to either `fuzzy`, which is the default, or `exact` for the options for `type: "select"`. Setting this to `exact` will match them only to an exact match within the options you define.

options

Type	`[ SelectOptionsObject, ... ]`
Required	required with `type: 'select'`
Description	The `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. Additionally, there is an `alternates` key for providing additional values for the key to automatically match to during the import process.

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.
alternates - This is an optional string array with additional values to help the importer automatically match to a specific key.

Below is an example of a type: "select" field that matches alternates of great and wonderful to the provided good value.

{
    label: "Select Field",
    key: "select_field",
    type: "select",
    options: [
        { value: "bad", label: "Bad" },
        { value: "good", label: "Good", alternates: ["great", "wonderful"] }
    ]
}

Schema & Advanced Field Configuration

label​

key​

description​

alternates​

validators​

type​

matchStrategy​

options​