Field types

Each collection field has a type from App\Enums\FieldTypeEnum. The type drives validation, normalization, EAV storage shape, and which React input renders in the item form.

Common settings

Available on (almost) every field via collections_fields.settings JSON:

Flags are normalized with a truthy check (boolean / 1 / '1' / 'true' / 'on'). Localized string maps are validated against the project’s enabled content locales (not hard-coded en/it) — see Project settings.

Field packs

Deterministic field bundles you can apply in one shot onto an existing collection from the Fields UI (Add field pack…) or via AI (ManageCollections apply_field_pack). Existing field names are skipped; missing ones are created through the same settings pipeline as HTTP create field.

HTTP: POST /collections/{collection}/field-packs/{pack} (can-edit-collections). Source: app/Support/Collections/FieldPacks/.

How to add a field pack

1. Add a *FieldPack class with a static definition() (see SeoInlineFieldPack).
2. Register it in FieldPackRegistry::all().
3. Ship docs + a Pest apply/skip test.

Collection packs

Starter collections. Prefer these for SEO entity / Articles / Pages / Products / Categories. Apply from the collections list (Create from pack…) or AI (apply_collection_pack). Missing dependencies are auto-created. Existing collection slugs are reused; missing fields/relations are added.

HTTP: POST /collections/packs/{pack} (can-create-collections), optional body name / slug. Source: app/Support/Collections/CollectionPacks/.

How to add a collection pack

1. Add a *CollectionPack class with definition() (key, label, collection, fields, requires, relations).
2. Register it in CollectionPackRegistry::all().
3. Ship docs + Pest (deps + relations + idempotent apply).

Model note: SEO is a collection; Articles/Pages/Products link via many_to_one. Use seo_inline only when you need denormalized seo_* fields on an existing collection.

Field conditions

Optional per-field rules evaluated against other field values on the item form (client) and for required on the server:

{
  "logic": "and",
  "rules": [{ "field": "kind", "operator": "equals", "value": "custom" }],
  "hidden": false,
  "readonly": false,
  "required": true
}

Operators: equals, not_equals, empty, not_empty. Logic is AND only (no OR / nested groups yet). When rules match, any of hidden / readonly / required present in the object override the base settings for that request.

Collection form layout

Presentation metadata on collections.form_layout (JSON), not a field type. Fields stay leaves; layout groups them into optional tabs + collapsible sections:

{
  "version": 1,
  "tabs": [{ "id": "main", "label": { "en": "Main" } }],
  "sections": [
    {
      "id": "details",
      "tab_id": "main",
      "label": { "en": "Details" },
      "collapsible": true,
      "collapsed": false,
      "field_ids": [1, 2]
    }
  ]
}

layout_width / layout_starts_new_row still apply inside each section. Unplaced fields render in an “Other” group. Endpoint: PUT /collections/{collection}/form-layout.

Storage helpers on the enum

Array storage types

These return true from isArrayStorage():

multiselect, checkbox_group, checkbox_group_tree, tag, files, one_to_many, many_to_many, blocks, m2a, relation_many.

Relation types

These return true from isRelationType():

relation, many_to_one, one_to_many, many_to_many, relation_tree, relation_many.

Multiple relation IDs (isMultipleRelationType()): one_to_many, many_to_many, relation_many.

Every field type

Text and scalars

Choice

Date, map, color

Files and media

* See callout above for allow_multiple.

Relations

Shared relation settings (where applicable):

• related_collection_id — target collection
• display_field — field name used as label
• display_template — optional label template
• filter — option list filter
• allow_duplicates — whether the same related id may appear more than once
• junction_fields — many_to_many only: [{ "name": "sort", "type": "number" }] mini-schema for per-link meta (string | number | boolean)

† Not in isRelationType().

Normalized storage shapes

Blocks field

blocks defines its schema inline on the field itself instead of pointing to another collection like m2a.

Settings

