Content modeling defines what can be created on the CMS, and the architecture defines how that content moves from your repository to the CMS Admin and, after publishing, to your storefront.

This guide details both layers for headless integrations, covering core concepts, design principles, JSON Schema rules, consumption patterns, and recommended Content Type structures.

For platform architecture (CQRS, schema upload lifecycle, file organization), see Understanding CMS architecture and schema declarations.

Before modeling content for a headless store, you need three foundations in place.

The CMS uses JSON Schema to declare every Content Type, component, and field. You don't need to master the full specification, but you should be comfortable with:

Concept	Role in the CMS
type	Declares the data shape (string, number, boolean, object, array).
properties	Lists the fields inside an object.
required	Indicates which fields are required before content can be saved.
items	Defines the shape of each element in an array.
$ref	Points to another definition in the same schema bundle.

A minimal field declaration looks like this:

Learn more in the JSON Schema instructions guide.

Schemas are authored as .jsonc files in your project and uploaded through the Content plugin (@vtex/cli-plugin-content):

Typical workflow:

1. Author component and Content Type files in your repository.
2. Run vtex content generate-schema to produce a unified bundle.
3. Run vtex content upload-schema to publish it to the Schema Registry.

For headless stores, the generate-schema command requires two extra arguments: the paths to your component and Content Type directories, and --base vtex.headless:

For example:

Requirement	Details
CMS enabled	CMS Admin available in your VTEX account.
Headless store	A store created with storefront type Headless in Storefront > Content.
Frontend integration	An app that fetches published entries from the Data Plane API and maps componentKey values to UI components.

Your team owns rendering, preview wiring, and CI/CD. The CMS provides schemas, authoring, and published content delivery.

Term	Definition
Schema	A versioned bundle that defines all Content Types and components for your store. Identified as account.name@version (for example, mystore.myheadlessstore@1.0.0) and stored in the Schema Registry. Contains components, content-types, optional $defs, and a $base reference to vtex.headless.
Content Type	A page-level template, for example, Home or Landing Page. Defined under the content-types key. You can create entries from Content Types.
Entry	One content instance of a Content Type (for example, a landing page with slug summer-sale).
Component	A reusable building block, for example, a banner or navigation bar. Defined under the components key. Can appear on multiple Content Types.
Section	A component that can be added to a page through a Content Type's sections array. See Understanding components and sections.
Field	A single property inside a Component or Content Type (string, number, boolean, object, or array), defined in properties.
Base schema	A shared template in $defs (or inherited via $base). Other definitions reuse it through $extends to avoid duplication.

A Content Type describes the shape of a page. Components are the building blocks you arrange inside it.

Relationship in practice:

Layer	Declares	Example
Content Type	Page structure and which components are available	landingPage with slug, seo, and sections
Component	Reusable block with its own fields	PromoBanner with title, image, link
Field	Atomic editable value	title (string), image.src (string + media widget)

A Content Type holds fixed fields (always present on every entry) and a dynamic sections array (you choose which components appear and in what order).

Scenario	Content Type	Component
Represents a routable page	✅	❌
Needs multiple instances (many landing pages)	✅	❌
Only one instance store-wide	✅ ($singleton: true)	❌
Reusable UI block on one or more pages	❌	✅
Nested inside another component	❌	✅
Needs a slug or identifier field	✅	❌
Shared across the store (header, footer)	✅ (singleton Content Type)	✅ (component inside it)

If it has a URL, model it as a Content Type. If it renders a block on a page, model it as a component.

Well-structured schemas reuse definitions instead of duplicating fields. The CMS supports three complementary mechanisms.

Level	Mechanism	Purpose
Platform	"$base": "vtex.headless"	Inherits the headless platform bundle when you upload your store schema.
Component	"$extends": ["#/$defs/base-component"]	Inherits shared component structure from your base bundle, when available.
Content Type	"$extends": ["#/$defs/base-page-template"]	Shares common page properties across Content Types when you define a template.

The vtex.headless base provides core platform definitions — not a full page library. You add the components and content-types your storefront needs.

Definitions such as base-component or base-page-template may be provided by your base bundle. Check the merged output of vtex content generate-schema before referencing them with $extends.

$extends inherits properties from one or more definitions in the same bundle. Child properties override parent properties with the same name.

Use $extends when multiple components share fields (dates, color variants, link objects) or when Content Types share a common page skeleton.

$ref embeds or reuses a definition without copying it:

Pattern	Example	Use when
Embed a component	"seo": { "$ref": "#/components/SEO" }	Every entry of a Content Type needs the same block.
Open section picker	"sections": { "$ref": "#/$defs/$ALLOW_ALL_COMPONENTS" }	You need to add any component you registered.
Restricted sections	"sections": { "type": "array", "items": { "anyOf": [...] } } }	Only certain components are allowed on a page.

$ALLOW_ALL_COMPONENTS is generated when you run vtex content generate-schema. It lists every component in your bundle as an anyOf array. Reference it in Content Types. Do not hand-author this definition in individual .jsonc files.

The CMS uses JSON Schema draft 2019-09 with a VTEX-specific vocabulary for CMS keywords and widgets.

These keywords extend standard JSON Schema. They're resolved when you upload a bundle.

