When to Use Group, Reference, Global, and Modular Blocks Fields in the Contentstack SaaS Content Platform

This blog post provides guidance on when to use group fields, global fields, reference fields, and modular blocks fields with the Contentstack SaaS content platform. Effective use of these data modeling features provides significant capabilities that can improve CMS user experiences as well as developer productivity and satisfaction. If you have perspectives on when to use these features, please comment on this blog post.

Selecting the Modular Blocks field type when adding a field in Contentstack

This post begins by providing some context for data modeling with headless CMS and Contentstack. For much greater detail including links to relevant resources, see the series of blog posts that begins here:

Entries and Content Types

An entry is a record in the CMS. Each entry contains values for the fields defined by the content type associated with that entry. The data model of a CMS implementation defines content types to meet requirements for their project.

In any CMS, a content type can specify a flat list of fields, resulting in a flat entry structure. For example, an entry associated with a content type that defines fields named Title and Description may appear in JSON as a flat list of keyed values as follows:

  "title": "<user data>",
  "description", "<user data>"

All CMS provide an equivalent to the Contentstack reference field type further in this blog post, but otherwise data modeling capabilities basically stop there, even if those referenced entries appear to be part of a primary entry. In this case, an individual field value in an entry can contain JSON, but not nested fields. Every individual block of content is an entry.

Some CMS support nested fields, where a field can contain other fields. Excluding the section about the reference field type, much of the remainder of this post apply largely to and uses terminology from Contentstack, though some other CMS provide similar functionality.


A block is a collection of fields. An entry is a block, where the content type of the entry defines the fields that make up the block. A block in an entry contains values for the fields specified in a block definition associated with the content type of that entry, nested within the value of a field. Group fields, global fields, and modular blocks as described in the following sections correspond to blocks nested within entries.

Group Fields

In Contentstack, a group field can contain other fields. In the CMS UI, groups appear in containers for fields. In the JSON structure, groups appear as keys that contain blocks, which are collections of keyed values. For example, if the content type for an entry defines a group field named Metadata to contain the Description field, then the JSON representation of that entry may appear as follows:

  "title": "<user data>",
  "metadata" {
    "description", "<user data>"

Just like any other field, depending on its configuration, group fields can repeat; a group field may contain multiple blocks.

  "title": "<user data>",
  "group": [
      "field ": "<user data>"
      "field": "<user data>"

Use group fields:

  • When a collection of fields repeats.
  • When a single repeating field may become a collection of repeating fields.
  • To organize related fields visually and structurally.
  • To improve CMS usability.

When to Use Global Fields with the Contentstack SaaS Content Platform

Global fields function like group fields in that they can contain nested fields, and result in an equivalent JSON structure. Multiple content types can share global field definitions. For example, if every type of page on a website contains a consistent collection of fields for metadata, then the content types for those page entries can share a global field that defines those fields.

Use global fields:

  • For any block definitions common to multiple content types.
  • When a block definitions that may become common to multiple content types.

When to Use Reference Fields with the Contentstack SaaS Content Platform

Reference fields in content types allow entries to reference other entries, allowing direct and indirect relationships between entries. Reference fields support content reuse. For example, a content type can contain a reference field that allows the CMS user to associate a different call to action with each entry.

Implement multiple content types and use reference fields:

  • To separate types of content elements that are logically distinct.
  • To allow separate management (versioning, workflow, translation, publishing, and otherwise) for different content elements.
  • To facilitate content reuse.

See also:

When to Use Modular Blocks with the Contentstack SaaS Content Platform

The Contentstack modular blocks field allows CMS users to manage a single field value that consists of several blocks, each based on a predefined structure. Consider modular blocks where you might otherwise use reference fields and separate content types, but where there are advantages to storing the data inline within a single entry rather than in separate referenced entries.

Use modular blocks:

  • To store data inline within a single entry rather than in multiple referenced entries.
  • To store a series of blocks with different structures.
  • To minimize the need to manage large collections of entries to represent a single web page.
  • To optimize use cases for CMS users and developers.

One thought on “When to Use Group, Reference, Global, and Modular Blocks Fields in the Contentstack SaaS Content Platform

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: