schemas.*

Description:

This key defines your schemas, which are the structured data formats for your content files.

Appears in:

└── collections_config
    └── *
        └── schemas
            └── *

collections_config
- *
  - schemas
    *

Type:

Object

Properties:

createObject#

This key defines the path to which CloudCannon will save new files in a Collection.

CloudCannon generates "Create Paths" when you open the Review changes modal.

For more information, please read our documentation on Create Paths.

Show examplesHide examples

In this example, CloudCannon will generate a Create Path for new files in the blog Collection using the date and title structured data keys. For example, CloudCannon will generate a create path of blog/2024-10-31-spooky-getaway.md for a file with the date 31st October 2024 and the title "Spooky Getaway".

Copied to clipboard

collections_config:
  blog:
    create:
      extra_data:
        filename: '{date|year}-{date|month}-{date|day}-{title}'
      path: '[relative_base_path]/{filename|slugify}.[ext]'

{
  "collections_config": {
    "blog": {
      "create": {
        "extra_data": {
          "filename": "{date|year}-{date|month}-{date|day}-{title}"
        },
        "path": "[relative_base_path]/{filename|slugify}.[ext]"
      }
    }
  }
}

_editablesObject#

This key defines which Rich Text editors have custom configuration for the associated WYSIWYG toolbar.

For more information, please read our documentation on Rich Text editors.

Show examplesHide examples

In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    _editables:
      content:
        snippet: true

{
  "collections_config": {
    "blog": {
      "_editables": {
        "content": {
          "snippet": true
        }
      }
    }
  }
}

_editables_from_globArray<_editables_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for configuring Rich Text formatting.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.editables.yml.

You can use this key anywhere you would use the _editables key in the configuration cascade.

This key has no default.

Show examplesHide examples

In this example, we have several WYSIWYG Toolbar Configuration Files in the .cloudcannon/editables/ folder, with each file containing multiple definitions. The value of the _editables_from_glob key tells CloudCannon all files in that folder that match the glob *.cloudcannon.editables.yml.

Copied to clipboard

