String Schema

Represents a string value in the submission.

This could be used for standard text input, or a format can be provided to specify a particular type of string (e.g. a date).

When not provided, the submission value is null.

obj {
    id = "#schema"
    properties {
        string("name") {
            title = "Full name"
        }
    }
}

When to use

When collecting textual input from a user. This can be free-text, or might be more constrained based on the validation rules and format.

When not to use

When only a small number of fixed values are valid, consider using a One Of Schema instead.

Dates can be collected by specifying a format of date. This enforces that the submission is an ISO-8601 date string (YYYY-MM-DD). Depending on the kind of date required, it is possible to customise the component for a more natural user experience.

Date input

A date-input has 3 fields, for the day, month, and year.

obj {
    id = "#schema"
    properties {
        string("date") {
            title = "Date of Birth"
            format = StringSchema.Format.DATE
        }
    }
}

When to use

If the date is notable, such as a date of birth, or it is written somewhere in that format, such as on an ID card.

Date lookup

A date lookup shows a calendar view to select a date. It can be selected by providing a control of date-lookup.

obj {
    id = "#schema"
    properties {
        string("date") {
            title = "Transfer date"
            format = StringSchema.Format.DATE
            control = Control.Schema.String.DATE_LOOKUP
            placeholder = "Select a date"
            minimum = "2023-01-01"
            maximum = "2026-12-31"
        }
    }
}

When to use

If the date is relevant to the current day, or the day of the week, such as setting an appointment date.

Properties

Property	Type	Required	Description
`$id`	String	No	A unique id which can be used to refer to the schema.
`accepts`	Array<String>	No	Array of MIME types the field should accept. If null, any type of file is accepted. Wildcard MIME types are allowed, but support for them varies from platform to platform. Clients must support at least image, audio, and video. Any unrecognised MIME types will be ignored.
`additionalText`	String	No	Additional information to be displayed to the user.
`alert`	AlertLayout	No	Configure an alert which will be displayed above the UI for this schema. This can be used to provide warnings or additional information to the user, but shouldn't be used for validation. For client-side validation please see the validation available on each schema type, or see Validate Async and Action for server-side validation.
`analyticsId`	String	No	An internal id which is attached to analytics events relating to the schema. It allows you to override $id during event emission, it is not user-facing and does not have to be unique within the step.
`autocapitalization`	AutocapitalizationType	No	Sets the default capitalization mode of the devices virtual keyboard
`autocompleteHint`	Array<AutocompleteToken>	No	A list of tokens describing to the client what kind of field it is. This can enable the user agent or assistive technologies to automatically suggest or fill in information specific to the user. Values not recognised by the client will be discarded, and clients that only support single values will take the first supported value in the list.
`autocorrect`	Boolean	No	Whether the device should automatically correct the user's input. It defaults to false.
`autofillKey`	String	No	Identifies the type of data which the client can autofill for this schema. This is provided in a `.` delimited string, in the format `source.prop`, e.g `contact.email`. In this example, the client should suggest values from the `email` property on objects retrieved from the `contact` source to autofill this field. The only currently supported source is `contact`. It will inspect contacts from the native client address book (if available). Supported properties on the `contact` source are: - `givenName` - `familyName` - `fullName` - `email` - `firstLine` - `city` - `state` - `postalCode` - `countryCode`
`cameraConfig`	Any	No	Provide client-specific configuration for the camera capture experience.
`control`	String	No	An identifier which can be used to request the client use a particular UI control to represent this schema.
`default`	String	No	The default value to use for this schema. This will be overridden by a value in the model of the Step if one is provided.
`description`	String	No	A user-facing description for the schema.
`disabled`	Boolean	No	If true, the UI for this schema will not accept input, but the corresponding data will still be submitted. Defaults to false.
`displayFormat`	String	No	An input mask where a * represents a user-input character. Only the user input is submitted, not the full string.
`format`	StringSchema.Format	No	The type of data the string represents.
`help`	Help	No	Provide additional help information to the user.
`hidden`	Boolean	No	If true, no UI will be shown to the user for this schema, but the corresponding data will still be submitted. Defaults to false.
`icon`	Icon	No	An icon which the client can use to represent this schema. Icons can be shown inside text input fields.
`image`	Image	No	An image which the client can use to represent this schema. Images can be shown inside text input fields.
`inlineAlert`	InlineAlert	No	An alert that will be displayed inline with the item.
`keywords`	Array<String>	No	A list of keywords that can be used when searching or filtering items in a One Of Schema. Only applies when this schema is child schema in a One Of Schema.
`maxLength`	Int	No	The maximum length permitted for the value, if null then there is no maximum length. This is ignored if a format with a specific structure is provided (e.g. `date`).
`maxSize`	Long	No	The maximum file size in bytes. If null, file size is unlimited.
`maximum`	String	No	The maximum value permitted. If null then there is no maximum. This is used for formats with a specific structure (e.g. `date`).
`media`	Media	No	A media object (avatar, icon, image) which the client can use to represent this schema. Media can be shown inside text input fields.
`minLength`	Int	No	The minimum length permitted for the value, if null then there is no minimum length. This is ignored if a format with a specific structure is provided (e.g. `date`).
`minimum`	String	No	The minimum value permitted. If null then there is no minimum. This is used for formats with a specific structure (e.g. `date`).
`onChange`	Behavior	No	The Behavior that should be performed when the schema value changes.
`pattern`	String	No	A regular expression that the value must match to be valid. This is ignored if a format with a specific structure is provided (e.g. `date`).
`persistAsync`	PersistAsync	No
`placeholder`	String	No	A user-facing placeholder value to use for the field. This can be used to provide an example of the expected input.
`refreshStepOnChange`	Boolean	No	When true, the step will be refreshed when the value of this schema changes.
`source`	Upload.Source	No	Valid sources for the file. If null, any source is permitted.
`suggestions`	Suggestions	No	Configure suggestions that the user can select to populate the schema
`summary`	Summary.Provider	No	Configure how this schema will be summarised when included in an Array Schema.
`supportingValues`	SupportingValues	No	An object containing two strings representing two user-facing values. One being clearly more important than the other.
`tags`	Array<String>	No	An optional list of identifiers used to configure renderers.
`title`	String	No	A user-facing title for the schema.
`type`	String	Yes
`validationAsync`	ValidateAsync	No
`validationMessages`	Map<String, String>	No	An object where each property/value pair is the name of a validation property (e.g. maximum) to the user-facing error message to display if the validation fails.