{
  "max_blocks_depth": 3,
  "block_types": [
    {
      "key": "rich_text",
      "label": "Rich text",
      "fields": [
        {
          "name": "title",
          "type": "string",
          "translatable": true,
          "settings": {}
        },
        {
          "name": "body",
          "type": "wysiwyg",
          "translatable": true,
          "settings": {}
        }
      ]
    },
    {
      "key": "media",
      "label": "Media",
      "fields": [
        { "name": "image", "type": "image", "settings": {} },
        {
          "name": "caption",
          "type": "string",
          "translatable": true,
          "settings": {}
        }
      ]
    }
  ]
}

max_blocks_depth is per field (default 3, absolute ceiling 5). Nested blocks fields inherit the root field’s max; deeper blocks types are stripped on save.

Value shape

[
  {
    "id": "11111111-1111-1111-1111-111111111111",
    "type": "rich_text",
    "data": {
      "title": { "en": "Hello", "it": "Ciao" },
      "body": { "en": "<p>Body</p>" }
    }
  }
]

Notes

• wysiwyg uses TipTap in the admin UI (toolbar: bold/italic/strike/headings/lists/blockquote/link/undo/redo). Paste from Word/HTML is accepted; WysiwygHtmlSanitizer strips scripts and non-allowlisted tags on normalize/save.
• The blocks field itself is not translatable; nested fields may be.
• Nested file fields (image, file, files) expand on the public API just like top-level file fields (including inside nested blocks).
• Nested relations (m2a, many_to_many, one_to_many) are JSON-embedded inside block.data — same link shapes as top-level (m2a { related_collection_id, related_item_id }, m2m { related_item_id, meta }). There is no junction table for nested paths; SQL filter/query on nested m2m is out of scope.
• Nested field settings.conditions use the same AND / equals / empty operators as collection fields, but evaluate against sibling keys in block.data, not top-level item fields.
• Builder UX: drag-and-drop, duplicate, delete, collapse/expand, text summary in the header, move up/down. No live frontend/site preview.
• blocks is distinct from top-level m2a: blocks stores inline typed fragments; top-level m2a links out to items. You can also put an m2a field inside a block type.
• Golden path: an Articles collection with a body blocks field — section → nested blocks → leaf (rich_text / media); optional related_modules (m2a) and related_articles (many_to_many) block types; conditional nested fields (e.g. show video_url when media_kind === video).

Nested blocks example

{
  "max_blocks_depth": 3,
  "block_types": [
    {
      "key": "rich_text",
      "label": "Rich text",
      "fields": [
        {
          "name": "title",
          "type": "string",
          "translatable": true,
          "settings": {}
        },
        {
          "name": "body",
          "type": "wysiwyg",
          "translatable": true,
          "settings": {}
        }
      ]
    },
    {
      "key": "section",
      "label": "Section",
      "fields": [
        {
          "name": "heading",
          "type": "string",
          "translatable": true,
          "settings": {}
        },
        {
          "name": "blocks",
          "type": "blocks",
          "translatable": false,
          "settings": {
            "block_types": [
              {
                "key": "rich_text",
                "label": "Rich text",
                "fields": [
                  {
                    "name": "body",
                    "type": "wysiwyg",
                    "translatable": true,
                    "settings": {}
                  }
                ]
              },
              {
                "key": "media",
                "label": "Media",
                "fields": [{ "name": "image", "type": "image", "settings": {} }]
              }
            ]
          }
        }
      ]
    },
    {
      "key": "related_modules",
      "label": "Related modules",
      "fields": [
        {
          "name": "modules",
          "type": "m2a",
          "settings": { "allowed_collection_ids": [2] }
        }
      ]
    },
    {
      "key": "related_articles",
      "label": "Related articles",
      "fields": [
        {
          "name": "articles",
          "type": "many_to_many",
          "settings": { "related_collection_id": 1, "display_field": "title" }
        }
      ]
    }
  ]
}

Nested conditions example

Inside a block type, conditions reference sibling field names:

{
  "name": "video_url",
  "type": "string",
  "settings": {
    "conditions": {
      "logic": "and",
      "rules": [
        { "field": "media_kind", "operator": "equals", "value": "video" }
      ],
      "required": true
    }
  }
}

Related pages

• Collections data model
• Collection items
• AI assistant model — tools that create/edit fields and items