Custom Entities

In Publive (a headless CMS), Custom Entities let you define your own content types and structures beyond the default post model. Each custom entity is driven by a schema that describes its fields, and each entry is a document that holds values for those fields.

• Schema – Defines the content type: its name, API identifiers, fields, groups, and settings (e.g. entry title, searchable/filter fields, allowed states, access control, custom URL rule (Coming soon)).
• Entry – A single record for that content type, with values for each field defined in the schema.
• Published entry – The version of an entry that is exposed via APIs for consumption by apps and websites.

Custom Entities = schema-defined content types + entries whose structure is flexible and defined by you.

---

​

How Custom Entities Can Be Used

• Structured content types – e.g. “Product”, “Event”, “Recipe”, “Team Member” with a fixed set of fields and validation.
• Multi-channel content – Same content type used by web, app, or other clients via APIs (e.g. JSON, HTML, XML, or plain text).
• Relations – Link entries to Categories, Tags, Members, Forms, or other custom content types via Related fields.
• Rich layouts – Use Components and Dynamic Zones to build modular blocks (hero, CTA, FAQ, etc.) inside an entry.
• Filtered lists – Use Dynamic List fields to show lists of related content filtered by relations (e.g. “Posts in this Category” or “Products in this Collection”).
• Single-page vs collection – Schemas can represent a collection (many entries) or a single content type (e.g. one “About Us” page); some schemas are used as reusable building blocks (e.g. shared with posts).

​

Example Scenarios

• Product catalog – A “Product” content type with name, SKU, price, category, image, and description. Entries are products; APIs return them for storefront or app.
• Landing page builder – A “Landing Page” content type with a Dynamic Zone where each section can be a different block type (Hero, Features, Testimonials, CTA). Each entry is a page; order and mix of blocks are flexible.
• Event listing – An “Event” content type with title, start/end date and time, venue (related entity), and a Dynamic List for “Related events” filtered by category or tag.

---

​

Core Concepts

​

Schema

• The schema is the definition of a content type: name, API slugs, response format, fields, groups, and settings.
• Fields – Each field has a name, a type (e.g. short text, number, relation, component, dynamic zone, dynamic list), optional metadata (e.g. label, default), and validation rules.
• Groups – Logical grouping of fields (e.g. “Content”, “SEO”) for organisation and UI.
• Settings – Include which field is used as the entry title, which fields are searchable, which can be used as filters, allowed states, access control, custom URL patterns (Coming soon), and optional component preview.

​

Entries and Field Values

• An entry belongs to one schema and holds one value per field.
• Values are typed according to the field type (text, number, date, media, relation, component(s), or dynamic list configuration).

​

Relations and Taxonomies

• Related fields link to other content: Categories, Tags, Members, Forms, or other custom content types (and posts).
• Dynamic List – Lets you define a list by content type and filters (e.g. by category or tag). The list is resolved when the entry is delivered via the API. System taxonomies (Category, Tag, Member, Form) cannot be used as the main content type for a dynamic list; the list is based on custom content types (or posts).

---

​

Field Types

Validation (e.g. required, format) is configured per field in the schema.

---

​

Components

​

What a Component Is

A Component is a reusable content block with its own structure: a component schema defines the fields (text, number, media, relation, or even another component). An instance of a component is a single “block” that fills in those fields.

Show Component details

• Component schema – Defines the block’s structure: name, slug, and field types (and optional settings such as filter fields). It is not a standalone content type; it is only used inside entities or other components.
• Component instance – One filled-in block: it follows one component schema and holds values for that schema’s fields. It can be placed in a component field or as one item in a dynamic zone.

​

How the Component Field Works

• In a content-type schema (or in another component schema), you add a field of type Component.
• You choose which component schemas are allowed for that field.
• You set the limit:
  • Single – The field holds exactly one component instance (e.g. one “Author card”).
  • Multi – The field holds multiple instances of the same component type (e.g. several “Feature” items in one block).

So: Component field = one block type, either once (single) or repeated (multi).

​

Nesting and Limits

• Components can contain other components (nested blocks).
• Maximum nesting depth is enforced (e.g. up to a few levels) so that structures stay manageable and performant.
• Circular references are not allowed (e.g. Component A cannot contain Component B if B contains A). The system validates this when you save the schema.

​

Example

• Component schema “Author Card”: name, email, avatar image.
• Content type “Article” has a field “Author” of type Component, limit Single, allowed type “Author Card”.
• An article entry then has one “Author” block with name, email, and avatar.

---

​

Dynamic Zone

​

What a Dynamic Zone Is

A Dynamic Zone is an ordered list of blocks where each block can be a different type. You define which block types (component schemas) are allowed; for each entry, editors choose which blocks to add and in what order.

Show Dynamic Zone details

• In the schema, the field type is Dynamic Zone.
• You configure the list of allowed component schemas (e.g. Hero, Feature Grid, Testimonials, CTA).
• When editing an entry, the value is an ordered list of blocks; each block specifies its type and its field values.

​

Component vs Dynamic Zone

Aspect	Component	Dynamic Zone
What it holds	One block type, once (single) or repeated (multi)	A list of blocks
Block types per field	One schema (single or multi instances)	Each item can be a different allowed schema
Typical use	Fixed or repeatable block (e.g. author, features)	Page builder: hero, then CTA, then FAQ, etc.

​

Example

• Content type “Landing Page” has a field “Sections” of type Dynamic Zone, with allowed types: Hero, Feature Grid, Testimonials, CTA.
• One page’s “Sections” might be: [Hero, Feature Grid, CTA]. Order and mix are flexible per entry.

---

​

Dynamic List

​

What a Dynamic List Is

A Dynamic List field does not store the actual list of items. It stores configuration: which content type to list and how to filter it (e.g. by category, tag, or other relation). When the entry is delivered via the API, the system uses this configuration to resolve and return the list of matching items.

Show Dynamic List details

• You configure:
  • Content type (model) – Which custom content type (or posts) to list. System taxonomies (Category, Tag, Member, Form) cannot be used as this content type.
  • Related fields – Which relation fields to use for filtering (e.g. category, tag).
  • Filters – For each chosen relation, the selected items (e.g. which categories or tags). Optionally a heading or similar display options.

So: Dynamic List = “list of content of type X filtered by these relation criteria.” Useful for “Related posts”, “Products in this collection”, etc., without storing the full list of IDs in the entry.

​

Configuration and Validation

• Content type (model) is required and must be a custom content type (or post type), not a system taxonomy.
• Filters – When used, you specify which relation(s) to filter by and the selected IDs (or equivalent).
• Related fields – When you use filters, you specify which relation fields those filters apply to.

​

Example

• Content type “Article” has a Dynamic List field “Related articles”.
• Configuration: content type = “Article”; filter by “Primary category” with one or more categories selected.
• When the article is returned via the API, “Related articles” is resolved to the list of articles in those categories (and can optionally include “related to this post” behaviour depending on product behaviour).