Frontastic schemas
A Frontastic schema is a JSON file that defines which data is collected for the schema from the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. and the API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code..
A schema can be for:
- Frontastic components
- Dynamic pages
- Page folders
- Project settings
- Data sources
In this article, we'll go through the general schema structure for all our schemas, schema field types, and how to access the data.
General schema structure
The basic structure of a schema is as follows:
{
"<schema>Type":"<customer>/<project>/identifier",
"name":"Name display in Frontastic studio",
"category":"Category type to display in the Frontastic studio",
"icon":"Icon name that displays in the Frontastic studio",
"schema":[
{
// ....
}
]
}
The <schema>Type
is the most important piece as it connects the schema to the React component in your project and they must be identical to the mapping defined there.
The name
is also important because this is what the user sees in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`..
The category
can be whatever you choose to organize your schemas in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`..
The icon
can be used to define a speaking icon from Material icons.
Schema section
The schema
section is an array of configuration sections.
These are displayed in different parts of the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. For example, for Frontastic componentsFrontastic components - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., these are displayed in the component editorcomponent editor - An interface (usually a panel) where you can adjust the different display settings of your Frontastic component, for example, an image, a title, and so on. panel.
{
// ...
"schema": [
{
"name": "First section in Frontastic studio",
"fields": [
{
"label": "Label in Frontastic studio",
"field": "identifierUsedToAccessFieldInDataProp",
"type": "string"
},
// ...
]
},
{
"name": "Second section in Frontastic studio",
"fields": [
{
"label": "Label for field in Frontastic studio",
"field": "fieldIdentifierMustBeUnique",
"type": "string"
},
// ...
]
}
]
}
You can move around fields between these sections as you like because the resulting data
property will be flat (without the sections). They're only for visualization purposes in the studio. That also means that every field identifier (see below) must be unique across the entire schema. The only exceptions are fields that are part of a group
(also see below).
Each schema
section has a name
(the section headline in the component editorcomponent editor - An interface (usually a panel) where you can adjust the different display settings of your Frontastic component, for example, an image, a title, and so on. panel) and a number of fields
.
Each object in fields
consists of a similar structure which can slightly differ depending on the type
of the field, for example:
{
"tasticType": "<projectName>/<componentName>",
"name": "<componentName>", // this will be visible in the Frontastic studio
"icon": "{select from https://material.io/resources/icons/?style=baseline}",
"category": "<categoryType>", // this should be the category type of your Frontastic component but you can name it as you wish
"schema": [
{
"name": "Data source", // this will be visible in the Frontastic studio and you can name this what you like
"fields": [
{
"label": "Custom data source", // this is what's displayed in the Frontastic studio
"field": "someDataSource", // this is the identifier used to access the field in the data prop
"type": "stream", // this must be a type of "stream"
"streamType": "<yourCompanyName>/<dataSourceName>", // this must match the customDataSourceType in your data source schema
"default": null
}
]
}
]
}
{
"customDataSourceType": "<yourCompanyName>/<dataSourceName>",
"name": "<New data source>", // this will be displayed in the Frontastic studio
"category": "Content", // this should be the category type of your data source but you can name it as you wish
"icon": "source", // you can choose any icon from material icons (select from https://material.io/resources/icons/?style=baseline)
"schema": [
{
"name": "Configuration", // this will be visible in the Frontastic studio and you can name this what you like. You can have as many sections of the schema as you wish
"fields": [
{
//Required fields
"label": "Query", // this is what's displayed in the Frontastic studio
"field": "query", // this is the identifier used to access the field in the data prop
"type": "text", // this tells the Frontastic studio what field type to display
//Optional fields
"default": "",
"required": "true", // set to true if the data source is required for your component, the user of the studio will be warned if a data source isn't selected.
"translatable": false
}
]
}
]
}
Each field has a label
which is displayed to the user as the prompt to insert some information.
The property field
determines how you can access the field in the data prop. Remember that field identifiers must be unique across a schema.
The type
determines what kind of information should be input by the user in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. We'll go through these in the next section of this article.
The remaining properties of a field are optional and help you to configure the behavior of the field in the studio:
translatable
: Determines if the field value should be available in different languages (see the internationalization article for more information. The default of this setting depends on the field type (see below).required
(default:false
): If the setting is mandatory in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. You'll still need to check if the value is set in your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. code because it might not be loaded yet (asynchronous) or the user in the studio ignored the warning about a mandatory setting (for example, to store a draft).default
(defaultnull
): Define a custom default value you want to receive when the config is left empty in the studio.
Schema field types
For the field type
, we have certain options you can use:
string
ortext
boolean
markdown
number
orinteger
ordecimal
enum
media
node
reference
tree
json
dataSource
Simple field types
There are a number of simple field types that are supported by Frontastic to allow different configuration inputs. The more complex types (stream
, group
) are explained further below.
Field type | Default | Description | Example of how it looks in the studio |
---|---|---|---|
String |
| 1-line input field. | |
Text |
| Multi-line input field. | |
Markdown |
| Allows the user to write simply formatted text using Markdown (see our using the markdown editor article for more information). You'll receive the raw Markdown string and can render it in your component using | |
Number | Not translatable | Lets the user input a numeric value. | |
Enum | Not translatable | Presents a select box to pick a single value from it. The selectable values are set through the additional property | |
Boolean | Not translatable | A simple switch that returns | |
Media | Not translatable | Lets the user select an image from the Frontastic media library and configure some additional settings such as an | |
Node | Not translatable | Lets the user select a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. from the page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. tree in the site buildersite builder - An interface that you work with to build your commerce site. Previously known as `stage`. and returns the corresponding page folder ID. You can use the | |
Reference | Not translatable | A reference can either be a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. (like from the | |
Tree | Not translatable | The user can select a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. in the site buildersite builder - An interface that you work with to build your commerce site. Previously known as `stage`. and you'll receive the entire sub-tree of page folderspage folders - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. that starts there. This is especially handy if you want to render a navigation. | |
JSON | Not translatable | This field type is meant for copy and paste of complex information (for example, exports from other systems). You can ask users to paste some JSON and will receive it automatically parsed to an object. |
Code examples for each type:
//...
"fields": [
{
"label": "Teaser text",
"field": "teaserText",
"type": "text",
"default": null
},
]
//...
//...
"fields": [
{
"label": "Label",
"field": "label",
"type": "string"
},
]
//...
//...
"fields": [
{
"label": "Content",
"field": "text",
"type": "markdown",
"default": "* Enter\n* some\n* Markdown",
"translatable": true
},
]
//...
//...
"fields": [
{
"label": "Space in px (overrides size field)",
"field": "spaceInPx",
"type": "integer",
"default": ""
}
]
//...
// ...
"fields": [
{
"label": "Size",
"field": "size",
"type": "enum",
"required": false,
"values": [
{
"value": "xxs",
"name": "Extra extra small (4 px)"
},
{
"value": "xs",
"name": "Extra small (8 px)"
},
{
"value": "sm",
"name": "Small (12 px)"
},
{
"value": "md",
"name": "Medium (16 px)"
},
{
"value": "lg",
"name": "Large (20 px)"
},
{
"value": "xl",
"name": "Extra large (24 px)"
}
],
"default": "xl"
},
//...
//...
"fields": [
{
"label": "Whole tile clickable",
"field": "isClickable",
"type": "boolean",
"default": false
},
]
//...
// ...
{
"name": "Image",
"helpText": "Customize your image",
"fields": [
{
"label": "Image",
"field": "image",
"type": "media",
"required": true
}
]
},
//...
//...
{
"label": "Node",
"field": "node",
"translatable": false,
"required": false,
"type": "node",
"default": null
},
//...
//...
{
"label": "Link",
"field": "reference",
"translatable": false,
"required": false,
"type": "reference",
"default": null
},
//...
//...
{
"label": "Navigation tree",
"field": "tree",
"type": "tree"
},
//...
//...
{
"label": "Teaser JSON",
"field": "teaserJson",
"type": "json",
"default": null
}
//...
Data source fields
The field type stream
is special in the sense that you won't receive the user entered configuration, but the result from a data source query.
For example, if you havestreamType: product-list
, the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. user will be able to filter products from the commerce backend by various criteria. In your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., you'll simply receive the products that are returned by this query.
Every field of type stream
needs a streamType
parameter:
//...
{
"name": "Stream selection",
"fields": [
//...
{
"label": "Data source",
"field": "data source",
"type": "stream",
"streamType": "product-list",
"default": null
}
//...
]
},
//...
It'll display as in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. as below:


As you're creating a schema for a data source, the possible values for streamType
need to match what you've inputted in your data source schema.
Group inputs for Frontastic components
In some cases, a single input isn't enough. Then you typically don't want to have multiple fields like image1
, image2
, image3
but use a field of type group
to let the user in the studio create a flexible number of group elements as values for the field.
The elements of a group
can contain any number of fields again. The basic configuration of a group
looks like this:
{
// ...
"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"
}
//...
},
// ...
]
},
]
}
This schema creates a group
of category
fields. The user in the studio can add a number of name
items (at least 1, up to 5, min
/max
are optional) in the group
and as the value, you receive an array of these elements in your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code..


