# Schemas A schema is a JSON file that specifies what a user of the Studio can configure. A schema determines what and of what type the fields are for the configuration of some features from the Studio. For example, a Frontend component schema determines the fields that Studio users can set to configure the content and appearance of a Frontend component, such as a toggle to show the component on mobile or a text field to enter the label of a button. You can create a schema for the following features: - [Frontend components](/frontend-development/creating-a-frontend-component.md#create-a-frontend-component-schema) - [Data sources](/frontend-development/developing-a-data-source-extension.md#create-a-data-source-schema) - [Dynamic pages](/frontend-development/developing-a-dynamic-page-extension.md#create-a-dynamic-page-schema) - [Page folders](/frontend-development/page-folder-schema.md) - [Project settings](/frontend-development/api-hub-configuration.md#add-project-configuration-fields-to-the-project-schema) ## Structure of a schema JSON file If you are using the visual editor in the schema builder, then all the available fields and options are displayed for you. A schema is a JSON file with the following properties: - A key that defines the type of the schema. The key must be one of the following: - `tasticType` - String - Required. The name of the Frontend component. - `customDataSourceType` - String - Required. The name of the data source extension. - `dynamicPageType` - String - Required. The name of the dynamic page. 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 `/`, for example, `demo/products-list`. - `name` - String - Required. The name of the schema displayed in the Studio. We recommend choosing a name that Studio users can understand. - `category` - String - Optional. 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. We recommend setting this property to help identify the schema in the Studio. - `maxUsePerPage` - Number - Optional. The maximum number of times Studio users can add a Frontend component to the same page version or component group. It only applies to Frontend component schemas. The limit does not apply to the number of times a component group is used. Therefore, if a component group contains a component with the `maxUsePerPage` property, and a Studio user adds the component group to the same page version more times than specified by the property, a warning message does not appear. - `icon` - String - Optional. The name of the icon displayed in the Studio. For more information, see [Icon](/frontend-development/schemas.md#icon). We recommend setting this property to help identify the schema in the Studio. - `schema` - Array of objects - Required. It determines the configuration sections and the related fields. For more information, see [Schema](/frontend-development/schemas.md#schema). The following is an example of a schema with the key set to `customDataSourceType` only for demonstration purposes. ```json title="Example of schema.json" { "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. } ``` ### Icon `icon` lets you choose which icon is displayed for your schema in the Studio. You can choose any icon from [Material icons](https://fonts.google.com/icons?icon.set=Material+Icons). You can set the icon you want to use in one of the following ways: - Set the name of the icon as the icon field in the schema, for example: `"icon": "info"` - Set the icon using the Studio UI. To do this, complete the following steps: 1. Click the schema you want to set the icon for. 2. Expand the icon section. 3. Click **Edit icon**. If you edit the icon using the UI but edit the JSON schema afterwards, the icon reverts to the one set in the schema. ### Schema `schema` is an array of objects displayed as sections in the Studio, each containing the following required properties: - `name` - String. The name of the configuration section displayed in the Studio. - `fields` - Array of objects. It determines the fields available in the Studio to manage a configuration. In the `fields` array, each object contains the following required properties and other properties specific to the [schema field type](/frontend-development/schemas.md#schema-field-types): - `label` - String. The field label displayed in the Studio. - `field` - String. 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. The schema field type displayed in the Studio. #### Schema field types 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 type is not translatable. You can use the following optional properties: - `default` - Boolean. The default value for the field. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of boolean field type" { "name": "Width settings", "fields": [ { "label": "Show the content full width", "field": "isFullWidth", "type": "boolean", "default": true, "required": true } ] // Other schema properties. } ``` ##### Data source The `dataSource` field type lets you specify a [data source](/frontend-development/development-concepts.md#data-sources) for your Frontend components. You must use the required `dataSourceType` (string) property to set the unique data source identifier specified when [creating the custom data source schema](/frontend-development/developing-a-data-source-extension.md#create-a-data-source-schema). ```json title="Example of data source field type" { "name": "Data sources", "fields": [ { "label": "Product selection data source", "field": "productList", "type": "dataSource", "dataSourceType": "myShop/product-list" } ] // Other schema properties. } ``` ##### Dynamic filter Every `dynamic-filter` field must have a `dynamicFilterEndpoint` property set to the path to the [filters action handler](/frontend-development/dynamic-filters-for-data-sources-and-dynamic-pages.md#implement-the-action-to-fetch-the-filters). You can use the optional `required` (boolean) property to make the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of dynamic filters field type" { "name": "Blog search", "fields": [ { "label": "Filters", "field": "blogFilters", "type": "dynamic-filter", "dynamicFilterEndpoint": "/action/blog/filters", "required": true } ] // 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. You can use the optional `required` (boolean) property to make the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). Encryption is a compute heavy task. Only use `encrypted` fields for secret credentials. Overusing `encrypted` fields can slow down your application. ```json title="Example of encrypted field type" { // Other schema properties. "fields": [ { "label": "Enter the secret variable", "field": "SECRET_VARIABLE_NAME", "type": "encrypted", "required": true } ] // Other schema properties. } ``` ##### Enum The `enum` field type lets Studio users select an option from a drop-down. You must use the required `values` (array of objects) property, 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 type is not translatable. You can use the following optional properties: - `default` - String. The default value for the field. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of enum field type" { // Other schema properties. "fields": [ { "label": "Theme", "field": "theme", "type": "enum", "values": [ { "value": "dark", "name": "dark" }, { "value": "light", "name": "light" } ], "default": "light", "required": true } ] // Other schema properties. } ``` ##### Group The `group` field type lets you bundle a set of input fields of different types. For example, to create tiles with product images, it could be necessary to upload an image, enter the name of the image, and add a link. You can bundle the image, the name, and link fields in the same group. In your `group` fields, we recommend using the optional `itemLabelField` (string) property and the related `name` field to activate the insertion and display of group names in the **Component settings** pane of the Studio's [page builder](/frontend-studio/using-the-page-builder.md). This helps Studio users to identify groups while working in the page builder. For example, let's say you [develop a Frontend component](/frontend-development/creating-a-frontend-component.md) that lets Studio users create image tiles. The Frontend component contains the `Tiles` schema, which contains the `Tile` group, which then contains the input fields to configure the tile settings (for example, `image`). In such a case, you could use the `itemLabelField` property so that Studio users can set and see the name of tiles while working in the page builder. In the following example, the `itemLabelField` property specifies that the `name` field is used to display the tile group name. You can also use the following optional properties: - `min` - Number. The minimum number of groups that Studio users can create. For example, if you want Studio users to add at least one image tile. - `max` - Number. The maximum number of groups that Studio users can create. For example, if you want Studio users to add up to six image tiles. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of group field type" { // Other schema properties. "schema": [ { "name": "Tiles", "fields": [ { "label": "Tile", "type": "group", "min": 1, "max": 6, "required": true, "itemLabelField": "name", "field": "tiles", "fields": [ { "label": "Tile name", "field": "name", "type": "string", "required": true }, { "label": "Image", "field": "image", "type": "media", "required": true } //... ] } ] } ] // Other schema properties. } ``` When creating a tile, Studio users could set its name using the **Tile name** field. ![The Edit Tile dialog in the Studio page builder that lets Studio users edit the settings of a tile group item.](https://docs.commercetools.com/frontend-development/images/enter-group-name-in-component-settings.png) The tile names set by Studio users would then appear in the **Tiles** section of the **Components settings** pane. ![Some tile groups in the Tiles section of the Component settings pane of the Studio's page builder.](https://docs.commercetools.com/frontend-development/images/group-name-displayed-in-component-settings.png) ##### Instant The `instant` field type lets Studio users select a date and time. This field type is not translatable. You can use the following optional properties: - `default` - String. The default value for the field. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). The selected date and time are based on the time on the computer of Studio users. ```json title="Example of instant field type" { // Other schema properties. "fields": [ { "label": "Countdown to", "field": "countdownTo", "type": "instant", "default": "Fri Jul 15 2024 16:14:00 GMT+02", "required": true } ] // Other schema properties. } ``` ##### JSON The `json` field type lets Studio users enter text in [JSON](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON) format. You can use the following optional properties: - `default` - Object. The default value for the field. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of json field type" { // Other schema properties. "fields": [ { "label": "Teaser JSON", "field": "teaserJson", "type": "json", "required": true } ] // Other schema properties. } ``` ##### Markdown The `markdown` field type lets Studio users enter [Markdown](https://en.wikipedia.org/wiki/Markdown) text in the [Markdown editor](/frontend-studio/frontend-component-settings.md#markdown). You can use the following optional properties: - `default` - String. The default value for the field. - `translatable` - Boolean. Set as `true` by default. It makes the field translatable based on the locales configured for your project. For more information, see [Component-level translations](/frontend-studio/locales-and-translations-in-the-studio.md#component-level-translations). - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of markdown field type" { // Other schema properties. "fields": [ { "label": "Content", "field": "text", "type": "markdown", "default": "Enter text in Markdown", "translatable": true, "required": true } ] // Other schema properties. } ``` ##### Media The `media` field type lets Studio users select a media asset from the library and configure additional settings such as an alt text, crop ratio, and gravity-specific cropping. This field type is not translatable. You can use the optional `required` (boolean) property to make the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of media field type" { // 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 type is not translatable. You can use the following optional properties: - `default` - String. The default value for the field. You must enter a valid page folder ID as the property value. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of node field type" { // Other schema properties. "fields": [ { "label": "Node", "field": "node", "type": "node", "default": "16a9b7457a997435f0d6ea38fd52e2d1", "required": true } ] // Other schema properties. } ``` ##### Number, Integer, and Decimal The `number`, `integer`, and `decimal` field types let Studio users enter a numeric value. These field types are not translatable. You can use the following optional properties: - `default` - Number. The default value for the field. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of numeric field types" { // Other schema properties. "fields": [ { "label": "Space in px (Overrides Size field)", "field": "spaceInPx", "type": "integer", "default": 0, "required": true } ] // Other schema properties. } ``` ##### Reference The `reference` field type lets Studio users select a page folder or enter an external URL. You can use the following optional properties: - `default` - Object. The default value for the field. - `translatable` - Boolean. Set as `false` by default. It makes the field translatable based on the locales configured for your project. For more information, see [Component-level translations](/frontend-studio/locales-and-translations-in-the-studio.md#component-level-translations). - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). For more information, see [Working with links](/frontend-development/working-with-links.md). ```json title="Example of reference field type" { // Other schema properties. "fields": [ { "label": "Link", "field": "reference", "type": "reference", "default": { "type": "link", "target": "https://example.com" }, "translatable": true, "required": true } ] // Other schema properties. } ``` ##### String The `string` field type lets Studio users enter one-line text. You can use the following optional properties: - `default` - String. The default value for the field. - `translatable` - Boolean. Set as `true` by default. It makes the field translatable based on the locales configured for your project. For more information, see [Component-level translations](/frontend-studio/locales-and-translations-in-the-studio.md#component-level-translations). - `format` - String. It sets the format of the values that Studio users can enter in a field. It only applies to Frontend component schemas. The possible values are `hex` (for users to enter hexadecimal color codes), `email`, and `url`. - `minLength` - Number. The minimum number of characters for values that Studio users must enter in the field. It only applies to Frontend component schemas. - `maxLength` - Number. The maximum number of characters for values that Studio users can enter in the field. It only applies to Frontend component schemas. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of string field type" { // Other schema properties. "fields": [ { "label": "Headline", "field": "label", "type": "string", "default": "Enter your text", "translatable": true, "minLength": 1, "maxLength": 50, "required": true } ] // Other schema properties. } ``` ##### Text The `text` field type lets Studio users enter multi-line text. You can use the following optional properties: - `default` - String. The default value for the field. - `translatable` - Boolean. Set as `true` by default. It makes the field translatable based on the locales configured for your project. For more information, see [Component-level translations](/frontend-studio/locales-and-translations-in-the-studio.md#component-level-translations). - `format` - String. It sets the format of the values that Studio users can enter in a field. It only applies to Frontend component schemas. The possible values are `hex` (for users to enter hexadecimal color codes), `email`, and `url`. - `minLength` - Number. The minimum number of characters for values that Studio users must enter in the field. It only applies to Frontend component schemas. - `maxLength` - Number. The maximum number of characters for values that Studio users can enter in the field. It only applies to Frontend component schemas. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of text field type" { // Other schema properties. "fields": [ { "label": "Teaser text", "field": "teaserText", "type": "text", "default": "Enter your text", "translatable": true, "minLength": 1, "maxLength": 150, "required": true } ] // 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 type is not translatable. You can use the following optional properties: - `default` - Object. The default value for the field. - `required` - Boolean. It makes the field mandatory, Studio users will have to set a value for it. You still need to check if the field value is set in your Frontend component code because it might not be loaded yet or the Studio user ignored the warning about a required field (for example, to store a draft). ```json title="Example of text tree type" { // Other schema properties. "fields": [ { "label": "Navigation tree", "field": "tree", "type": "tree", "default": { "node": "16a9b7457a997435f0d6ea38fd52e2d1", "depth": 2 }, "required": true } ] // 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. ```json title="Example of description field type" { "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. ```json title="Example of image field type" { "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. ```json title="Example project schema for project credentials" { "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 } ] } ] } ``` ![The Project settings page with the Project Credentials section where the description is set to Enter the credentials for your commercetools Frontend project and the Enter API Key and Enter APP ID fields are filled in with values](https://docs.commercetools.com/frontend-development/images/project-credentials-schema-description-and-logo-fields.png) ## Related pages - [Area overview page with navigation](/frontend-development.md) - [Previous page: Work with links](/frontend-development/working-with-links.md) - [Next page: Page folder schema](/frontend-development/page-folder-schema.md)