Defining components

A component is a reusable JSON Schema object that groups related fields — for example, a link, a banner, an SEO block, or a full page section. In a headless project, you declare each component in its own .jsonc file under cms/components/, merge them into a schema bundle with the Content plugin, and upload the bundle to the Schema Registry.

This guide covers how to define components, including file structure, required properties, and four annotated examples: a reusable building block, a page section, nested composition with $ref, and polymorphic fields.

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

The Content plugin provides the CLI commands used in this guide to generate and upload your schema bundle. Make sure it's installed before proceeding by following the Content plugin guide.

Both components and Content Types are JSON Schema objects, but they play different roles:

If it has a URL, model it as a Content Type. If it renders a block on a page or groups fields reused elsewhere, model it as a component. See Choosing between a Content Type and a component.

Sections are components that you add to a page through a Content Type's sections array. Reusable building blocks (such as Link or SEO) are usually embedded inside sections or Content Types with $ref instead of being listed in the section picker.

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

Keep component schemas separate from Content Type files:

You can use a different directory. The CLI accepts custom paths as arguments. The file prefix is what determines discovery.

The component ID (the segment after cms_component__) must match $componentKey in the file. This value appears in published JSON and is what your storefront uses to pick a renderer.

Generate and upload the bundle:

For headless projects that use a custom base schema, pass --remote <url> to point to a publicly accessible JSON Schema file, or --local <path> to use a local file. If your project extends vtex.faststore, omit both flags. The command fetches the FastStore schema automatically.

On success, the CLI prints:

The generate-schema command also creates #/$defs/$ALLOW_ALL_COMPONENTS, a generated list of every component in your bundle. Content Types reference it for open section pickers. See Making components available on pages. Don't hand-author this definition in individual files.

A component schema is a JSON Schema object with CMS-specific metadata.

Set $abstract: true on building blocks that should never be placed directly on a page. Leave it unset (or false) on sections you add through the page editor.

The example below defines a Link component with three fields. Link is never added as a standalone section. Other components and Content Types embed it with $ref.

File: cms/components/cms_component__Link.jsonc

What you get in the Admin: A reusable link form wherever another schema references #/components/Link.

What your storefront does: Renders the nested link object inside a parent section or Content Type field. No separate componentKey lookup for Link unless you fetch it as an embedded object.

The example below defines a CallToAction section, a page block you add through a Content Type sections array. It includes a title and a nested link object.

File: cms/components/cms_component__CallToAction.jsonc

Adding this component to a Content Type affects both the Admin and the storefront:

• In the Admin: A section you can add, reorder, and configure on any Content Type that exposes $ALLOW_ALL_COMPONENTS (or a restricted anyOf list that includes CallToAction).

• In the storefront: Maps componentKey: "CallToAction" to a UI component and renders title and link from the published JSON.

When the same field shape appears in multiple components, define it once and reference it with $ref instead of duplicating properties.

The example below updates CallToAction to reuse the Link component from the previous section:

File: cms/components/cms_component__CallToAction.jsonc

Both components must exist in the same schema bundle before upload. The Schema Registry resolves $ref pointers when the bundle is saved, so the Admin form and validation use the merged Link definition.

Polymorphic fields accept more than one shape depending on what you choose. Instead of a fixed object, you declare a set of variants using anyOf or oneOf, and the CMS Admin presents you with a picker to select which variant to use.

The two JSON Schema keywords work the same way structurally but enforce different validation rules. Use oneOf when exactly one variant must match, and anyOf when one or more can match. Beyond validation, the main practical difference is whether the field is a single object or an array of items. That is what changes the UI behavior, not the keyword itself.

Keep $componentKey values stable across schema versions. Changing a key breaks existing published content that references the old value, and storefront renderers that map on componentKey will stop matching.

The examples below use a CustomCarousel component to illustrate both patterns.

The example below uses oneOf on a single card field. You pick exactly one variant, image card or text card, and complete its fields. You could also use anyOf here with the same structural result. The keyword choice depends on your validation intent.

File: cms/components/cms_component__CustomCarouselOneOf.jsonc

Using oneOf on a single field changes behavior in both the Admin and the storefront:

• In the Admin: A single Card field with a type picker. You choose "Image Card" or "Text Card" and complete its fields. Only one variant is active at a time.

• In the storefront: Reads the published card object and branches on which properties are present (image vs. text) to decide which renderer to use.

The example below uses anyOf on the items of a cards array. Multiple items of different types can be added in any order and combination. You could also use oneOf on array items. The keyword choice again depends on validation intent.

File: cms/components/cms_component__CustomCarouselAnyOf.jsonc

What you get in the Admin: A Cards list with an Add item dropdown. Each click adds a new item. You pick "Image Card" or "Text Card" per item, and items of different types can be freely mixed and reordered in the same list.

The image above shows the Custom Carousel anyOf section in the CMS Admin. The Cards array accepts Image Card and Text Card items in any order and combination.

What your storefront does: Iterates over the cards array and dispatches each item to the appropriate renderer based on which properties are present.

The examples above illustrate two different array contexts, not a rule about which keyword to use where. anyOf and oneOf can each appear on a single field or on array items. What changes the UI behavior is the array context: a single field renders a type picker, while an array renders a growable list with per-item type selection.

Components become editable page blocks when a Content Type references them through a sections property.

Reference the generated $ALLOW_ALL_COMPONENTS definition:

Every component in your bundle (including CallToAction and PromoBanner) appears in the Admin section picker. Building blocks such as Link and SEO are meant to be embedded with $ref, not added as standalone sections. Mark them with $abstract: true to signal that intent to the Admin.

When a Content Type should allow only certain sections, replace $ALLOW_ALL_COMPONENTS with an explicit anyOf list:

Use restricted lists on Content Types where commerce or promotional sections would not make sense, for example, blog posts or legal pages.

After adding a CallToAction section to a landing page and publishing it, the Data Plane returns content shaped like this:

Each item in sections includes a componentKey your storefront uses to select a renderer. Nested objects from $ref (such as link) don't get their own top-level componentKey unless the schema defines them as embedded components at the Content Type level (as with SEO on a landing page).

Your storefront owns the mapping from schema to UI:

1. Fetch the entry from the Data Plane API by Content Type name or slug.
2. Loop through sections (or fixed component fields such as SEO).
3. Match componentKey to a component in your framework (React, Vue, Svelte, or server templates).
4. Pass field values as props or template context.

Unlike FastStore integrations, headless projects do not ship with a predefined component library. You define both the schemas in cms/components/ and the renderers in your codebase. Keep $componentKey values stable: Changing them breaks existing published content and storefront mappings.

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

---