The input Element

The input element can be seen as a representation of the HTML <input /> element. It is structured as follows:

{
    "type": "input",
    "tags": Array<String>,
    "version": String,
    "key": String,
    "data_type": ?Enum<'PNO', 'IBAN', 'ORGANIZATION_REGISTRATION_ID', 'UNKNOWN'>,
    "password": Boolean,
    "label": ?String,
    "placeholder": ?String,
    "prefill_value": ?String,
    "read_only": Boolean,
    "mask": ?Array<String>,
    "validator": ?{
        "min_length": ?Integer,
        "max_length": ?Integer,
        "required": ?Boolean,
        "min_value": ?Integer,
        "max_value": ?Integer,
        "numeric_only": ?Boolean,
        "char_whitelist": ?Array<Char>,
        "char_blacklist": ?Array<Char>,
        "pattern": ?String,
        "pattern_format": ?String
    }
}

data_type Enum, optional, since v1.2.0

The optional data_type property defines the type of data the input is asking for.

  • UNKNOWN - This is the default of the data_type property where the data type is unknown or does not match any other values of this enumeration.
  • PNO - This indicates that the input shall hold a swedish personal identity number (Swedish: personnummer).
  • IBAN - This indicates that the input shall hold an international bank account number.
  • ORGANIZATION_REGISTRATION_ID - This indicates that the input shall hold organization registration id(s).

As we may add additional values later on we suggest mapping unhandled values to the UNKNOWN-enum. We do not consider adding new values to the data-type-property a breaking change to the API as handling them is entirely optional.

password Boolean, always present, since v1.0.0

The password property contains a boolean that indicates if the input contains sensitive consumer data. It is recommended to not show the clean input value. For example show * instead.

An input element with password set to true and label set to "Password" could look like this: Input with password=true

label String, optional, since v1.0.0

The label property represents a caption for the input.

placeholder String, optional, since v1.0.0

The placeholder property specifies a short hint that describes the expected value for the input element.

prefill_value String, optional, since v1.0.0

The prefill_value property sets a value to the input element at initialization. If the consumer does not change the value of the input the prefill_value is submitted as the value.

An input element with prefill_value and label set could look like this: Input with label and prefillValue

read_only Boolean, always present, since v1.0.0

If the value of the read_only property is true the value of the input can not be changed by the consumer.

An input element with prefill_value and label set and read_only set to true could look like this: Disabled input with prefillValue

mask String[], optional, since v1.0.0

The optional mask property enables us to set a specific mask for the input element. The syntax of mask is similar to the text-mask syntax.

An input element with mask set to ['(', /[1-9]/, /[1-9]/, /[1-9]/, /[1-9]/] and a label could look like this: Masked input

validator Object, optional, since v1.0.0

The validator property may contain several rules for the input element to be validated against.

validator.min_length Integer, optional, since v1.0.0

Specifies the minimum number of characters allowed.

validator.max_length Integer, optional, since v1.0.0

Specifies the maximum number of characters allowed.

validator.required Boolean, optional, since v1.0.0

Specifies that the value cannot be null or empty.

validator.min_value Integer, optional, since v1.0.0

Specifies the minimum value for numeric values.

validator.max_value Integer, optional, since v1.0.0

Specifies the maximum value for numeric vaules.

validator.numeric_only Boolean, optional, since v1.1.0

Specifies whether or not only digits ([0-9]) are allowed.

The default value for this validation is false.

validator.numeric Boolean, optional, since v1.0.0

[deprecated]

Specifies if numbers ([0-9]) are allowed symbols.

The default value for this validation is true.

validator.letters Object, optional, since v1.0.0

[deprecated]

Specifies if (upper- and/or lowercase) letters are allowed.

The default value for this validation is { uppercase: true, lowercase: true }.

validator.symbols Boolean, optional, since v1.0.0

[deprecated]

Specifies if characters that are not numbers ([0-9]), letters or whitespace characters are allowed.

The default value for this validation is true.

validator.char_whitelist Char[], optional, since v1.0.0

Specifies an array of allowed characters.

Characters in the char_whitelist array override all but the pattern validation rule.

validator.char_blacklist Char[], optional, since v1.0.0

Specifies an array of disallowed characters.

validator.pattern RegEx, optional, since v1.0.0

Specifies a RegEx pattern which the value must match, regardless of the specifications made in other validation rules.

pattern_format String, optional, since v1.0.0

A human-readable pattern-format, which can be shown to the consumer if the input is invalid because of the pattern-validation.

Conflicting Rules

