A Content Type is the schema template to create page entries. In a headless project, you declare each Content Type as an individual .jsonc file, combine them into a schema bundle with the Content plugin, and upload the bundle to the Schema Registry.

This guide covers how to define Content Types: where files live, which properties are required, and two annotated examples (minimal and full).

For modeling concepts (Content Type vs. Component, singleton patterns, recommended page structures), see Understanding content modeling and architecture for headless stores.

• Understanding content modeling and architecture for headless stores
• Content plugin installed
• Component schemas your Content Types reference (for example, SEO, PromoBanner) are defined under cms/components/

Each Content Type lives in its own file. The Content plugin discovers files by prefix and merges them into the content-types key of your schema bundle.

For headless storefronts, keep Content Type files separate from component schemas:

You can co-locate Content Type files under cms/pages/ (shown above) or use another directory; the CLI accepts custom paths as arguments. What matters is the file prefix, not the folder name.

The Content Type ID (the segment after cms_content_type__) is what editors see in the CMS Admin and what your storefront uses in Data Plane URLs: …/{storeId}/landingPage/entries/slug/{slug}.

Remember, this step applies only to headless stores. Don't use the vtex.headless base schema for FastStore stores, as it may remove the default FastStore content types and components from the store schema.

Before uploading the schema, open the generated schema.json file and review its contents. Make sure it includes the expected content types, components, and pages for your headless store.

Uploading a schema replaces the current schema configuration for the selected store. Reviewing the file first helps prevent accidentally removing existing content types or components.

Generate and upload the bundle with the headless base schema:

Replace {storeId} with your headless store ID when prompted, or pass it with the store flag documented in the Content plugin.

A Content Type schema is a JSON Schema object with CMS-specific metadata. The table below lists every property you're likely to use.

$ALLOW_ALL_COMPONENTS is generated when you run vtex content generate-schema. Reference it in Content Types — don't create it manually in individual files.

These two properties work together to control how entries are created and fetched:

For most headless pages, use either a singleton with empty identifierKeys or identifierKeys: ["slug"].

The example below defines a singleton About page. It has a sections array only. No slug, no embedded components. Editors add sections from the components you registered in the bundle.

File: cms/pages/cms_content_type__aboutPage.jsonc

What editors get: a single About entry where they add and reorder sections such as PromoBanner or RichTextBlock.

What your storefront does: fetch the about entry by Content Type name and render each section by componentKey.

The example below defines a multi-instance Landing Page Content Type with:

• A slug field for routing.
• An embedded SEO component (relation via $ref).
• A hero image field using the media gallery widget.
• A sections array for dynamic page blocks

Prerequisite component: cms/components/cms_component__SEO.jsonc:

Content Type file: cms/pages/cms_content_type__landingPage.jsonc:

After editors save and publish, the Data Plane returns content shaped by this schema:

Your storefront maps landingPage to its page template, reads slug for routing, and renders seo, heroImage, and each item in sections.