Format

Formats for string values

Values

Value	Description
`base64url`
`date`	An ISO-8601 formatted date
`email`	An email address ⚠️ Deprecated - Set control property to "email" instead
`numeric`	A string where all characters are numerals or `.` ⚠️ Deprecated - Set control property to "numeric" instead

Controls

`date-lookup`

Presents a calendar for date selection.

obj {
    id = "#schema"
    properties {
        string("date") {
            title = "Transfer date"
            format = StringSchema.Format.DATE
            control = Control.Schema.String.DATE_LOOKUP
            placeholder = "Select a date"
            minimum = "2023-01-01"
            maximum = "2026-12-31"
        }
    }
}

`email`

Use an input suitable for email entry. Note that this does not provide validation. Please use the pattern property with an appropriate regex for email validation.

`numeric`

Use an input suitable for entering a string of numbers.

`password`

Use a secure control intended for entering secrets such as password.

obj {
    id = "#schema"
    properties {
        string("password") {
            title = "Password"
            control = Control.Schema.String.PASSWORD
            autocompleteHint(AutocompleteToken.PASSWORD)
        }
    }
}

`phone-number`

Use an input suitable for phone number entry.

obj {
    id = "#schema"
    properties {
        string("phone") {
            title = "Phone number"
            control = Control.Schema.String.PHONE_NUMBER
            autocompleteHint(AutocompleteToken.PHONE_NUMBER)
        }
    }
}

`sharable`

Use a component that allows sharing the provided content. e.g: images

`textarea`

Use an input suitable for multi-line text input.

obj {
    id = "#schema"
    properties {
        string("feedback") {
            title = "Please leave your comments below"
            control = Control.Schema.String.TEXTAREA
        }
    }
}

String Schema

When to use

When not to use

Formats

Date

Date input

When to use

Date lookup

When to use

Properties

Related Types

Format

Values

Controls

date-lookup

email

numeric

password

phone-number

sharable

textarea

`date-lookup`

`email`

`numeric`

`password`

`phone-number`

`sharable`

`textarea`