Schemas

Structure of a schema JSON file

A schema is a JSON file with the following required properties:

• A key that defines the type of the schema. The key must be one of the following:

  • tasticType: for Frontend components.
  • customDataSourceType: for data sources.
  • dynamicPageType: for dynamic pages.

  The value for this key is the unique identifier of the schema. The unique identifier is referenced in both the code and the studio, so it must be readable. We recommend following a naming convention such as <project>/<identifier>, for example, demo/products-list.

• name: string. The name of the schema displayed in the studio. We recommend choosing a name that studio users can understand.

• category: string. The name of the category used to group the schemas in the studio. For example, all data source schemas with this field set to Content will be grouped in the studio in the Content category section.

• icon: string. The name of the icon displayed in the studio. For example, of the icon displayed next to a data source schema name. You can choose any icon from Material icons.

• schema: array of objects. It determines the configuration sections and the related fields. For further information, see Schema.

The following is an example of a schema with the key set to customDataSourceType only for demonstration purposes.

{
  "customDataSourceType": "demo/example",
  "name": "Example schema",
  "category": "Examples",
  "icon": "info",
  "schema": [
    {
      "name": "Content API configuration",
      "fields": [
        {
          "label": "Enter Content ID",
          "field": "contentID",
          "type": "string"
        }
      ]
    }
  ]
  // Other schema properties.
}

Schema

schema is an array of objects displayed as sections in the studio, each containing the following required properties:

• name: string. The configuration section name displayed in the studio.
• fields: array of objects. It determines the fields available to the studio users to manage a configuration.

In the fields array, each object contains the following properties:

• label: string - required. The field label displayed in the studio.

• field: string - required. The unique name of the field used to access the value from the resulting data object.

  The schema sections are only used in the studio and the resulting configuration is flattened before passing to the API hub or the Frontend components. Therefore, you must ensure all field names are unique.

• type: string - required. The schema field type displayed in the studio.

• translatable: boolean - optional. It determines if the field value can be available in different languages. For more information, see Internationalization and using multiple languages for a field on the locales and translations.

• required: boolean - optional. It determines if the field is required and therefore studio users must set it.

  You still need to check if the field value is set in your Frontend component code because it might not be loaded yet (asynchronous) or the studio user ignored the warning about a required field (for example, to store a draft).

• default: string - optional. The default value you want to receive when the configuration is left empty in the studio. The default is null.

• values: array - optional. Key-value pairs to define the values of enum fields.

Schema field types

The commercetools Frontend schemas support the following field types.

Boolean

The boolean field type lets studio users use a toggle to set the field value to true or false. This field is not translatable.

{
  "name": "Width settings",
  "fields": [
    {
      "label": "Show the content full width",
      "field": "isFullWidth",
      "type": "boolean"
    }
  ]
  // Other schema properties.
}

Data source

Every dataSource field must have a dataSourceType property set to the unique data source identifier specified when creating the custom data source schema.

{
  "name": "Data sources",
  "fields": [
    {
      "label": "Product selection data source",
      "field": "productList",
      "type": "dataSource",
      "dataSourceType": "myShop/product-list",
      "default": null
    }
  ]
  // Other schema properties.
}

Encrypted

The encrypted field type lets you safely store secret information like your API credentials. The API hub stores the value after encrypting it and decrypts it when read from the backend extensions.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Enter the secret variable",
      "field": "SECRET_VARIABLE_NAME",
      "type": "encrypted",
      "translatable": false,
      "required": true
    }
  ]
  // Other schema properties.
}

Enum

The enum field type lets studio users select an option from a drop-down. The enum field type requires a values property that's an array of objects, each with a name and value pair. The name is displayed as the drop-down item text in the studio, and the value is used in the Frontend component or API hub. This field is not translatable.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Theme",
      "field": "theme",
      "type": "enum",
      "required": false,
      "values": [
        {
          "value": "dark",
          "name": "dark"
        },
        {
          "value": "light",
          "name": "light"
        }
      ],
      "default": "dark"
    }
  ]
  // Other schema properties.
}

Group

The group field type lets you group a set of input fields of different types. For example, to create product cards, it could be necessary to upload an image, enter some text, and add a link. You can bundle the image, text field, and link field in the same group.

The group field type also let the user add a variable number of the grouped fields in the range specified by the min and max properties, which can be helpful when you want studio users to add a variable number of input fields. For example, you want users to add at least one but up to five product cards.

The itemLabelField property lets you specify which field label to use as the label displayed in the component settings panel.