Every validation rule that is set must be applied. That means that it is possible to have conflicting validation rules, hence it is important to know how and in which order the validation rules apply.

Regardless of all other rules - if set - the pattern rule must always be adhered to, for example, if char_whitelist is set to ["A", "B"] and pattern is set to C[0-9]+, then the input B2345 is not valid, because it does not match the pattern.

Additionally, characters in the char_whitelist array override all but the pattern validation rule, for example, if numeric_only is set to true and char_whitelist is [','], then , is still a valid character.

Validation Examples

Description Example
Account numbers.

Valid examples:
123456
12345678

Invalid examples:
123 (min_length)
123 456 78 (numeric_only)
12-34-56-78-00 (numeric_only, max_length)

Account numbers are often used in the authentication process.
{
    "min_length": 4,
    "max_length": 12,
    "required": true,
    "numeric_only": true,
}
Login via email address.

Valid examples:
test@klarna.com
test3account@klarna.com
test.account+bank@klarna.com

Invalid examples:
test@klarnacom (pattern)
test@email@klarna.com (pattern)
@klarna.com (pattern)

Some bank accounts require a login via email address. In this example `pattern` is used to validate the input.
{
        "required": true,
        "char_blacklist": ["/", "\", "#", "*"]
        "pattern": "^[^@]+@[^@\.]+\.[^@]+$",
        "pattern_format": "email@adress.com"
}
National identification number in Sweden.

Valid examples:
8112289874
811228-9874
811228+9874
19811228-9874

In this example, we allow only digits but additionally permit the hyphen and plus symbol via the whitelist. Since the first two numbers and the symbol is optional, we define a length of 10-13 to be valid.
{
    "min_length": 10,
    "max_length": 13,
    "required": true,
    "numeric_only": true,
    "char_whitelist": ["-", "+"]
}
German IBAN validation.

Valid examples:
DE89 3704 0044 0532 0130 00
DE89370400440532013000

Invalid examples:
370400440532013000 (min_length)
AT3704004405320130000000 (numeric_only)
89370400440532013000DD (pattern)

Spaces and a length between 22 and 27 chars are valid. Furthermore only digits are allowed, except the letters "D" and "E". With the pattern we additionally force a specific order.
{
    "min_length": 22,
    "max_length": 27,
    "required": true,
    "numeric_only": true,
    "char_whitelist": [" ", "D", "E"],
    "pattern": "^DE[0-9\s]{20,25}$",
    "pattern_format": "DE00000000000000000000",
}
British sort codes.

Valid examples:
123456
12-34-56

Invalid examples:
12/34/56 (numeric_only, pattern)
{
    "min_length": 6,
    "max_length": 8,
    "required": true,
    "numeric_only": true,
    "char_whitelist": ["-"],
    "pattern": "^\d{2}-?\d{2}-?\d{2}$",
    "pattern_format": "12-34-56"
}
Value range.

Valid examples:
50

Invalid examples:
100 (max_value)

The numeric value must be between 18 and 99.
{
    "min_value": 18,
    "max_value": 99,
    "numeric_only": true,
}

Example

{
    "type": "input",
    "key": "input1",
    "version": "1.0.0",
    "tags": [],
    "password": false,
    "label": "Label",
    "placeholder": "",
    "prefill_value": "prefilled",
    "read_only": false,
    "validator": {
        ...
    }
}

Returning the value of the input Element

The value sent back to the server for the input element has to be a string.

The following example first depicts the received form and then the unencrypted response to it:

{
    "form_identifier": "ab12c34d-e45f-6789-0a12-3bc4de567fa",
    "version": "1.0.0",
    "elements": [
        {
            "type": "input",
            "key": "input1",
            "version": "1.0.0",
            "tags": [],
            "data_type": "UNKNOWN",
            "password": false,
            "label": "Name",
            "read_only": false
        }
    ]
}
{
    "form_identifier": "ab12c34d-e45f-6789-0a12-3bc4de567fa",
    "data": [
        {
            "key": "input1",
            "value": "John Doe"
        }
    ]
}

Changelog


1.2.0 - 08.09.2021

  • Adds InputFormElement#data_type

1.1.0 - 16.01.2020

  • updated validation

The classification of a character as a letter or a symbol depends on the alphabet of the language it is used in. For example in the Greek alphabet the character α is considered to be a letter, however in the English alphabet α can be classified as a symbol. In order to avoid these ambiguities in version 1.1.0 the "numeric", "letters" and "symbols" validation properties were deprecated and will be removed in the future. Additionally the "numeric_only" validation property was added.


1.0.0 - 01.02.2019

  • initial version

results matching ""

    No results matching ""