Content Schema

The Content Schema is a formula for representing online store content. Its purpose is to standardize how themes model merchant-generated 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 property to define the customization options supported by the section.

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

<ContentSchema>

{
  "static": [<StaticContentSchema>],
  "blocks": [<BlockContentSchema>]
}

The content schema property is an object with two keys: static and blocks, whose value must be an array. Both keys are optional.

  • The static key defines the content fixed on the section. Similar to section settings, static content can't be removed or added more than once.

  • The blocks key defines the content that can be added more than once, removed, and reordered within the section.

Each static and block content is a container of settings, one of which is built-in and can't be opted out of. The list of content types is standardized by Shopify.

Content sections may accept content of a given type in both static and block form, but no more than once in each form.

<StaticContentSchema>

{
  "type": <ContentType>,
  "label": <String>,
  "info": <String>,
  "settings": [<SettingSchema>]
}
Property Required? Description
type yes One of the supported content types. Depending on the type, the content will carry a different built-in setting. See the list of content types.
label no A label for the built-in setting of the content.
info no Additional information about the built-in setting to be displayed next to it in the editor. Use sparingly, as it's better to use only informative labels.
placeholder no A value for the built-in setting's placeholder text. This is for text-based content types only.
settings no An array of setting definitions. This allows the content to carry additional settings beside the built-in setting. All setting types are supported except those that were deprecated before the release of content sections.

<BlockContentSchema>

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

Block content schemas support the same properties as static content schemas, with the addition of:

Property Required? Description
name yes A name for the type of content.
limit no A number between 1 and 10. Sets a limit on how many times the content can be added to the section.

The section.content Liquid property

The section.content Liquid property lets you access a section's static and block content. It returns an object with the following properties:

  • a property for each static content, whose name is the type of the content and value a content object. For example, section.content.image for a static content of type image.

  • blocks: an array of content objects, one for each block content.

The content Liquid object

The content Liquid object represents an instance of a static or block content in a section, accessed via the section.content property. 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.
  • value: returns the value for the built-in setting of the content. Unlike the settings object, which returns the ID of resources, this property return Liquid objects such as product and image directly.
  • 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.

List of content types

Static and block content have a built-in setting which varies based on the type of the content.

The built-in setting is standardized by Shopify and can't be opted out of. This enables content made with a section of one theme to be rendered by a section of a different theme.

<ContentType> <SettingType>
richtext richtext
image image_picker
external_video video_url
product product
collection collection
blog blog
article article
menu link_list
html html
custom n/a

The custom content type has no built-in setting. It's intended to be extended with additional settings. Use sparingly, as this type of content will not work across themes.

Restriction on additional section settings

In addition to static and block content, content sections can define additional settings onto themselves using the settings schema property. 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 use 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 the additional settings of static and block content, nor to frame and page sections.

Examples

Section that has a fixed product, with an additional setting on the section:

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

{{ section.content.product.value }} returns a "product" object, or a blank value when no product has been selected.

{{ section.settings.show_vendor_name }} returns a boolean.

Section that accepts multiple images, with an additional setting on each image:

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

{% for content in section.content.blocks %}
  {{ content.value }} returns an "image" object, or a blank value when no image has been selected.

  {{ content.settings.alignment }} returns a string.
{% endfor %}

Section that accepts multiple images and products:

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

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

Section that has a fixed image and accepts multiple products:

{% schema %}
{
  "name": "Shop the look",
  "content": {
    "static": [
      {
        "type": "image",
        "label": "Featured image"
      }
    ],
    "blocks": [
      {
        "type": "product",
        "name": "Product"
      }
    ]
  }
}
{% endschema %}

{{ section.content.image.value }} returns an "image" object or a blank value.

{% for content in section.content.blocks %}
  {{ content.value }} returns a "product" object or a blank value.
{% endfor %}

Section that accepts no content:

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

Ready to start selling with Shopify?

Try it free