Schemas

Schemas dictate the shape of your data, which forms the base of your content. They are comprised of fields, which you may arrange in any form and quantity to perfectly match the data structure your project needs. In this article, you’ll learn how Schemas are structured and how they look and work under the hood.

Structured Data for Your Data Structures

A Schema in Mattrbld is a JSON-file consisting of am array of Fields, which will be discussed in a dedicated article, and an array of tabs which you can optionally use to cluster your fields in thematic groups, without necessarily having to stick them into a Group Field.

Expressed as a JSON document a Schema would look like this:

{
  "fields": […],
  "tabs": [
    {
      "label": "Label of the Tab",
      "groupAs": null
    }  
  ]
}

Tabs

As you can see, a tab consists of a label which will be used to label that tab in the Schema and Content Editors, as well as a groupAs property, which by default is set to null but can be used to group all fields within a tab under a common key.

The fact that Schemas are simple JSON files means that it’s easy to work with them even outside of Mattrbld, although you might want to stick to the visual Schema Editor for some time savers and reduced complexity, as the field definitions can be quite verbose. Nonetheless, you can easily use an IDE’s advanced features for example to relabel all tabs across multiple Schemas in one go.

As soon as the tabs array includes more than one tab, they will be shown at the top of the Content Editor (they are always visible in the Schema Editor).

Versioning

The fields of a Schema are independent clones (as opposed to linked copies) of the default fields and any custom fields you define, meaning that a Schema will always work even if copied to a project that does not have the custom fields defined. This may seem a bit verbose, but it allows for each field to be independently updated without jeopardising your existing Schemas and thus your content.

Every field carries a version number, which increases as changes to the field are made. You can safely keep using fields marked as “outdated” in your Schemas until you are ready to update them to their newest version, which will unlock new options and behaviours.

Impact on Content

Mattrbld tries its best to leave your content files untainted, i.e. so that they only contain properties that you have defined in your Schema. However, there are a couple of exceptions to this rule that were necessary to make things work in a predictable manner.

As such a content item with a Schema will always contain a top-level property ___mb_schema which holds a path to the assigned Schema in your project. You can use this to your advantage if you are populating a project with content via an external script and want to pre-assign a Schema to each content item. This property will also come in handy when implementing real-time content previews.

Content items created within Mattrbld, but not yet edited and thus validated, will additionally contain a ___mb_unedited property with a value of true so you can easily filter them out during your build process, as they might not yet be valid. As soon as the content item edited for the first time, this property will be deleted.

For Content Editors

The Schema of a content item also dictates what fields will be presented to Content Editors in the Content Editor interface. For example, a field with the type text will render an input or textarea depending on its configuration, while a toggle field will render a toggle.

In this sense, Schemas are also the blueprint from which the editing UI is generated, which allows you to control what fields are visible to whom and what options the editors should have within those fields.

You will learn how to create your own Schemas and configure them in the next article. If you are already familiar with the process, you may also skip to the article on validation or the field reference.