Component Modeling

As your data model grows, you'll often find yourself needing the same set of fields in multiple places—an address block, SEO metadata, or a call-to-action button. Copying these fields across different schemas is inefficient and leads to inconsistencies when you need to make updates.

Components solve this problem. They are reusable, embeddable schema fragments that you can define once and embed anywhere. Unlike Collection folders, which store content, a Component is purely a structural blueprint for a block of fields.

When to Use Components

Components are the solution for several common data modeling challenges:

• Building Composite Layouts: When you need to create flexible page layouts (like a landing page), Components act as the "bricks" (e.g., Hero Section, Testimonial Slider, CTA) that content editors can mix and match within a Composite folder.
• Sharing Common Fields: To ensure consistency for common data blocks like SEO metadata or an address, create them as a single Component and embed it wherever needed. Updating the Component updates it everywhere.
• Modeling Complex Nested Data: For complex data that has its own set of fields and validation rules (like product variants with unique inventory fields), Components provide a way to keep your schemas modular and clean.

Rule of Thumb: Use Collection folders when you need to store a list of standalone resources. Use Components when you need to define a reusable set of fields that will be embedded within other resources.

How Components Work

1. Define the Schema: A Component is essentially a schema without content. You define its fields and validation rules just like you would for a folder.
2. Embed in Other Schemas: You can then embed this Component in other schemas (either in Composite folders or even other Components) by using a "Nested" field type.
3. Manage Versions: Components have their own versioning system. You can work on a draft version of a Component without affecting its live usage. When you publish the new version, all schemas that embed it automatically inherit the changes.

Example: A Reusable SEO Component

A common use case is creating a single, consistent component for SEO metadata that can be attached to any content type.

1. Create the SEO Metadata Component:

📁 Components
└── 📄 SEO Metadata
    ├── title (string)
    ├── description (text)
    └── og_image (image)

2. Embed it in a Collection Folder: In your Articles collection folder, you add a single nested field that references your SEO Metadata component.

📁 Articles (Collection)
└── Schema:
    ├── title (string)
    ├── body (text)
    └── seo_fields (Nested → SEO Metadata)

3. The Result: Now, every article your editors create will have a consistent, reusable block of SEO fields. If you ever need to add a new SEO field (e.g., twitter_card), you only need to update the SEO Metadata component once, and the change will instantly apply to all your articles.

Best Practices for Component Design

• Name Components Clearly: Use descriptive names (HeroSection, SeoMetadata) so they are easily identifiable in the dashboard.
• Keep Components Granular: Prefer smaller, focused Components over large, monolithic ones. A small CtaButton component is more reusable than a giant PageFooter component.
• Version Safely: Always test new Component versions in a non-production environment before publishing them, as changes will propagate to all schemas that use them.
• Document for Editors: Use the "Description" and "Help Text" fields for your Components and their fields to guide content editors.

Related API References

• Management API – Components → Create, update, and manage your reusable schemas.
• Management API – Fields → Define the structure and validation rules within your Components.
• Management API – Versions → Manage the lifecycle of your Component schemas.