Content Schema

The Content Schema is a formula for representing online store content. Its purpose is to standardize how themes model user content in content sections, enabling content made with a section of one theme to be rendered by a section of a different theme. It also serves to provide a consistent editing experience to merchants.

The Content Schema is specific to content sections. It does not apply to frame and page sections.

The content section schema property

Content sections are required to define the content property in their schema. The content property works alongside the settings and blocks properties to define the customization options supported by the section.

{% schema %}
  {
    "name": <SectionName>,
    "content": <ContentSchema> | [<ContentSchema>] | false,
    "settings": [<SettingSchema>]
  }
{% endschema %}

There are three types of values for content:

  • A single content schema. In this case, the settings of the content schema are attached to the section itself and presented to the merchant as section settings. The blocks property can't be used.
  • An array of one or more content schema. In this case, each content schema defines a container of settings that can be added, removed, and reordered within the section and is presented to the merchant as a block. The blocks property can't be used.
  • The value false. In this case, the section opts out of the Content Schema. The blocks property can be used, with some limitations.

In all cases, the settings property can be used to define additional settings for the section, with some limitations.

<ContentSchema>

{
  "type": <ContentType>,
  "name": <String>,
  "config":
    "<SettingId>": {
      "label": <String>,
      "info": <String>
    }
  },
  "settings": [<SettingSchema>]
}

Each content schema must have a type.

type must be one of the supported content types. Depending on the type, the content will carry different built-in settings. See the list of content types.

name is a string describing the type of content.

config enables the content schema to override the labels and info text of the built-in settings of the content type.

settings enables the content to carry additional settings beside the built-in settings, with some limitations.

The section.content Liquid property

The section.content Liquid property lets you access a section's content configuration.

There are three types of values for section.content:

The content Liquid object

The content Liquid object represents the content and settings information of an instance of a content type added to a section. It is similar to the block object.

The content Liquid object has the following properties:

  • id: returns a unique ID dynamically generated by Shopify.
  • type: returns the type of the content.
  • settings: returns an object of the additional settings set of the content. Retrieve setting values by referencing the setting's unique ID as defined in the section schema.
  • additional properties to access information for the built-in settings of the content type, as defined in the list of content types. Unlike the content.settings object, which return the ID of resources, those properties return Liquid objects such as product and image directly.

List of content types

A content type is a set of one or more settings packaged together as one unit. They are standardized by Shopify, so that content made with a section of one theme may be rendered by a section of a different theme.

For example, the text content type is made of a title text setting and a body richtext setting. When a section accepts a text content type, it receives those two settings, either on itself or as blocks. The value of those settings can be accessed via the section.content property and content objects.

It's not possible to opt out of any of the built-in settings of content types.

<ContentType> <SettingId> <SettingType>
text title text
body richtext
image image image_picker
link url
caption richtext
external_video url video_url
cover image_picker
caption richtext
product product product
collection collection collection
article article article
blog blog blog
menu menu menu

This is not a final list of all the content types, and will be updated as they are released.

Restriction on additional settings

In addition to the built-in settings of content types, content sections can define additional settings onto themselves, their content, or their blocks. Those settings must be of one of the following types:

Content sections can't define additional settings of the following types:

This restriction ensures that content sections model user content using the standard list of content types, enabling content made with a section of one theme to be rendered by a section of a different theme.

This restriction doesn't apply to frame and page sections.

Examples

Section that accepts a single instance of the product content type, with an additional setting on the section:

{% schema %}
  {
    "name": "Featured product",
    "content": {
      "type": "product",
      "config": {
        "product": {
          "label": "Featured product"
        }
      }
    },
    "settings": [
      {
        "type": "checkbox",
        "id": "show_vendor_name",
        "label": "Show vendor name"
      }
    ]
  }
{% endschema %}

{{ section.content }} returns a "content" object.
{{ section.content.product }} returns a "product" object or blank value.
{{ section.settings.show_vendor_name }} returns a boolean.

Section that accepts multiple instances of the image content type, with an additional setting on each content instance:

{% schema %}
{
  "name": "Image gallery",
  "content": [
    {
      "type": "image",
      "name": "Image",
      "settings": [
        {
          "type": "select",
          "id": "alignment",
          "label": "Image alignment",
          "default": "center",
          "options": [
            {
              "value": "top",
              "label": "Top"
            },
            {
              "value": "center",
              "label": "Center"
            },
            {
              "value": "bottom",
              "label": "Bottom"
            }
          ]
        }
      ]
    }
  ]
}
{% endschema %}

{{ section.content }} returns an array of "content" objects.

{% for content in section.content %}
  {{ content.image }} returns an "image" object.
  {{ content.settings.alignment }} returns a string.
{% endfor %}

Section that accepts multiple instances of the image and product content types:

{% schema %}
{
  "name": "Slideshow",
  "content": [
    {
      "type": "image",
      "name": "Image slide"
    },
    {
      "type": "product",
      "name": "Product slide"
    }
  ]
}
{% endschema %}

{{ section.content }} returns an array of "content" objects.

{% for content in section.content %}
  {% case content.type %}
  {% when 'image' %}
    {{ content.image }} returns an "image" object.
  {% when 'product' %}
    {{ content.product }} returns a "product" object.
  {% endcase %}
{% endfor %}

Section that opts out of the Content Schema:

{% schema %}
{
  "name": "Newsletter",
  "content": false
}
{% endschema %}

{{ section.content }} returns false.

The richtext setting type

The richtext setting is used to add a rich text editor to a section. The richtext setting type has been updated to support additional elements in frame, page and content sections. It remains unchanged in legacy sections to not cause problems in existing themes.

The following elements are supported by the updated rich text editor:

  • Headings
  • Button-style links
  • Alignment
  • Indentation
  • Blockquote format
  • Unordered and ordered lists
  • Tables
  • Code / HTML block

Ready to start selling with Shopify?

Try it free