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:

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.

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:

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.