What Parser Schema JSON does

Parser Schema JSON tells Dispatchable how to take the raw data coming in from a third-party form or webhook and convert it into the structure our system expects.

Instead of requiring custom development for every form, the parser schema lets you define:

• which incoming field to read

• which Dispatchable field it should fill

• which transformations to apply

• which default values to use when needed

This is especially useful when your form provider sends data using field names that do not match Dispatchable’s field names.

How it works

When a webhook is received, Dispatchable follows this process:

1. It captures the raw incoming payload.

2. It reads the saved parser schema.

3. It maps each incoming field to the correct Dispatchable field.

4. It applies any transformations you defined.

5. It builds the final payload.

6. It sends that payload into the system.

Basic structure of a parser schema

A parser schema is a JSON object with two main sections:

• fields

• arrays

Example

{
  "fields": {
    "customer_first_name": {
      "path": "q12_contactInfo.field_1",
      "transforms": [
        { "name": "split_first_name" }
      ]
    },
    "customer_last_name": {
      "path": "q12_contactInfo.field_1",
      "transforms": [
        { "name": "split_last_name" }
      ]
    },
    "customer_phone_1": {
      "path": "q12_contactInfo.field_2",
      "transforms": [
        { "name": "digits_only" }
      ]
    },
    "customer_email": {
      "path": "q12_contactInfo.field_3",
      "transforms": [
        { "name": "trim" },
        { "name": "lowercase" }
      ]
    },
    "load_type": {
      "value": "auto_transport"
    },
    "trailer_type": {
      "value": "OPEN"
    }
  },
  "arrays": {
    "vehicles": [
      {
        "vehicle_year": {
          "path": "q13_yearmakemodel.field_4"
        },
        "vehicle_make": {
          "path": "q13_yearmakemodel.field_5"
        },
        "vehicle_model": {
          "path": "q13_yearmakemodel.field_6"
        },
        "vehicle_type": {
          "value": "CAR"
        }
      }
    ]
  }
}

Field definitions

Each field inside fields can use one of these approaches.

1. path

Use path when the value should come from the incoming payload.

Example

{
  "customer_email": {
    "path": "q12_contactInfo.field_3"
  }
}

This tells the parser to read:

q12_contactInfo.field_3

from the incoming payload and store it as:

customer_email

2. value

Use value when you want to hard-set a field instead of reading it from the payload.

Example

{
  "load_type": {
    "value": "auto_transport"
  }
}

This always sets:

load_type = auto_transport

3. default

Use default when a field should fall back to a value if the incoming value is missing or blank.

Example

{
  "origin_zip": {
    "path": "q14_typeA",
    "transforms": [
      { "name": "extract_zip" }
    ],
    "default": "00000"
  }
}

If no zip code can be extracted, the parser uses 00000.

4. transforms

Use transforms to modify the incoming value before saving it.

Example

{
  "customer_phone_1": {
    "path": "q12_contactInfo.field_2",
    "transforms": [
      { "name": "digits_only" }
    ]
  }
}

If the incoming value is:

"(805) 665-8716"

the saved value becomes:

"8056658716"

Using nested paths

Paths use dot notation to read nested JSON fields.

Example payload

{
  "q12_contactInfo": {
    "field_1": "Jason Test",
    "field_2": "(954) 833-9829",
    "field_3": "jason@test.com"
  }
}

Matching schema

{
  "customer_email": {
    "path": "q12_contactInfo.field_3"
  }
}

Using arrays

Use the arrays section when a target field needs to be built as an array, like vehicles.

Example

{
  "arrays": {
    "vehicles": [
      {
        "vehicle_year": {
          "path": "q13_yearmakemodel.field_4"
        },
        "vehicle_make": {
          "path": "q13_yearmakemodel.field_5"
        },
        "vehicle_model": {
          "path": "q13_yearmakemodel.field_6"
        },
        "vehicle_type": {
          "value": "CAR"
        },
        "is_operational": {
          "path": "q13_yearmakemodel.field_8",
          "transforms": [
            {
              "name": "map_value",
              "options": {
                "map": {
                  "Operational": true,
                  "Inoperable": false
                }
              }
            }
          ]
        }
      }
    ]
  }
}

This creates a vehicles array in the final payload.

Supported transform types

Below are common transforms you can use.

trim

Removes extra spaces.

{ "name": "trim" }

lowercase

Converts text to lowercase.

{ "name": "lowercase" }

uppercase

Converts text to uppercase.

{ "name": "uppercase" }

digits_only

Removes anything that is not a number.

{ "name": "digits_only" }

split_first_name

Takes a full name and returns the first name.

{ "name": "split_first_name" }

split_last_name

Takes a full name and returns the last name.

{ "name": "split_last_name" }