{
  // ...
  "schema": [
    {
      // ...
      "fields": [
        {
          "label": "Top categories",
          "field": "topCategories",
          "type": "group",
          "itemLabelField": "name",
          "min": 1,
          "max": 5,
          "fields": [
            {
              "label": "Category name",
              "field": "name",
              "type": "string",
              "translatable": false,
              "required": true
            },
            {
              "label": "Navigation tree",
              "field": "tree",
              "type": "tree"
            }
            //...
        },
        // ...
      ]
    },
  ]
  // Other schema properties.
}

To learn more about using groups, see groups in Frontend component settings

Instant

The instant field type lets studio users select a date and time. This field is not translatable.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Countdown to",
      "field": "countdownTo",
      "type": "instant",
      "default": "Fri Jul 15 2024 16:14:00 GMT+02"
    }
  ]
  // Other schema properties.
}

Json

The selected date and time are based on the time on the computer of studio users.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Teaser JSON",
      "field": "teaserJson",
      "type": "json",
      "default": null
    }
  ]
  // Other schema properties.
}

Markdown

The markdown field lets studio users enter Markdown text. By default, this field is translatable based on the locales configured for your project. For more information on using Markdown, see Using the Markdown editor.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Content",
      "field": "text",
      "type": "markdown",
      "default": "* Enter\n* some\n* Markdown",
      "translatable": true
    }
  ]
  // Other schema properties.
}

Media

The media field type lets studio users select an image from the media library and configure additional settings such as an alt text, crop ratio, and gravity-specific cropping. This field is not translatable.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Image",
      "field": "image",
      "type": "media",
      "required": true
    }
  ]
  // Other schema properties.
}

Node

The node field type lets studio users select a page folder from the page folder drop-down in the site builder and return the corresponding page folder ID. This field is not translatable.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Node",
      "field": "node",
      "type": "node",
      "required": false,
      "default": null
    }
  ]
  // Other schema properties.
}

Number, Integer, and Decimal

The number, integer, and decimal field types let studio users enter a numeric value. This field is not translatable.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Space in px (Overrides Size field)",
      "field": "spaceInPx",
      "type": "integer",
      "default": 0
    }
  ]
  // Other schema properties.
}

Reference

The reference field type lets studio users select a page folder or enter an external URL. This field is not translatable. For more information, see Working with links.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Link",
      "field": "reference",
      "type": "reference",
      "required": false,
      "default": null
    }
  ]
  // Other schema properties.
}

String

The string field type lets studio users enter one-line text. By default, this field is translatable based on the locales configured for your project.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Headline",
      "field": "label",
      "type": "string"
    }
  ]
  // Other schema properties.
}

Text

The text field type lets studio users enter multi-line text. By default, this field is translatable based on the locales configured for your project.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Teaser text",
      "field": "teaserText",
      "type": "text",
      "default": null
    }
  ]
  // Other schema properties.
}

Tree

The tree field type lets studio users select a page folder sub-tree starting from the selected page folder that a Frontend component receives. The page folder sub-tree is useful to render the navigation. This field is not translatable.

{
  // Other schema properties.
  "fields": [
    {
      "label": "Navigation tree",
      "field": "tree",
      "type": "tree"
    }
  ]
  // Other schema properties.
}

Additional information field types

To provide the studio users with information about a schema, you can add the description and image field types. These fields are shown at the top of a schema settings section in the studio. These fields are for display only and do not collect any user input.

Description

The description field type lets you display a text on the schema settings section.

{
  "schema": [
    {
      "fields": [
        {
          "type": "description",
          "text": "Enter the credentials for your commercetools Frontend project."
        }
      ]
    }
  ]
  // Other schema properties.
}

Image

The image field type lets you display an image on the schema settings section.

{
  "schema": [
    {
      "fields": [
        {
          "type": "image",
          "url": "https://commercetools.com/_build/images/logos/commercetools-logo-desktop.svg"
        }
      ]
    }
  ]
  // Other schema properties.
}

For example, the following schema definition with a description field renders as shown in the image.

{
  "schema": [
    {
      "name": "Project credentials",
      "fields": [
        {
          "type": "description",
          "text": "Enter the credentials for your commercetools Frontend project."
        },
        {
          "type": "image",
          "url": "https://commercetools.com/_build/images/logos/commercetools-logo-desktop.svg"
        },
        {
          "label": "Enter API key",
          "field": "API_KEY",
          "type": "encrypted",
          "required": true
        },
        {
          "label": "Enter APP ID",
          "field": "APP_ID",
          "type": "string",
          "required": true
        }
      ]
    }
  ]
}