A schema is a predefined template that determines what should populate a collection file. You can configure several schemas for each collection, creating a list of file templates for you and your team.
This article covers all the keys available for schema configuration. To learn more about schemas, read our documentation on creating a schema.
Each entry in schemas has the following options available:
The create path definition to control where new files are saved to inside this collection. Defaults to [relative_base_path]/{title|slugify}.md.
Read more details for create when choosing where to create new files.
Sets the behavior when editing existing files with inputs not present in the schema with remove_extra_inputs set to false. Defaults to false. Has no effect if remove_extra_inputs is true.
If true, non-schema inputs are hidden in the Data Editor.
If false, non-schema inputs are visible in the Data Editor.
Displayed in the add menu when creating new files, also used as the icon for collection files if no other preview is found. Must be a Material Icon name. Defaults to notes.
Displayed in the add menu when creating new files. Defaults to a formatted version of the key.
Preview your unbuilt pages (e.g. drafts) to another page’s output URL. The Visual Editor will load that set preview URL and use the Data Bindings and Previews to render your new page without saving.
For example new_preview_url: /about/ will load the /about/ URL on new or unbuilt pages in the Visual Editor.
The path to the schema file. Relative to the root folder of the site. Required.
Controls whether or not inputs are sorted to match the schema when editing existing files. Defaults to true.
Non-schema inputs are ordered after schema inputs if not removed with remove_extra_inputs.
Sets the behavior when saving files with empty inputs. Defaults to false.
If true, empty inputs are removed before persisting the data to the source file.
If false, empty inputs are persisted in the source file.
Removed inputs are available for editing again provided they are in the matching schema file. Inputs are considered empty if the value is null, undefined or ''.
Sets the behavior when editing existing files with inputs not present in the schema. Defaults to true.
If true, non-schema inputs are removed before the editor loads, and subsequently removed from the source file if saved.
If false, non-schema inputs are either hidden or visible in the editor depending on hide_extra_inputs, but still kept in the source file on save.
If any inputs conflict with schema (e.g. a file's title is a string and the schema's title is an object), the schema version takes priority.
This key defines the appearance of a Card. You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.
The following nested keys are available:
textsubtexticonicon_coloricon_background_colorimagemetadatagallery
This key defaults to:
preview:
text:
- key: title
- key: name
icon:
- key: icon
For more information about previews, please read our documentation on configuring card previews.
Show exampleHide example
In this example, we have configured the appearance of file Cards in the Collection browser.
collections_config:
blog:
preview:
text:
- key: title
subtext:
- key: author
icon: edit_note
icon_color:
- key: color
- '#ff0000'
image:
- key: image
metadata:
- template:
- url
- icon: event
text:
- template: Published on {date|date_long}
gallery:
- key: featured_image
{
"collections_config": {
"blog": {
"preview": {
"text": [
{
"key": "title"
}
],
"subtext": [
{
"key": "author"
}
],
"icon": "edit_note",
"icon_color": [
{
"key": "color"
},
"#ff0000"
],
"image": [
{
"key": "image"
}
],
"metadata": [
{
"template": [
"url"
]
},
{
"icon": "event",
"text": [
{
"template": "Published on {date|date_long}"
}
]
}
],
"gallery": [
{
"key": "featured_image"
}
]
}
}
}
}In this example, we have configured the appearance of Cards in inputs using the Structure staff.
_structures:
staff:
values:
- value:
_type: Employee
name:
job_description:
profile_picture:
preview:
text:
- key: name
- Employee
subtext:
- key: job_description
- Description of position
image:
- key: profile_picture
icon: support_agent
- value:
_type: Manager
name:
job_description:
profile_picture:
url:
preview:
text:
- key: name
- Manager
subtext:
- key: job_description
- Description of position
image:
- key: profile_picture
icon: face
{
"_structures": {
"staff": {
"values": [
{
"value": {
"_type": "Employee",
"name": null,
"job_description": null,
"profile_picture": null
},
"preview": {
"text": [
{
"key": "name"
},
"Employee"
],
"subtext": [
{
"key": "job_description"
},
"Description of position"
],
"image": [
{
"key": "profile_picture"
}
],
"icon": "support_agent"
}
},
{
"value": {
"_type": "Manager",
"name": null,
"job_description": null,
"profile_picture": null,
"url": null
},
"preview": {
"text": [
{
"key": "name"
},
"Manager"
],
"subtext": [
{
"key": "job_description"
},
"Description of position"
],
"image": [
{
"key": "profile_picture"
}
],
"icon": "face"
}
}
]
}
}
}Schemas now support the new preview option. Read our migration guide if you are still using the old options: text_key, subtext_key, image_key and image_size.