Components and Dynamic Zones

This guide describes how to use reusable component fields and dynamicZone fields in Notty CMS schemas and Content API payloads.

Data model

• component: embeds one component schema (repeatable: false) or an array (repeatable: true).
• dynamicZone: array of blocks; each block must include __component.
• Component/block id is optional in API payloads and responses.
• Current implementation stores component and dynamic zone values as JSON columns.

Component schema example

{
  "uid": "shared.seo-meta",
  "category": "shared",
  "info": {
    "displayName": "SEO Meta",
    "description": "SEO metadata"
  },
  "attributes": {
    "metaTitle": { "type": "string", "maxLength": 60 },
    "metaDescription": { "type": "text", "maxLength": 160 }
  }
}

Content schema example

{
  "kind": "collectionType",
  "info": {
    "singularName": "page",
    "pluralName": "pages",
    "displayName": "Page"
  },
  "attributes": {
    "title": { "type": "string" },
    "seo": {
      "type": "component",
      "component": "shared.seo-meta"
    },
    "blocks": {
      "type": "dynamicZone",
      "components": ["blocks.hero", "shared.seo-meta"]
    }
  }
}

Content API examples

Create (POST /api/content/page)

{
  "title": "Home",
  "seo": {
    "metaTitle": "Home page"
  },
  "blocks": [
    {
      "__component": "blocks.hero",
      "title": "Welcome"
    },
    {
      "__component": "shared.seo-meta",
      "metaTitle": "Inline SEO"
    }
  ]
}

Response (GET /api/content/page/:id)

{
  "id": 1,
  "title": "Home",
  "seo": {
    "metaTitle": "Home page"
  },
  "blocks": [
    {
      "__component": "blocks.hero",
      "title": "Welcome"
    },
    {
      "__component": "shared.seo-meta",
      "metaTitle": "Inline SEO"
    }
  ]
}

Update with block ids (PUT /api/content/page/:id)

{
  "blocks": [
    {
      "id": 202,
      "__component": "shared.seo-meta",
      "metaTitle": "Updated first block"
    },
    {
      "id": 101,
      "__component": "blocks.hero",
      "title": "Updated second block"
    }
  ]
}

Update without block ids

{
  "blocks": [
    {
      "__component": "shared.seo-meta",
      "metaTitle": "No id block"
    },
    {
      "__component": "blocks.hero",
      "title": "No id block 2"
    }
  ]
}

Update rules (id, no id, order)

1. id in component and dynamic zone items is optional.
2. If id is sent, it is preserved in stored JSON and returned by API.
3. If id is omitted, items are stored and returned without id.
4. Block order is exactly the order from the request array.
5. On update, the full field value is replaced with the provided payload.

Validation rules

• dynamicZone must define non-empty components.
• Each __component in payload must be present in components.
• Referenced component schemas must exist.
• Component field payload must match component attribute types and required constraints.