# Global fields - reusable field groups

### About this export

| Field | Value |
| --- | --- |
| **content_type** | lesson |
| **platform** | contentstack-academy |
| **source_url** | https://www.contentstack.com/academy/courses/content-modeling-with-contentstack/global-fields-reusable-field-groups |
| **course_slug** | content-modeling-with-contentstack |
| **lesson_slug** | global-fields-reusable-field-groups |
| **markdown_file_url** | /academy/md/courses/content-modeling-with-contentstack/global-fields-reusable-field-groups.md |
| **generated_at** | 2026-08-03T11:49:37.821Z |

> Part of **[Content Modeling](https://www.contentstack.com/academy/courses/content-modeling-with-contentstack)** on Contentstack Academy. **Academy MD v3** — structured for retrieval; no quiz or assessment keys.

<!-- ai_metadata: {"lesson_id":"04","type":"text","duration_minutes":1,"topics":["Global","fields","reusable","field","groups"]} -->

#### Lesson text

# Global fields: reusable field groups

> **TL;DR**
> 
> *   Global fields define a group of fields once and embed it across multiple content types -- changes propagate everywhere automatically.
> *   The API output for a global field is identical to a group field; the difference is purely in how the schema is managed.
> *   Use global fields for structures that appear in 3+ content types with identical shape (SEO metadata, addresses, CTAs).
> *   Modifying a global field is a cross-cutting change -- audit all consuming content types and frontends before editing.

SEO metadata follows the same pattern on every content type in your stack: a meta title, a meta description, an Open Graph image, and an optional canonical URL. Without global fields, you would recreate those four fields manually on every content type, with no guarantee that the UIDs, validation rules, or help text stay consistent. Contentstack's Global Fields solve this by letting you define a group of fields once and embed it across as many content types as you need - and when you update the global field definition, the change propagates everywhere it is used.

## What global fields are

A global field in Contentstack is a reusable, centrally managed set of field definitions. You create it once under Settings > Global Fields in your stack, and then you add it as a field in any content type. Visually, it appears in the entry editor as an expandable group of fields, similar to a regular Group field. Structurally, however, it is fundamentally different: a global field is defined in one place and referenced by content types, whereas a Group field is defined inline within a single content type.

Think of global fields as shared components in a design system. Just as a design system defines a Button component once and uses it across every page, a global field defines a set of fields once and uses them across every content type that needs them.

## Creating a global field

To create a global field in Contentstack:

1.  Navigate to Settings > Global Fields in your stack.
2.  Click + New Global Field.
3.  Enter a title (e.g., "SEO Metadata") and a UID (e.g., seo\_metadata).
4.  Add fields to the global field definition just as you would add fields to a content type.
5.  Save the global field.

Here is an example of an SEO Metadata global field with four fields:

Field label

Field UID

Field type

Notes

Meta Title

meta\_title

Single Line

Max 60 characters

Meta Description

meta\_description

Multi Line

Max 160 characters

OG Image

og\_image

File

Recommended 1200x630

Canonical URL

canonical\_url

Single Line

Full URL, optional

Once saved, this global field becomes available when editing any content type. In the content type builder, you select Global Field from the field type list and choose "SEO Metadata." The four fields appear inside the content type as a nested group, using the exact UIDs and validation rules you defined.

## How global fields differ from group fields

Group fields and global fields look identical in the entry editor - both appear as expandable sections containing nested fields. The difference is in how they are managed and what happens when you need to make changes.

Characteristic

Group field

Global field

Definition location

Inside a single content type

Centrally, under Settings > Global Fields

Reusability

Cannot be shared across content types

Used by any number of content types

Updates

Changing it affects only the one content type

Changes propagate to all content types that use it

Schema ownership

Owned by the content type

Owned by the global field definition

API output

Nested JSON object

Nested JSON object (same structure)

The API representation is identical. A Group field called seo with fields meta\_title and meta\_description produces the same JSON structure as a Global Field called seo\_metadata with the same fields. The difference is purely in how the schema is managed, not how the data is delivered.

This means frontend developers do not need to know whether a nested object in the API response came from a Group field or a Global field. The contract (field UIDs and types) is the same either way. The distinction matters only to content modelers and stack administrators.

## The JSON schema of a global field

When you fetch a global field definition via the Content Management API at GET /v3/global\_fields/seo\_metadata, you get a schema that looks like this:

{
  "global\_field": {
    "title": "SEO Metadata",
    "uid": "seo\_metadata",
    "schema": \[
      {
        "display\_name": "Meta Title",
        "uid": "meta\_title",
        "data\_type": "text",
        "field\_metadata": {
          "description": "Page title for search engines. Keep under 60 characters."
        }
      },
      {
        "display\_name": "Meta Description",
        "uid": "meta\_description",
        "data\_type": "text",
        "field\_metadata": {
          "multiline": true,
          "description": "Summary for search results. Keep under 160 characters."
        }
      },
      {
        "display\_name": "OG Image",
        "uid": "og\_image",
        "data\_type": "file"
      },
      {
        "display\_name": "Canonical URL",
        "uid": "canonical\_url",
        "data\_type": "text"
      }
    \]
  }
}

When this global field is added to a content type (say, "Blog Post"), the content type schema references it with data\_type: "global\_field" and a reference\_to property pointing to the global field UID:

{
  "display\_name": "SEO",
  "uid": "seo",
  "data\_type": "global\_field",
  "reference\_to": "seo\_metadata"
}

Notice that the field UID in the content type (seo) can differ from the global field UID (seo\_metadata). The content type assigns its own UID to the instance of the global field. This means you could theoretically add the same global field twice to a content type with different instance UIDs, though this is rarely useful.

## API representation

In the Content Delivery API response, a global field appears as a nested JSON object, exactly like a Group field. For a Blog Post entry with the SEO Metadata global field:

{
  "entry": {
    "uid": "blt9876543210fedcba",
    "title": "Understanding Content Modeling",
    "body": "...",
    "seo": {
      "meta\_title": "Content Modeling Best Practices | Our Blog",
      "meta\_description": "Learn how to design content models that scale across channels and teams.",
      "og\_image": {
        "uid": "bltasset\_og\_001",
        "url": "https://images.contentstack.io/v3/assets/.../og-image.jpg",
        "filename": "og-image.jpg"
      },
      "canonical\_url": "https://example.com/blog/content-modeling"
    }
  }
}

The seo key corresponds to the instance UID assigned in the content type, and its children use the field UIDs from the global field definition. Frontend code accesses these values the same way it would access any nested object:

function SEOHead({ seo }: { seo: SEOMetadata }) {
  return (
    
      
      {seo.og\_image && (
        
      )}
      {seo.canonical\_url && (
        
      )}
    
  );
}

Because the global field ensures consistent UIDs across content types, this component works for Blog Posts, Landing Pages, Product Pages, and any other content type that includes the SEO Metadata global field.

## Change propagation

The most significant advantage of global fields over Group fields is centralized change propagation. When you update a global field definition - for example, adding a robots\_directive field to SEO Metadata - the change automatically appears in every content type that uses that global field. Editors see the new field the next time they open any entry, and the API response includes the new key (with a null or empty value until editors populate it).

This propagation works in both directions:

*   Adding a field to the global field definition adds it to all content types. Existing entries gain the new field with no value. As discussed in lesson 2.1.2, frontend code should handle missing or null fields gracefully.
*   Removing a field from the global field definition removes it from all content types. Any data stored in that field on existing entries is lost. This is a destructive operation and a breaking change for frontend code that depends on the removed field UID.
*   Renaming a field UID within the global field changes the API key across all content types simultaneously. This is equally destructive - every frontend reference to the old UID breaks at once across every content type that uses the global field.

> **Common Pitfall**
> 
> Removing or renaming a field inside a global field breaks the API contract for every content type that uses it -- the blast radius is proportional to reuse.

This propagation behavior makes global fields powerful but demands careful governance. A careless change to a global field used by 15 content types simultaneously breaks 15 API contracts.

## Best use cases for global fields

Global fields work best for field groups that satisfy two criteria: they appear in multiple content types, and they should always have the same structure.

### SEO metadata

The classic use case. Every content type that represents a page needs SEO fields, and those fields should be identical everywhere. A global field ensures that meta\_title has the same UID, character limit, and help text whether it appears on a Page, a Product, or a Product Line.

### Address blocks

If multiple content types include physical addresses (store locations, shipping addresses), an Address global field with fields for street, city, state, postal\_code, and country ensures consistency. Adding a latitude and longitude field later automatically extends every content type that uses addresses.

### Social media links

A Social Links global field with fields for twitter\_url, instagram\_url, and website\_url can be shared across Page, Product Line, and Header content types.

### Call-to-action buttons

A CTA global field with cta\_label, cta\_url, and cta\_style (select field with options like "primary," "secondary," "outline") standardizes how CTAs are modeled across Landing Pages, Banners, and Promotional content types.

### Structured data / Schema.org markup

Fields for schema\_type, schema\_name, and schema\_description can be standardized as a global field for content types that need structured data markup for search engines.

## When NOT to use global fields

Global fields are not always the right choice. Here are scenarios where other approaches fit better.

### When the data should be independently queryable

If you need to search, filter, or list items by the data in question, it should be a separate content type with a Reference field, not a global field. For example, a "Category" with a name and description might seem like a candidate for a global field, but if you need to list all categories or filter articles by category, it must be its own content type. Global fields are embedded data; they cannot be queried independently. See lesson 2.2.1 on references vs. modular blocks for guidance on when to use references.

### When different content types need different variations

If Pages need meta\_title, meta\_description, and og\_image for SEO but Products also need product\_schema\_type for Schema.org markup, forcing everything into one global field adds irrelevant fields to Pages. Either create two global fields (one for basic SEO, one for product-specific structured data) or use a Group field for the product-specific extension.

### When the group is used by only one content type

If only the Product content type has a care\_instructions section with materials and cleaning, making it a global field provides no benefit. Use a regular Group field instead. Global fields add management overhead (they appear in the Settings menu, they require governance), and that overhead is only justified when multiple content types benefit from the shared definition.

## Global fields vs. group fields vs. references: a decision framework

Choosing between these three options is one of the most common content modeling decisions. Here is a decision framework:

Question

If yes, use...

Does this data need to be queried, filtered, or listed independently?

Reference to a separate content type

Will the same group of fields appear in 3+ content types with identical structure?

Global field

Is this group of fields specific to one content type?

Group field

Does changing this data in one place need to update all entries that display it?

Reference (single source of truth for content)

Does changing the _schema definition_ need to update all content types that use it?

Global field (single source of truth for structure)

The key distinction: References share _content_ (one Product Line entry used by many products), while Global Fields share _structure_ (one field definition used by many content types). A Reference means "this entry points to that entry." A Global Field means "this content type uses that field group definition."

## Managing global fields at scale

As your stack grows, you may accumulate many global fields. Keep them manageable with these practices:

*   Name global fields by their purpose, not their location. "SEO Metadata" is better than "Page Header Fields" because the same global field might appear on content types that are not pages.
*   Document which content types use each global field. The Contentstack UI does not currently show a "used by" list for global fields. Maintain a simple reference document or use the Content Management API to query content type schemas for data\_type: "global\_field" references.
*   Treat global field changes as cross-cutting concerns. Before modifying a global field, identify every content type that uses it and every frontend component that reads its fields. The impact radius is larger than modifying a single content type.
*   Version control global field definitions. Use the Contentstack CLI to export global field schemas and store them in version control alongside your content type definitions. This makes changes reviewable in pull requests.

## Common mistakes

1.  Creating global fields for data that should be references. A "Featured Product Line" global field with line\_title, line\_description, and line\_image embedded in every Product creates data duplication - every entry stores a copy of the line data, and updating the line requires editing every entry. This data belongs in a Product Line content type with Reference fields pointing to it. Global fields share _structure_, not _content_.
2.  Over-using global fields and making content types rigid. Adding global fields for "Hero Section," "Sidebar Content," and "Footer CTA" to every content type forces a uniform page layout across the entire site. Content types should model domain concepts (as discussed in lesson 2.1.1), not page regions. Use Modular Blocks or page-composition patterns for layout flexibility.
3.  Modifying global fields without checking downstream impact. Removing a field from a global field used by 12 content types simultaneously breaks the API contract for all 12. Unlike modifying a Group field (which affects one content type), modifying a global field has a blast radius proportional to its reuse. Always audit usage before making changes.

#### Key takeaways

- Connect **Global fields - reusable field groups** back to your stack configuration before moving to the next module.
- Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment.
- Re-read the delivery versus management boundary for anything you changed in the entry model.

## Supplement for indexing

### Content summary

Global fields - reusable field groups. Global fields: reusable field groups TL;DR Global fields define a group of fields once and embed it across multiple content types -- changes propagate everywhere automatically. The API output for a global field is identical to a group field; the difference is purely in how the schema is managed. Use global fields for structures that appear in 3+ content types with identical shape (SEO metadata, addresses, CTAs). Modifying a global field is a cross-cutting change -- audit all consuming content types and frontends before editing. SEO metadata follows the same pattern on every content type in your stack: a meta title, a meta description, an Open Graph image, and an optional canonical URL. Witho

### Retrieval tags

- Global
- fields
- reusable
- field
- groups
- content-modeling-with-contentstack
- lesson 04
- Global fields - reusable field groups
- content-modeling-with-contentstack lesson

### Indexing notes

Index this lesson as a primary chunk tagged with lesson_id "04" and topics: [Global, fields, reusable, field, groups].
Parent course slug: content-modeling-with-contentstack. Use asset_references URLs as thumbnail hints in search results when present.
Never surface LMS quiz content or assessment answers from this file.

### Asset references

_No image or video thumbnail URLs were extracted._

### External links

| Label | URL |
| --- | --- |
| Contentstack Academy home | `https://www.contentstack.com/academy/` |
| Training instance setup | `https://www.contentstack.com/academy/training-instance` |
| Academy playground (GitHub) | `https://github.com/contentstack/contentstack-academy-playground` |
| Contentstack documentation | `https://www.contentstack.com/docs/` |