Keyword	Applies to	Purpose
$base	Schema bundle	Inherits the vtex.headless platform schema.
$extends	Component, Content Type	Inherits properties from other definitions in the bundle.
$componentKey	Component	Unique identifier used in API responses and frontend mapping.
$componentTitle	Component	Display name in the CMS Admin.
$singleton	Content Type	Limits the Content Type to a single entry (for example, home, globalHeader).
$abstract	Component	Marks a template-only component that you can’t add to pages.
identifierKeys	Content Type	Fields that uniquely identify entries (for example, ["slug"]).
widget	Field	Controls the Admin UI control (ui:widget).
enumNames	Field	Human-readable labels for enum values.

For schema file naming and upload workflow, see Understanding CMS architecture and schema declarations.

Field type	JSON Schema	Description
Short text	{ "type": "string" }	Default text input.
Long text	string + "ui:widget": "text-area"	Multi-line input.
URL slug	string + "ui:widget": "slug"	Normalized with / prefix.
Number	{ "type": "number" } or "integer"	Integers for counts and limits.
Toggle	{ "type": "boolean" }	Checkbox.
Select	enum + optional enumNames	Dropdown.
Date and time	string + "ui:widget": "date-time"	Stored as ISO 8601 string.
Image or video	string + "ui:widget": "media-gallery"	References Media Gallery assets.
Rich text	string + "ui:widget": "draftjs-rich-text"	Formatted text stored as a JSON string.
Group of fields	{ "type": "object", "properties": {…} }	Nested form section.
List of items	{ "type": "array", "items": {…} }	Repeatable blocks (footer links, nav items).

Standard JSON Schema validation runs when you save content. Common constraints:

Constraint	Example	Effect
required	"required": ["title", "slug"]	Named fields must be completed.
minLength / maxLength	"minLength": 10 on a slug	Enforces string length.
minimum / maximum	"maximum": 5 on item count	Bounds numeric values.
minItems / maxItems	"minItems": 1, "maxItems": 8 on a link array	Limits array size.
enum	"enum": ["primary", "secondary"]	Restricts to allowed values.
default	"default": "primary"	Pre-fills new entries.

Invalid data is rejected when saving, before the content is published.

After you upload schemas and publish content, your headless storefront reads published entries from the Data Plane API. The schema you defined shapes the JSON your app receives: field names, section structure, and componentKey values.

For the full lifecycle (schema upload, authoring, publishing, sync), see Understanding CMS architecture and schema declarations.

Your storefront owns:

• Routing: Mapping URLs to Content Types and slugs.
• Locale: Passing the locale query parameter when fetching entries.
• Rendering: Mapping each componentKey to a UI component in your framework.

The sections below cover the most common consumption patterns.

Use this pattern when a URL arrives at your frontend, and you need to load the corresponding CMS entry. Pass the slug as a path segment after entries/slug/. Multi-segment slugs (for example, en/promo) are supported.

Response shape (simplified):

To request a localized version, add the locale query parameter:

Use this pattern to build listing pages (for example, a blog index or a campaign directory), or to pre-render all entries at build time.

Response shape (simplified):

By default, only entry metadata is returned. To include the full content blob for each entry, add ?content=all:

The Data Plane API uses scroll-based pagination. Each response returns a scroll token when more entries exist. Pass it as the scroll query parameter to fetch the next page. Each page contains up to 20 entries.

First request:

Next page:

When scroll is absent from the response, you have reached the last page.

You can also control sort order:

Singleton Content Types (defined with "$singleton": true) have exactly one entry store-wide — no slug is needed. Fetch them by listing the Content Type's entries and reading the first (and only) result. This is the standard pattern for headers, footers, and global navigation.

Every section object in an API response includes a componentKey that identifies which component to render. Your frontend maps these keys to actual UI components.

A typical implementation in React:

Each component receives the full section object as props, so field names in your JSON Schema map directly to the props your component expects. If a componentKey isn't in your map, the section is silently skipped — this is a safe default during incremental rollout.

The patterns below are common conventions for headless commerce storefronts. Names, components, and routes are yours to define. Nothing in this section exists until you add it to your schema bundle.

Some content applies across every page rather than to a single route.

Pattern	Suggested Content Type name	Components you might define	Purpose
Header	globalHeader	SiteHeader, AnnouncementBar	Top navigation, logo, utility links.
Footer	globalFooter	SiteFooter	Links, social icons, copyright.
Navigation	Inside a header component	Link arrays, menu items	Main menu is maintained once.
Banners	On page Content Types	PromoBanner, TextBanner	Promotional blocks per page.

Fetch singleton entries by Content Type name (no slug) and wrap every page layout with the returned sections.

Navigation is usually a component inside a header singleton, not its own page Content Type. Banners are components on page-level Content Types. Each page chooses its own banner stack.

Page type	$singleton	identifierKeys	Components you might use	Example route
Home	true	[]	Promo banners, featured collections.	/
Landing page	false	["slug"]	Banners, rich text, CTA.	/{slug}
PLP	false	["slug"]	Breadcrumb, layout config.	/category/{slug}
PDP	false	["slug"]	Product layout, cross-sell blocks.	/product/{slug}
Blog category	false	["slug"]	Category header, article list.	/blog/{slug}
Blog post	false	["slug"]	Article body, related content.	/blog/post/{slug}

Home: One entry, no slug:

Landing page: Many entries, slug required:

PLP and PDP: The CMS entry controls layout and display configuration. Product data (catalog, prices, stock) still comes from VTEX commerce APIs.

Blog: Define blogCategory and blogPost Content Types when your storefront needs editorial content:

Restricting sections with a custom anyOf (instead of $ALLOW_ALL_COMPONENTS) keeps commerce components off article pages.