_editables_from_glob:
  - /.cloudcannon/editables/*.cloudcannon.editables.yml

{
  "_editables_from_glob": [
    "/.cloudcannon/editables/*.cloudcannon.editables.yml"
  ]
}

Copied to clipboard

text:
  bold: true
  italic: true
  underline: true
block:
  format: p h3
  undo: true
  redo: true
link:
  bold: true
  italic: true
  underline: true

{
  "text": {
    "bold": true,
    "italic": true,
    "underline": true
  },
  "block": {
    "format": "p h3",
    "undo": true,
    "redo": true
  },
  "link": {
    "bold": true,
    "italic": true,
    "underline": true
  }
}

_enabled_editorsArray<_enabled_editors[*]>#

This key defines which editing interfaces are available by default for files at a given level of the configuration cascade.

Whether an editing interface is available for a specific file is determined by other factors.

Values can be one of the following: visual, content, or data.

Specifying one or more editing interfaces will disable all unspecified editing interfaces.

You cannot disable the Source Editor with this key.

By default, this key is set to visual, content, and data.

If undefined at higher levels of the configuration cascade, _enabled_editables will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on the Visual Editor, Content Editor, Data Editor, and Source Editor.

Show examplesHide examples

In this example, we have enabled only the Content Editor in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    _enabled_editors:
      - content

{
  "collections_config": {
    "blog": {
      "_enabled_editors": [
        "content"
      ]
    }
  }
}

hide_extra_inputsboolean#

This key toggles whether CloudCannon will hide inputs that are not present in a Schema from the Data Editor and the sidebar of the Visual Editor and Content Editor.

Setting this key to true will hide inputs that are not present in a Schema from the Data Editor and the sidebar of the Visual Editor and Content Editor. Hiding these inputs does not delete the data. You can see non-schema data keys by opening a file in the Source Editor. This key has no effect if remove_extra_inputs is true.

Defaults to: false

Show examplesHide examples

In this example, CloudCannon will hide non-schema inputs in files using the article schema in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    schemas:
      article:
        hide_extra_inputs: true

{
  "collections_config": {
    "blog": {
      "schemas": {
        "article": {
          "hide_extra_inputs": true
        }
      }
    }
  }
}

iconstring#

This key defines the icon 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 Symbols name.

Defaults to: notes

Allowed values: 123 360 10k 10mp 11mp 12mp 13mp 14mp 15mp 16mp and 3574 more.

Show examplesHide examples

In this example, we have configured a custom icon for the article schema in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    schemas:
      article:
        icon: article

{
  "collections_config": {
    "blog": {
      "schemas": {
        "article": {
          "icon": "article"
        }
      }
    }
  }
}

_inputsObject<_inputs.*>#

This key defines which inputs are available at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _inputs will default to any values configured in the CloudCannon configuration file.

Show examplesHide examples

In this example, we have configured the date_created key as a Date and Time Input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.

Copied to clipboard

_inputs:
  date_created:
    type: datetime
    label: Date of article creation
    comment: UTC +0 timezone
    context:
      open: false
      title: Help
      icon: help
      content: This date field will automatically populate when you create an article.
    hidden: false
    disabled: true
    instance_value: NOW
    cascade: true
    options:
      timezone: Etc/UTC

{
  "_inputs": {
    "date_created": {
      "type": "datetime",
      "label": "Date of article creation",
      "comment": "UTC +0 timezone",
      "context": {
        "open": false,
        "title": "Help",
        "icon": "help",
        "content": "This date field will automatically populate when you create an article."
      },
      "hidden": false,
      "disabled": true,
      "instance_value": "NOW",
      "cascade": true,
      "options": {
        "timezone": "Etc/UTC"
      }
    }
  }
}

In this example, we have configured the blog_tags key as a Multiselect Input in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    _inputs:
      blog_tags:
        type: multiselect
        label: Blog type
        comment: Select a blog type
        context:
          open: false
          title: Help
          icon: help
          content: |
            Blog tags help our users filter articles by topic.
        options:
          values:
            - Opinion
            - Feature
            - Resource

{
  "collections_config": {
    "blog": {
      "_inputs": {
        "blog_tags": {
          "type": "multiselect",
          "label": "Blog type",
          "comment": "Select a blog type",
          "context": {
            "open": false,
            "title": "Help",
            "icon": "help",
            "content": "Blog tags help our users filter articles by topic.\n"
          },
          "options": {
            "values": [
              "Opinion",
              "Feature",
              "Resource"
            ]
          }
        }
      }
    }
  }
}

_inputs_from_globArray<_inputs_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Input configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.inputs.yml.

You can use this key anywhere you would use the _inputs key in the configuration cascade.

This key has no default.

Show examplesHide examples

In this example, we have several Input Configuration Files in the .cloudcannon/inputs/ folder, with each file containing multiple Input definitions. The value of the _inputs_from_glob key tells CloudCannon to only use the seo.cloudcannon.inputs.yml and blog-details.cloudcannon.inputs.yml files in that folder.

Copied to clipboard

collections_config:
  posts:
    path: content/posts
    icon: event
    inputs_from_glob:
      - /.cloudcannon/inputs/seo.cloudcannon.inputs.yml
      - /.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml

{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "icon": "event",
      "inputs_from_glob": [
        "/.cloudcannon/inputs/seo.cloudcannon.inputs.yml",
        "/.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml"
      ]
    }
  }
}

Copied to clipboard

seo_title:
  type: text
  options:
    required: true
    max_length: 50
seo_description:
  type: textarea
  options:
    show_count: true
    required: true
    max_length: 125
seo_image:
  type: image
  options:
    path:
      uploads: images
    accepts_mime_types:
      - image/png
      - image/jpeg
    required: true
    pattern: (?i)\.(jpe?g|png)$
    pattern_message: Please select a JPG or PNG image file

{
  "seo_title": {
    "type": "text",
    "options": {
      "required": true,
      "max_length": 50
    }
  },
  "seo_description": {
    "type": "textarea",
    "options": {
      "show_count": true,
      "required": true,
      "max_length": 125
    }
  },
  "seo_image": {
    "type": "image",
    "options": {
      "path": {
        "uploads": "images"
      },
      "accepts_mime_types": [
        "image/png",
        "image/jpeg"
      ],
      "required": true,
      "pattern": "(?i)\\.(jpe?g|png)$",
      "pattern_message": "Please select a JPG or PNG image file"
    }
  }
}

namestring#

This key defines the name displayed in the add menu when creating new files.

Defaults to a formatted version of the key.

new_preview_urlstring#

This key defines the preview URL for unbuilt pages (e.g. drafts) to another page's output URL.

The Visual Editor will load that set preview URL and use Editable Regions, or 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.

pathstring Required#

This key defines the path to the schema file relative to the root folder of the site.

previewObject#

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.

For more information about previews, please read our documentation on configuring card previews.

Show examplesHide examples

In this example, we have configured the appearance of file Cards in the Collection browser.

Copied to clipboard

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.

Copied to clipboard

_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"
          }
        }
      ]
    }
  }
}

remove_empty_inputsboolean#

This key toggles whether CloudCannon will remove empty inputs from a file using a given Schema before persisting them to your file.

Setting this key to true will remove empty inputs from a file using a given Schema before persisting them to your file. CloudCannon considers an input to be empty when its value is null, ' ', or undefined. If this key is true, empty inputs will be visible in the Data Editor and the sidebar of the Visual Editor and Content Editor, but not the Source Editor. For this key to function, you must also define _schema in your file.

Defaults to: false

Show examplesHide examples

In this example, CloudCannon will remove empty inputs in files using the article schema in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    schemas:
      article:
        remove_empty_inputs: true

{
  "collections_config": {
    "blog": {
      "schemas": {
        "article": {
          "remove_empty_inputs": true
        }
      }
    }
  }
}

remove_extra_inputsboolean#

This key toggles whether CloudCannon will remove inputs that are not present in a Schema from a file before loading it in an Editing Interface.

Setting this key to false will preserve inputs that are not present in a Schema, making them visible in the Visual Editor, Content Editor, and Data Editor, and they will be saved to your Git repository.

Defaults to: true

Show examplesHide examples

In this example, CloudCannon will preserve extra inputs in files using the article schema in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    schemas:
      article:
        remove_extra_inputs: false

{
  "collections_config": {
    "blog": {
      "schemas": {
        "article": {
          "remove_extra_inputs": false
        }
      }
    }
  }
}

reorder_inputsboolean#

This key toggles whether CloudCannon will reorder inputs in a file to match the order defined in a given Schema.

Setting this key to false will preserve the existing order of inputs in a file, regardless of the order defined in the Schema.

Defaults to: true

_select_dataObject<_select_data.*>#

This key defines defines fixed data sets to populate Select and Multiselect inputs at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _select_data will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on Select and Multiselect inputs.

Show examplesHide examples

In this example, we have configured the blog_tags Multiselect input for the blog Collection.

Copied to clipboard

collections_config:
  blog:
    _select_data:
      blog_topics:
        - Opinion
        - Feature
        - Resource

{
  "collections_config": {
    "blog": {
      "_select_data": {
        "blog_topics": [
          "Opinion",
          "Feature",
          "Resource"
        ]
      }
    }
  }
}

_structuresObject<Structure>#

This key defines which structures are available for Object inputs and Array inputs at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _structures will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on structures.

Show examplesHide examples

In this example, we want to populate an Array input in the blog Collection with Related Articles, including the name, description, and url fields.

Copied to clipboard

collections_config:
  blog:
    _structures:
      related_articles:
        style: select
        values:
          - preview:
              text:
                - key: name
              subtext:
                - key: url
            value:
              name: 
              description: 
              url:

{
  "collections_config": {
    "blog": {
      "_structures": {
        "related_articles": {
          "style": "select",
          "values": [
            {
              "preview": {
                "text": [
                  {
                    "key": "name"
                  }
                ],
                "subtext": [
                  {
                    "key": "url"
                  }
                ]
              },
              "value": {
                "name": null,
                "description": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}

In this example, we want to populate an Array input with Staff members, including the name, job_description, and profile_picture fields for all staff types, and the url field for Managers only.

Copied to clipboard

_structures:
  staff:
    style: modal
    hide_extra_inputs: false
    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": {
      "style": "modal",
      "hide_extra_inputs": false,
      "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"
          }
        }
      ]
    }
  }
}

_structures_from_globArray<_structures_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Structure configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.structures.yml.

You can use this key anywhere you would use the _structures key in the configuration cascade.

Please see our documentation on values_from_glob for defining individual Structure values in a split Configuration File.

This key has no default.

Show examplesHide examples

In this example, we have several Structure Configuration Files in the .cloudcannon/structures/ folder. The value of the _structures_from_glob key tells CloudCannon to use the staffMembers.cloudcannon.structures.yml file in that folder.

Copied to clipboard

_structures_from_glob:
  - /.cloudcannon/structures/staffMembers.cloudcannon.structures.yml

{
  "_structures_from_glob": [
    "/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml"
  ]
}

Copied to clipboard

staff:
  style: modal
  values:
    - label: Employee
      value:
        name: 
        job_description: 
        profile_picture: 
    - label: Manager
      value:
        name: 
        job_description: 
        profile_picture: 
        url:

{
  "staff": {
    "style": "modal",
    "values": [
      {
        "label": "Employee",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null
        }
      },
      {
        "label": "Manager",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null,
          "url": null
        }
      }
    ]
  }
}

Examples:

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

`schemas.*`

Table of contents