Schema 101

In journey steps like Login Form and Get Information from Client, schemas define the data expected from the client and also affect the UI rendering if using Mosaic's auto-generated client-side forms. You can customize the default schema by adjusting attributes, order, or preset values through the step configuration. This allows for precise control over the data structure and client-side rendering. The schema structure below outlines the supported fields and customization options.

General Structure

The schema structure follows JSON schema standards, with enhancements for client-side rendering.

Field Description
type A mandatory field according to JSON schema standards, with the value always being "object".
properties An object containing key-value pairs that describe the form fields to be rendered on the client side and the object properties to be sent by the client. Each key (e.g., email) is used in journey expressions (e.g., clientData.email), while the value is an object specifying its type and how it should be collected on the client side. Refer to the structure and examples below for more details.
required An optional array including a subset of keys from the properties object above. Any key listed here will be considered mandatory input on the client side.
order An optional array listing a subset of keys from the properties object above. This field indicates the order in which fields should be presented on the client side.

Within each object in properties, the structure includes:

Field Description
type A field specifying the data type, which can be string, number, or boolean. When rendered on the client side, boolean appears as a checkbox and number as a numeric input box. For string, it either renders as a plain text input or according to the format field described below.
title An optional field title used for client-side rendering.
format A field that guides the client side on how to render string fields. Options include password, email, phone, date, date-time, or passkey.
- password, email, phone, date, date-time determine the appropriate input widget to display based on the specified format.
- passkeys affect the Login Form step, enabling automatic passkey activation from text boxes.
For more, see the examples below.
enum An array of free-form strings. When combined with a string type, this indicates that the client should display a dropdown list instead of a plain text input. See the example below for implementation details.
Copy
Copied
{
  "type": "object",
  "properties": {
    "attribute1": {
      "title": "string",
      "type": "<TYPE>",
      "format": "<FORMAT>",
      "enum": ["value1", "value2", "value3"]
    },
    "attribute2": {}
  },
  "required": ["attribute1"],
  "order": ["attribute1", "attribute2"]
}

Examples

Below are examples of how to define schemas for various forms in journey flows. These examples illustrate different configurations for collecting user input, such as email, phone numbers, passwords, and more, in a structured and customizable way.

Collect Email

This example displays a simple form that only asks for the user's email. It could be used as the first step to collect the user identifier before proceeding to a Sign-in or Sign-up flow.

The type field is set to string, indicating the type of value received in the journey. Additionally, setting the format to email ensures the UI input validates the email on the client side.

Copy
Copied
{
  "type": "object",
  "properties": {
    "email": {
      "title": "Email",
      "type": "string",
      "format": "email"
    }
  },
  "required": ["email"]
}

Collect Email with a "Remember me" Checkbox

Building on the previous example, this example includes a "Remember me" checkbox in addition to the email input.

Copy
Copied
{
  "type": "object",
  "properties": {
    "email": {
      "title": "Email",
      "type": "string",
      "format": "email"
    },
    "remember": {
      "title": "Remember me",
      "type": "boolean"
    }
  },
  "required": ["email"]
}

Collect Email and Password

This example represents a typical login form where the username is an email, and authentication requires a password. Like the email field, the password field has a string type, but setting the format to password instructs the client to render a password input box. Additionally, including the order array ensures the fields are displayed in the desired order.

Copy
Copied
{
  "type": "object",
  "properties": {
    "email": {
      "title": "Email",
      "type": "string",
      "format": "email"
    },
    "password": {
      "title": "Password",
      "type": "string",
      "format": "password"
    }
  },
  "required": ["email", "password"],
  "order": ["email", "password"]
}

Collect Email, Phone, and Password

This example represents a simple onboarding form where we collect an email, phone number, and password (entered twice). Note that phone is not included in the required array, meaning the UI will not enforce it as a mandatory field.

Copy
Copied
{
  "type": "object",
  "properties": {
    "email": {
      "title": "Email",
      "type": "string",
      "format": "email"
    },
    "phone": {
      "title": "Phone",
      "type": "string",
      "format": "phone"
    },
    "password1": {
      "title": "Password",
      "type": "string",
      "format": "password"
    },
    "password2": {
      "title": "Retype Password",
      "type": "string",
      "format": "password"
    }
  },
  "required": ["email", "password1", "password2"],
  "order": ["email", "phone", "password1", "password2"]
}

Collect Email, Phone Number, Address, and a Security Question

In this form, we introduce the enum format type for string, which instructs the UI to display a dropdown list instead of a text input field. In this case, we use it to select a security question.

Copy
Copied
{
  "type": "object",
  "properties": {
    "email": {
      "title": "Email",
      "type": "string",
      "format": "email"
    },
    "phone": {
      "title": "Phone",
      "type": "string",
      "format": "phone"
    },
    "addr1": {
      "title": "Address line 1",
      "type": "string"
    },
    "addr2": {
      "title": "Address line 2",
      "type": "string"
    },
    "question": {
      "title": "Choose a security question",
      "type": "string",
      "enum": ["What was the name of your first pet?","What is your favorite color?"]
    },
    "answer": {
      "title": "Answer",
      "type": "string"
    }
  },
  "required": ["email", "question", "answer"],
  "order": ["email", "phone", "addr1", "addr2", "question", "answer"]
}

Full Registration Form

This example is a comprehensive registration form that collects various information, including birth date, which is specified with a format of date, and credit card information, which is set to number to enforce numeric-only data on the client side.

Copy
Copied
{
  "type": "object",
  "properties": {
    "first_name": {
      "title": "First name",
      "type": "string"
    },
    "last_name": {
      "title": "Last name",
      "type": "string"
    },
    "birthday": {
      "title": "Birthday",
      "type": "string",
      "format": "date"
    },
    "email": {
      "title": "Email",
      "type": "string",
      "format": "email"
    },
    "phone": {
      "title": "Phone",
      "type": "string",
      "format": "phone"
    },
    "password1": {
      "title": "Password",
      "type": "string",
      "format": "password"
    },
    "password2": {
      "title": "Retype Password",
      "type": "string",
      "format": "password"
    },
    "card_type": {
      "title": "Card type",
      "type": "string",
      "enum": ["Visa","American Express","Mastercard"]
    },
    "card": {
      "title": "Card number",
      "type": "number"
    },
    "sec_code": {
      "title": "Security code",
      "type": "number"
    }

  },
  "required": ["first_name", "last_name", "email", "password1", "password2"],
  "order": ["first_name", "last_name", "birthday", "email", "phone", "password1", "password2","card_type", "card", "sec_code"]
}