docs
  1. SCAYLE Resource Center
  2. Developer Guides
  3. Checkout
  4. Customization
  5. Configure JSON
  6. Address Forms

Address Forms

Overview

The addressForm section contains default address form configuration. Additionally, under countryOverwrites.{countryCode}.addressForm you can specify address form configuration per country, that overwrites the default address form config for this country. Properties that are not specified on the country level will be inherited from the default.

Under addressForm, as well as for each country under countryOverwrites.{countryCode}.addressForm, and also under countryOverwrites.{countryCode}.addressForm the following fields or field groups can be configured: title, streetHouseNumber, additional, zipCodeCity and state.

Country code

The countryCode is the ISO 3166-1 alpha-2 country code.

Available options

These are the available config options under addressForm and addressForm.countryOverwrites.{countryCode}:

ParameterDescriptionData TypePossible Values
specialComponentEnable/disable a country-specific address component with extra functionality. Available for countries BG, NL and USbooleantrue or false
title.enabledWhen enabled, title field is addedbooleantrue or false
streetHouseNumber.separateFieldsWhen enabled, the street and house number fields are combinedbooleantrue or false
streetHouseNumber.houseNumber.positionSpecify if the house number goes before the street ("first")string"first" or "second"
additional.enabledWhen enabled, an additional address field is addedbooleantrue or false
zipCodeCity.zipCode.enabledWhen enabled, zip code field is addedbooleantrue or false
zipCodeCity.zipCode.positionSpecify if the zip code goes before the city ("first")string"first" or "second"
zipCodeCity.zipCode.allowListEnable/disable an allowlist (the actual allowlist data needs to be setup separately by SCAYLE)booleantrue or false
zipCodeCity.zipCode.blockListEnable/disable a block list (the actual block list data needs to be setup separately by SCAYLE)booleantrue or false
zipCodeCity.zipCode.completion.enabledEnable/disable zip code suggestions based on the city (if already entered). Available for RObooleantrue or false
zipCodeCity.zipCode.completion.disableSpecialComponentSuggestionEnable/disable specialComponent's address suggestionsbooleantrue or false
zipCodeCity.city.completion.enabledEnable/disable city completion based on the zip code (if already entered), available for AT, CH, CZ, DE, ES, HU, PL, PT, SI and SKbooleantrue or false
zipCodeCity.zipCode.formatOnBlur.inputZip code field substitution on blurstringgroup-capture regex string, e.g. "^(LV-)?(\\d{4})$"
zipCodeCity.zipCode.formatOnBlur.outputZip code field substitution on blurstringgroup-replace/substitute regex string, e.g. "LV-$2"
state.enabledEnable/disable additional state fieldbooleantrue or false
state.select.enabledEnable/disable state dropdown (disabling will lead to free text field)booleantrue or false
state.select.blockListRemove specific states from the state dropdownarraye.g. ["CA", "MO"]
googleMapsAutocomplete.enabledEnable/disable Google maps autocompletebooleane.g. true or false

When specialComponent is set to true for country NL, the streetHouseNumber.separateFields also needs to be set to true.
The feature requires Address Doctor to be activated on the backend.

Special Components

The special component mainly consist in a custom form's layout for the fields and specific address validation/suggestion for each country.

BG: Bulgaria

Fields order:

  1. city
  2. zipCode
  3. street
  4. houseNumber
  5. additional

Custom city suggestion are based on the provided zipCode.

NL: Netherlands

Fields order:

  1. zipCode
  2. houseNumber
  3. additional
  4. street city

Custom address suggestion are based on the provided zipCode and houseNumber.

US: United States

Fields order:

  1. state
  2. zipCode and City
  3. street and houseNumber
  4. additional

This form layout includes the mandatory state field, which can be use as Select and displays all the available US states for the user to pick.

It supports zipCode > city completion and googleMapsAutocomplete features (if configured).

Field Validation