Then if you click the edit icon on a country or + Add countries, you'll get pop-up settings:


Help text
You can provide additional information to your users in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. by using the field types description
and image
. In contrast to normal fields, these don't expect the label
and field
properties, but only type
plus their specific value properties. As there's:
{
// ...
"schema": [
{
// ...
"fields": [
{
"type": "description",
"text": "I will be displayed in Frontastic studio as help."
},
{
"type": "image",
"url": "https://example.com/some/image.png"
},
// ...
]
},
]
}
Images can, for example, be hosted in your project or an external HTTPS secured file hosting.
You can also use helpText
which displays at the top of the section and appears on hover:
//...
{
"name": "Image",
"helpText": "Customize your image",
"fields: [
//...
}
//...
Best practices
When you first create a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. schema only make configurable what really needs to be configured in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. In some cases, it means that nothing will be configurable. For example, the checkout Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. is only placed on the page and the code takes care of the rest. It's only when your team needs something to be configurable should you add it into your schema.
If you ever add any new configurations to an existing Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., they must be optional and set to a default that will result in the old behavior (for example, false
in the example above).
Copy the schema of your latest and most simple Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. or a similar Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. to what you want to create as a starting point for your new schema. Test it to make sure it works and then tweak it to how you want it. That way you don't have to rewrite a lot of code, you keep the same format and conventions, and you know how it'll behave.
Keep as much business logic outside of the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. itself and put that into the patterns or explicit logic components. Use the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. as a data layer to feed the components. It might even be a good idea to translate the data structure coming from Frontastic into your own semantic data structure to increase the re-use of your components.
When deciding how to slice up a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., it's sometimes best to make one big block in the first instance and then refactor only if you need to make smaller parts configurable. Think about how it will be used and how it makes sense from a user point of view. If it makes sense from the get-go to make 2 (or more) smaller Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., then make it like that. But if you're not sure how to split it up, make 1 big one. It'll save you set up time and you won't have to think about so many possibilities to account for in your code. You can always cut it down in the future. You can even use our grid system within a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., which will then make it easier when refactoring and will make it all look the same even if you're using 1 big Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. versus 4 small Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code..
In general, take each Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. on a case by case basis. In some cases, some of these best practices won't work for the individual Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. you're creating as it's unique and how you handle it is unique.
If you want to, you could limit the number of products that will be displayed to your customers in a product slider, or add a title to it, or even a description. You can add all these things and more into the schema of your component and make them configurable by the users of the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`..
Updated 17 days ago