Fields

A field is a property of the entity to be imported. For example, if you are importing Contacts some fields are the "First name", "Last name", "Phone", "Email" and "Country". When defining the fields, it is sufficient to provide only the label. These are enough to get you started.

What about the data type, you may ask. Well, that is not necessary. Everything is treated as a string and you can use transformers and validators to normalize the data and apply some constraints. More on this later.

Let's continue with our example, to import Contacts. Here is a possible definition for fields, without any validators or transformers for now. The example below is enough to allow your users to map data from their CSV and Excel files. The fields will appear in the wizard with the same order as defined in the array below.

 1[
 2  {
 3    "label": "First name"
 4  },
 5  {
 6    "label": "Last name"
 7  },
 8  {
 9    "label": "Phone"
10  },
11  {
12    "label": "Email"
13  },
14  {
15    "label": "Country"
16  }
17]

#Mapping Strategy

By design, importOK tries to match the fields specified in the schema to the columns included in the uploaded file. This is done by calculating the Levenshtein distance between each field and header name, making it ideal to auto-correct typos and align header labels with the actual field name. Having said that, it is still possible to define your own mapping strategy.

#Dynamic Field Processing

Sometimes you need to modify your field definitions based on the uploaded data. For example, you might want to add fields dynamically based on the columns present in the file, or adjust field configurations based on the data content.

ImportOK provides field processors that run before the mapping step and allow you to analyze the uploaded data and modify field definitions accordingly. This enables dynamic field generation, conditional configuration, and data-driven schema adjustments.

For detailed information on implementing field processors, see the Field Processor reference.

#Field Schema

label

description

transformers

validators

provider

aliases

#Field Aliases

Field aliases allow you to define alternative names that should be considered when automatically mapping columns from uploaded files to your fields. This is particularly useful when users might have different naming conventions or when you want to support common variations of field names.

 1{
 2  "firstName": {
 3    "label": "First Name",
 4    "aliases": ["first_name", "fname", "given_name", "forename"]
 5  },
 6  "lastName": {
 7    "label": "Last Name",
 8    "aliases": ["last_name", "lname", "surname", "family_name"]
 9  },
10  "email": {
11    "label": "Email Address",
12    "aliases": ["email", "mail", "e_mail", "contact_email"]
13  }
14}

In the next step we are going to extend the above example to include a few transformers aiming to auto heal the uploaded data, like trimming spaces.

Let's define some transformers →