---
title: "Modular blocks, references or global fields?"
url: "https://developers.contentstack.com/guides/modular-blocks-references-or-global-fields"
type: "guide"
level: "beginner"
intent: "learn"
outcome: "You can pick between modular blocks, references, global fields and taxonomies for a given piece of content and explain the trade-off in querying, editing, localization and publishing."
prerequisites:
  - "A Contentstack stack where you can create content types"
  - "Basic understanding of content types and entries"
tags:
  - "content_modeling"
  - "headless"
authors:
  - "Tim Benniks"
published: "2026-11-20T09:00:00.000Z"
updated: "2026-11-15T10:56:09.205Z"
---

# Modular blocks, references or global fields?

- **Authors:** Tim Benniks
- **Published:** 2026-11-20T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:09.205Z
- **Level:** Beginner
- **Intent:** Learn
- **Tags:** content_modeling, headless

---

Every Contentstack content model comes down to a few choices repeated many times. Should this be a set of blocks inside the entry, a link to another entry, a reusable group of fields, or a label from a taxonomy? Each option changes how editors work, how many requests your front end makes, and what happens when someone publishes or translates.

This guide explains each option, compares them on the things that matter in production, and walks through three examples you will run into on almost every project.

## What you'll learn

- What modular blocks, references, global fields and taxonomies are


- Who owns the content in each case, and what gets reused


- How each option affects querying, localization and publishing


- How to model a landing page, a blog post with an author, and a product with shared SEO fields


- A decision table and flow you can use in modeling sessions



## The four options

### Modular blocks

Contentstack concept: A modular blocks field holds an ordered list of blocks. Each block follows one of the block types you define on the field.

A sections field on a landing page might allow hero, feature_grid, quote and cta blocks. Editors add the blocks they need, in the order they want. The content of every block is stored inside the entry.

If you are coming from page builders, modular blocks are the sections list. The developer defines which sections exist and how they render. The editor decides which ones to use.

### References

Contentstack concept: A reference field links an entry to one or more other entries, of the content types you allow.

A blog post with an author reference points at an entry of the person content type. The author is written once and reused by every post that references it. Change the author's bio and every post shows the new bio.

### Global fields

Contentstack concept: A global field is a reusable group of fields, defined once at the stack level and added to any content type.

An seo global field with meta_title, meta_description and canonical_url can be added to pages, blog posts and products. Change the global field's schema and every content type that uses it gets the change.

### Taxonomies

Contentstack concept: A taxonomy is a stack-level tree of terms that you attach to content types. Entries store the terms editors select.

Taxonomies are the fourth option, for classification. Levels, regions, product categories and topics are labels you filter by, not content you render. The [taxonomy querying guide](/guides/querying-content-by-taxonomy) covers how to query them.

## Ownership and reuse

The most useful question in a modeling session is: who owns this content, and where else does it appear?

- Modular blocks belong to one entry. A hero block on the homepage is the homepage's hero. If you copy it to another page, you have two heroes that drift apart.


- References point at content owned by another entry. The referenced entry is reused, and edits show up everywhere.


- Global fields reuse a structure, not values. Two products with the same seo global field each have their own meta title.


- Taxonomies reuse a vocabulary. The term beginner is defined once and every entry that selects it means the same thing.



A simple rule covers most cases: if the same content should appear in several places and stay in sync, it needs to be its own entry, which means a reference.

## Editorial experience

Modular blocks and global fields are edited in place. The editor stays in one entry and sees everything that belongs to it. This makes them the best fit for content that only makes sense in context, like the sections of one page.

References send the editor to another entry. That is the point when the content is shared, but it adds friction for content that is not. A landing page where every section is a separate referenced entry means opening ten entries to change one page, and ten entries to publish.

Taxonomies show up as a term picker. Editors choose from a controlled list and cannot invent new values, which is what you want for anything used in filters.

## Query cost

Modular blocks, global fields and taxonomy terms come back with the entry. One request, no extra parameters.

References come back as a UID and content type UID unless you ask for them to be resolved. With the TypeScript Delivery SDK, you resolve them with includeReference():

```typescript
import contentstack, { QueryOperation } from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
});

const post = await stack
  .contentType("blogpost")
  .entry("blt0123456789abcdef")
  .includeReference("author")
  .fetch();
```

References inside blocks use dot notation:

```typescript
const page = await stack
  .contentType("landing_page")
  .entry()
  .includeReference("sections.testimonial.person")
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find();
```

Every resolved reference adds entries to the response. A multiple reference field with ten items, where each item references three more entries, turns one entry into forty. Payloads grow, and so does the number of entries whose changes affect the page. Resolve only the paths a page renders, and use only() to keep the fields small.

## Localization and publishing

Modular blocks and global fields are part of the entry. They are localized with the entry, field by field, and published with the entry. One publish, one locale at a time, everything consistent.

A referenced entry has its own localized versions and its own publish state per environment and locale. That has two consequences:

- Publishing a blog post does not publish its author. If the author is not published to that environment, the resolved reference is missing from the response.


- Translating a page does not translate the entries it references. Each referenced entry is translated on its own.



Nested reference publishing helps with the first one. In the publish dialog, editors can send the entry together with its references, up to five levels deep. The [publishing explainer](/blog/releases-bulk-publish-and-nested-reference-publishing-explained) goes deeper into releases and bulk publishing.

Taxonomy terms are stored on the entry, so selecting a term publishes with the entry. The taxonomy itself is managed at the stack level.