date_from_parts

Builds a date from separate year, month, and day fields.

{
  "name": "date_from_parts",
  "options": {
    "year_key": "year",
    "month_key": "month",
    "day_key": "day"
  }
}

extract_city

Pulls the city from a comma-separated location string.

{
  "name": "extract_city",
  "options": {
    "delimiter": ",",
    "index": 0
  }
}

extract_state_code

Finds a 2-letter state code in a location string.

{ "name": "extract_state_code" }

extract_zip

Finds a zip code in a location string.

{ "name": "extract_zip" }

map_value

Maps one incoming value to another.

{
  "name": "map_value",
  "options": {
    "map": {
      "Operational": true,
      "Inoperable": false
    }
  }
}

Example using a JotForm payload

Incoming payload

{
  "q14_typeA": "Ridgeland, MS, Madison County, USA, 39157",
  "q15_typeA15": "Ventura, CA, Ventura County, USA",
  "q13_yearmakemodel": {
    "field_4": "2019",
    "field_5": "Subaru",
    "field_6": "Outback",
    "field_8": "Operational"
  },
  "q16_shippingDate": {
    "year": "2026",
    "month": "04",
    "day": "04"
  },
  "q12_contactInfo": {
    "field_1": "Colin Dixon",
    "field_2": "(111) 111-1111",
    "field_3": "testemail@gmail.com"
  }
}

Parser schema

{
  "fields": {
    "origin_city": {
      "path": "q14_typeA",
      "transforms": [
        { "name": "extract_city", "options": { "delimiter": ",", "index": 0 } }
      ]
    },
    "origin_state": {
      "path": "q14_typeA",
      "transforms": [
        { "name": "extract_state_code" }
      ]
    },
    "origin_zip": {
      "path": "q14_typeA",
      "transforms": [
        { "name": "extract_zip" }
      ],
      "default": "00000"
    },
    "first_avail": {
      "path": "q16_shippingDate",
      "transforms": [
        {
          "name": "date_from_parts",
          "options": {
            "year_key": "year",
            "month_key": "month",
            "day_key": "day"
          }
        }
      ]
    },
    "customer_first_name": {
      "path": "q12_contactInfo.field_1",
      "transforms": [
        { "name": "split_first_name" }
      ]
    },
    "customer_last_name": {
      "path": "q12_contactInfo.field_1",
      "transforms": [
        { "name": "split_last_name" }
      ]
    },
    "customer_phone_1": {
      "path": "q12_contactInfo.field_2",
      "transforms": [
        { "name": "digits_only" }
      ]
    },
    "customer_email": {
      "path": "q12_contactInfo.field_3",
      "transforms": [
        { "name": "trim" },
        { "name": "lowercase" }
      ]
    },
    "load_type": {
      "value": "auto_transport"
    },
    "trailer_type": {
      "value": "OPEN"
    }
  },
  "arrays": {
    "vehicles": [
      {
        "vehicle_year": {
          "path": "q13_yearmakemodel.field_4"
        },
        "vehicle_make": {
          "path": "q13_yearmakemodel.field_5"
        },
        "vehicle_model": {
          "path": "q13_yearmakemodel.field_6"
        },
        "vehicle_type": {
          "value": "CAR"
        },
        "is_operational": {
          "path": "q13_yearmakemodel.field_8",
          "transforms": [
            {
              "name": "map_value",
              "options": {
                "map": {
                  "Operational": true,
                  "Inoperable": false
                }
              }
            }
          ]
        }
      }
    ]
  }
}

Best practices

1. Start with required fields first

Before building out every possible field, make sure you map the fields required by the target endpoint.

2. Use defaults carefully

Defaults are helpful, but only when they make business sense.

3. Keep transform names generic

Do not build schemas around provider-specific logic names. Use generic transform names like date_from_parts instead of vendor-specific names.

4. Use real JSON booleans

When using map_value, use:

true
false

not:

"true"
"false"

5. Validate after changes

After updating the parser schema, send test payloads and confirm the transformed output is valid.

Common mistakes

Invalid JSON

Make sure all keys and string values use double quotes.

Wrong path

If the path does not match the incoming payload exactly, the parser will return null.

String booleans instead of real booleans

This can cause validation errors on fields that expect true or false.

Missing required target fields

If required target fields are not mapped or defaulted, the final payload will fail validation.

When to update the parser schema

Update the parser schema when:

• your form field names change

• you add new fields to your form

• your target endpoint requires additional fields

• incoming values need new transformations

Summary

Parser Schema JSON allows you to map incoming webhook data into the exact structure Dispatchable expects.

It gives you control over:

• field mapping

• transformations

• defaults

• arrays like vehicles

This makes it possible to integrate third-party forms and webhook sources without requiring custom development each time.