Under streetHouseNumber, streetHouseNumber.houseNumber, streetHouseNumber.street, additional, zipCodeCity.zipCode, zipCodeCity.city, and state you may specify the following general field validation properties:

  • required is used to specify if the field is required or optional
  • minLength is used to specify the minimum number of characters in the field
  • maxLength is used to specify the maximum number of characters in the field
  • format is used to specify the format of the input. This can be a reference to a predefined format ("email", "name", "houseNumber", "streetOrCity" or "default) or a custom regex string (e.g. "^\\d{5}$"). Read more about predefined formats.
  • illegalTerms is used to block certain terms from being part of the input in the field (e.g. ["po box", "postfach"]).
  • layeredValidation is used to add validation rules and point to a specific translation key when the rule fails. It takes an array with format and translationKey. (e.g. [{ "format": "[A-Z].*[A-Z]", "translationKey": "custom1"}]).

Street / house number

Depending on the value for streetHouseNumber.separateFields these validation properties go either directly on the streetHouseNumber section for one combined field or on both, streetHouseNumber.houseNumber and streetHouseNumber.street, for separate fields.

State

if state.select.enabled is true the validation properties are not needed.

Examples

Basic Configuration
  "addressForm": {
    "DE": {
      "title": {
        "enabled": false
      },
      "streetHouseNumber": {
        "separateFields": false,
        "houseNumber": {
          "position": "second"
        },
        "illegalTerms": ["postfach"]
      },
      "zipCodeCity": {
        "zipCode": {
          "position": "first",
          "minLength": 5,
          "maxLength": 5,
          "format": "^//d{5}$"
        }
      },
      "additional": {
        "enabled": true
      }
    },
    "NL": {
      "title": {
        "enabled": false
      },
      "streetHouseNumber": {
        "separateFields": false,
        "houseNumber": {
          "position": "second"
        },
        "illegalTerms": ["postbus", "po box"]
      },
      "zipCodeCity": {
        "zipCode": {
          "position": "first",
          "minLength": 7,
          "maxLength": 7,
          "format": "^//d{4} [A-Z]{2}$"
        }
      }
    },
    "LV": {
      "zipCodeCity": {
        "zipCode": {
          "position": "second",
          "minLength": 4,
          "maxLength": 7,
          "format": "^(LV-)?\\d{4}$",
          "formatOnBlur": {
            "input": "^(LV-)?(\\d{4})$",
            "output": "LV-$2"
          }
        }
      }
    }
  }

Custom street validation

Here is an example if for US addresses you want separate street and house number fields for a custom street validation:

  "addressForm": {
    "US": {
      "streetHouseNumber": {
        "separateFields": true,
        "street": {
          "minLength": 3,
          "maxLength": 40,
          "format": "^.$"
        },
        "houseNumber": {
          "position": "first",
          "required": false
        }
      }
    }
  }

Predefined Formats

"format": "email"
/^[\p{L}\d!#$%&'*+/=?^_`{|}~-]+(\.[\p{L}\d!#$%&'*+/=?^_`{|}~-]+)*@[\p{L}\d]+([.-][\p{L}\d]+)*\.\p{L}{2,}$/u

What this pattern allows:

  1. The local part of the email (before the @) can include:
    • Unicode letters (from any language)
    • Digits (0-9)
    • Special characters: !#$%&'*+/=?^_{|}~-`
    • Periods, provided they are not at the start or end, and not consecutive
  2. The domain part of the email (after the @) can include:
    • Unicode letters (from any language)
    • Digits (0-9)
    • Periods and hyphens, provided they are not at the start or end, and not consecutive
    • A top-level domain with at least two letters

Examples of Matches

Examples of Non-Matches

  • "plainaddress" (missing @ and domain)
  • "@missingusername.com" (missing local part)
  • "[email protected]" (period immediately after @)
  • "username@com" (TLD too short)
"format": "houseNumber"
/^[1-9\p{L}][\d\p{L}]*(?:(?: +| *[\/\-,] *)[\d\p{L}]+)*?$/u

What this pattern allows :

  • Strings that start with a non-zero digit or a letter.
    Examples: 1, A, 5, Z.
  • May continue with any combination of digits and letters.
    Examples: 1A, A1, 123ABC, XYZ987.
  • Can include groups separated by spaces or specific punctuation (-, /, +, ,), optionally surrounded by spaces. Each group must start and end with a digit or letter.
    Examples: A 123, 9-ABC, Z / 456, 3+XYZ, B,789.

Example Matches

  1. A123
    • Starts with a letter (A).
    • Followed by digits (123).
  2. 9ABC
    • Starts with a digit (9).
    • Followed by letters (ABC).
  3. A 123
    • Starts with a letter (A).
    • Followed by a space and then digits (123).
  4. 9-ABC
    • Starts with a digit (9).
    • Followed by a hyphen (-) and then letters (ABC).
  5. X/123
    • Starts with a letter (X).
    • Followed by a slash (/) and then digits (123).

Example Non-Matches

  1. 0123
    • Starts with a zero (0), which is not allowed by the pattern.
  2. A--123
    • Contains two hyphens (--), which is not allowed by the pattern.
  3. A123$
    • Starts valid but ends with $
"format": "name"
/^[\p{L}\-. ]+$/u

What this pattern allows:

  • Any combination of Unicode letters (from any language),
  • Hyphens (-),
  • Dots (.),
  • Spaces ( ).

Additionally, the pattern enforces that these characters must appear from the beginning to the end of the string, with no other characters allowed.

Examples of Matches

  • "John Doe"
  • "Marie Curie-Skłodowska"
  • "Évariste Galois"
  • "Dr. John H. Watson"

Examples of Non-Matches

  • "John Doe!" (contains an exclamation mark)
  • "1234" (contains digits)
  • "Marie@Curie" (contains an @ symbol
"format": "streetOrCity"
/^[\p{L}\d\-. '\u2018-\u2019]+$/u

What this pattern allows:

  • Unicode letters (from any language)
  • Digits (0-9)
  • Hyphens (-)
  • Dots (.)
  • Spaces ( )
  • Single quotes (')
  • Left single quotation marks (‘)
  • Right single quotation marks (’)

Examples of Matches

  • "123 Main St."
  • "O'Connor Street"
  • "St. John’s Avenue"
  • "Rue de l'Église"
  • "Straße 123"

Examples of Non-Matches

  • "123 Main St!" (contains an exclamation mark)
  • "Main@Street" (contains an @ symbol)
  • "City#1" (contains a # symbol)
"format": "default"
/^[\p{L}\d\-./,()&+:!? '"\u2018-\u201F\u00AA\u00BA]+$/u

Use Cases

  1. Validation of Usernames or Identifiers
  2. Validation of text fields
  3. Sanitisation of input data to prevent injection attacks

What this pattern allows:

Strings that start and end with one or more characters that are any of the following:

  • Unicode letters.
  • Digits (0-9).
  • Specific punctuation and symbols: hyphen (-), dot (.), slash (/), comma (,), parentheses (( and )), ampersand (&), colon (:), plus (+), exclamation mark (!), question mark (?), space ( ), single quote ('), and double quote (").
  • Special Unicode quotation marks in the range U+2018 to U+201F.
  • Feminine ordinal indicator (ª, U+00AA) and masculine ordinal indicator (º, U+00BA).

Example Matches

  1. Hello, World!
    • Contains letters, comma, space, and exclamation mark.
  2. 123-456/789
    • Contains digits, hyphen, and slash.
  3. “Quotes”
    • Contains Unicode quotation marks.
  4. A+1=2
    • Contains letters, digit, plus, and equal sign (although equal sign is not explicitly allowed, so this would not match without it).
  5. 50% off (limited time)
    • Contains digits, percent sign, space, parentheses, and letters (although percent sign is not explicitly allowed, so this would not match without it).

Example Non-Matches

  1. Hello@World
    • Contains an @ symbol, which is not allowed by the pattern.
  2. $100
    • Contains a $ symbol, which is not allowed by the pattern.
  3. abc_def
    • Contains an underscore (_), which is not allowed by the pattern.
Previous
Configure JSON
Next up
Compatibility Fixes