Components

A Component is a pre-built, versioned schema fragment that lives next to your Collections. A Collection embeds a Component into its own schema through a nested field, and chooses how to follow the Component going forward — either pinned to a specific version, or auto-updating as the Component evolves.

Think of Components as a shared schema library for your environment. They are not standalone content; they are reusable schema definitions that Collections opt into.

When to Use Components

Components are the right tool when the same set of fields needs to appear across multiple Collections:

  • Shared field patterns: SEO metadata, addresses, author bios, call-to-action blocks — anywhere the same shape should stay identical across content models.
  • Modular schema design: Break a complex Collection schema into smaller, focused chunks that you can evolve independently.
  • Coordinated evolution: Add a new field once on the Component and let auto-update propagate it to every Collection that subscribes — no manual edits per Collection.

Rule of thumb: Use Collections for content. Use Components for schema pieces that more than one Collection needs to share.

How Components Work

  1. Define the schema. A Component is a schema without resources of its own. You define its fields and validation rules just like a Collection's schema.
  2. Publish a version. Components are versioned. Each published version is immutable — Collections that pin to it keep getting the same shape forever.
  3. Embed into a Collection. A Collection adds a nested field whose metadata points at a specific Component version (component, component_version). The resolved Collection schema inlines the Component's fields.
  4. Choose how to follow updates. On each nested field you decide between:
    • auto_update: false (pinned, the default) — the field stays on its current Component version forever until you explicitly call sync_component.
    • auto_update: true — when the Component publishes a new version, the platform automatically advances this Collection to a fresh schema version with the new pin.

Pinned vs Auto-Updating Fields

The auto_update flag on a nested field controls how the Collection follows the Component's evolution.

Pinned (auto_update: false)

The field references one specific Component version. Publishing a new Component version does not touch this Collection. The pin only moves when you call POST /collections/{key}/sync_component/ and pass either an empty body (advance to current) or to_versions: { "<path>": "<target_version_uid>" }.

Use pinning when:

  • You want explicit, audited control over when a schema bump reaches a Collection.
  • The Collection has a release cadence that should be independent of the Component's.

Auto-Updating (auto_update: true)

The field follows the Component's current_version. Every time the Component publishes, the platform:

  1. Materializes a new Collection schema version with the advanced pin (the old version stays untouched — existing Revisions remain valid).
  2. Runs a compatibility check (rejecting changes that would invalidate existing data, like a required field added without a default, a type narrowing, or a field removal).
  3. Emits an update event with subtype component_auto_sync (or component_auto_sync_failed / component_auto_sync_skipped_quota on conflict / quota exhaustion).

Use auto-update when:

  • You want Collections to stay in lockstep with the Component without manual work.
  • Compatibility is a soft contract you'd rather catch at publish time than during a manual sync.

Example: A Reusable SEO Component

1. Create the SEO Metadata Component schema:

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

2. Embed it in a Collection schema:

In your Articles Collection, add a nested field whose meta points at the SEO Metadata Component.

📁 Articles (Collection)
└── Schema:
    ├── title (string)
    ├── body (text)
    └── seo_fields  ← nested:
                       component:         "cmp-seo-metadata"
                       component_version: "ver-abc12345"
                       auto_update:       true

3. The result:

Every article in Articles now carries the SEO fields. When you add twitter_card to the SEO Metadata Component and publish a new version, the Articles Collection automatically advances to a fresh schema version with the new field — no manual edits, no broken existing articles.

If a Collection pins the same SEO Component with auto_update: false, the new field shows up only after a sync_component call.

Compatibility & Safety

The platform refuses to auto-advance a Collection if the new Component version would break existing resources. The conservative v1 rules:

  • required_field_added_no_default — a required field was added to the Component without a default value.
  • type_narrowed — a field's type changed in a way that prior data may not satisfy.
  • field_removed — a field present in the previous version is gone.

When auto-sync detects a conflict, it skips the advance and emits a component_auto_sync_failed event. The same predicate runs when sync_component is called explicitly — incompatible advances return 409 component_sync_conflict with the structured conflict list.

Best Practices

  • Name Components clearly. Use descriptive names (SeoMetadata, AddressBlock) so they are easy to spot in the dashboard and grep in code.
  • Keep Components focused. Smaller, single-purpose Components are easier to evolve and harder to break.
  • Default to pinning for shared production Collections. Auto-update is convenient, but pinning gives you a controlled bump per Collection.
  • Treat Component publishes as schema migrations. Even a "safe" change (adding an optional field) materializes new Collection versions — observability dashboards should track the auto-sync events.

Related API References

Was this page helpful?