## Worked example 1: a landing page

A marketing landing page has a hero, a few feature sections, a testimonial and a CTA. Editors want to reorder sections and add new ones without a deploy.

- Model the page as a landing_page content type with a sections modular blocks field.


- Give each block type its own fields: hero (title, image, CTA), feature_grid (group of items), cta (label, link).


- Make the testimonial block a reference to a testimonial content type, because the same quote appears on several pages.


- Add an seo global field to the content type.



The page stays one entry. Only the testimonial is shared, so only the testimonial needs includeReference().

## Worked example 2: a blog post with an author

A blog post has a title, a body, an author and a few topics.

- The author is a reference to a person entry. The same person writes many posts and has a profile page.


- Topics are taxonomy terms. You filter by them, but they have no content of their own.


- The SEO fields are a global field, shared in structure with every other page type.



The query resolves one reference (author). Topics and SEO come back with the entry.

## Worked example 3: a product with shared SEO and a category

A product has a name, price, images, SEO fields, and belongs to a category like "Rings" or "Necklaces".

- The SEO fields are a global field. Products, pages and blog posts all need the same SEO structure, but each product has its own values.


- If the category is a label used for filtering and breadcrumbs, make it a taxonomy. A category taxonomy can nest "Rings" under "Jewelry", and $eq_below returns everything below a category.


- If the category has its own landing page with a description, hero image and featured products, make it a category content type and reference it from the product.



Many projects end up with both: a taxonomy for filtering, and a category entry for the landing page content.

## Decision table

Question

Modular blocks

Reference

Global field

Taxonomy

Content shared and kept in sync across entries?

No

Yes

No

Terms only

Schema reused across content types?

No

No

Yes

Yes

Editor stays in one entry?

Yes

No

Yes

Yes

Extra query parameter needed?

No

includeReference()

No

No

Publishes with the parent entry?

Yes

No, separately

Yes

Yes

Localized with the parent entry?

Yes

No, per referenced entry

Yes

Yes

Good for filtering?

No

Possible, more work

No

Yes

## Decision flow

Use this flow when you are not sure which option fits:

flowchart TD  A[New piece of content] --> B{Is it a label you filter or group by?}  B -- Yes --> T[Taxonomy]  B -- No --> C{Does the same content appear in several entries and need to stay in sync?}  C -- Yes --> R[Reference to its own entry]  C -- No --> D{Do editors compose a variable list of sections?}  D -- Yes --> M[Modular blocks]  D -- No --> E{Is the same set of fields needed on several content types?}  E -- Yes --> G[Global field]  E -- No --> F[Plain fields or a group on the content type]## Where people get confused

### Global fields do not share content

A global field is a shared schema. If you add an seo global field to products, every product gets its own SEO values. Teams expecting "edit once, update everywhere" need a reference.

### Not everything shared needs a reference

Shared structure is a global field. Shared vocabulary is a taxonomy. Only shared content is a reference.

### Deep reference chains

A page that references sections, which reference cards, which reference authors, is three levels deep before you render anything. Every level adds query cost and publishing steps. Multi-content-type reference fields resolve up to three levels with include, and the GraphQL Content Delivery API stops at three levels too. If your model goes deeper, flatten it.

### Using modular blocks for one fixed layout

If a content type always has exactly one hero and one body, plain fields are simpler. Use modular blocks when the list of sections varies per entry.

## Limits to remember

- A content type can have up to 400 fields, counting the fields inside modular blocks, groups and global fields. See [Contentstack limits on one page](/guides/contentstack-limits-on-one-page).


- A reference field can allow up to 50 content types.


- A multiple content type reference field can hold up to 200 entries, and its references resolve up to three levels deep.


- Nested reference publishing sends references up to five levels deep.


- An entry can hold up to 25 taxonomy terms.



## Key takeaways

- Use modular blocks for content that belongs to one entry and varies in structure, like page sections.


- Use a reference when the same content must appear in several places and stay in sync. Resolve it with includeReference(), and remember it publishes and localizes separately.


- Use a global field to reuse a set of fields across content types. It shares the schema, not the values.


- Use a taxonomy for labels you filter by. Query it with taxonomies.<taxonomy_uid>.


- Keep reference chains shallow. Every level costs payload, cache surface and publishing steps.



## Next steps

- See these patterns applied to menus in [Modeling navigation in Contentstack](/guides/modeling-navigation-in-contentstack).


- Refresh the vocabulary in [Core Contentstack concepts](/guides/contentstack-0-to-100-for-developers/core-contentstack-concepts).


- Learn why this site classifies its content with taxonomies in [Taxonomies are your query layer](/blog/taxonomies-are-your-query-layer).





---

## Do this with AI

Install the cms-data-modeling-best-practices skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Content Modeler profile in MCP Profile Hub. Then ask your agent:

> Review the content types in my stack and point out modular blocks that should be global fields and reference chains deeper than three levels, with a short reason for each.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Does a global field share content between entries?

No. A global field shares a schema. Every entry that uses it stores its own values. To share values, use a reference.

### Do referenced entries publish with the parent entry?

Not automatically. A referenced entry is its own entry with its own publish state. Nested reference publishing can send references along with the parent, up to five levels deep.

### Do I need includeReference for modular blocks?

No. Modular block content is stored inside the entry and comes back with it. You only need includeReference for reference fields, including reference fields inside blocks.

### When should I use a taxonomy instead of a reference?

When the value is a label you filter by, like a level or a region. Use a reference when the thing you point at has its own content to render.

