Block Type Contracts

This reference describes the shipped published core block types, their editable fields, translations, child rules and public rendering. The Block Types administration screen exposes the same contract as read-only information; it does not define a custom schema or build new editing forms.

Plugins support declaration-only plugin block hooks through PluginBlockTypeDefinition, PluginBlockPackDefinition, and PluginBlockRegistry. Enabled plugins can expose plugin-owned handles such as analytics-tools::score-card for discovery, but these declarations do not replace the shipped core block contracts, core block views, core seeders, or block editing services. Unqualified core-style handles such as hero remain core-owned and are rejected for plugin declarations.

A Block Type Contract is the current technical agreement for how one block type behaves across CMS layers:

• catalog identity: slug, label, category, status, and system or container metadata
• admin form source: which Blade partial currently edits the block and which fields it exposes
• validation and request handling: how WebBlocks\Cms\Http\Requests\Admin\BlockRequest currently normalizes and validates block payloads
• storage ownership: which values live on blocks, dedicated translation rows, block_media, or related records
• translation ownership: which user-facing fields are locale-owned
• shared ownership: which settings or relationships remain shared across locales
• media or relationship ownership: direct media_id, ordered block_media, navigation lookups, or same-page relationships
• child support: whether the block is a container and whether child types are restricted
• public renderer source: which public Blade partial renders the block today
• renderer root contract: whether the block owns its public root markup or relies on the generic wrapper path
• portability and revisions: whether the current storage shape should continue to travel through revisions, clone, export/import, and promotion
• tests and gaps: known focused coverage, unclear behavior, or compatibility debt

Status terms used below:

• clear: admin form, request handling, storage, and renderer mostly line up
• mostly clear: current contract is understandable but has one notable caveat
• transitional: current contract intentionally carries a compatibility path or mixed ownership pattern
• needs review: the installed contract needs confirmation before relying on the behavior
• legacy/fallback: published behavior depends on a fallback or compatibility path

Current and future contract work should keep these ownership rules explicit:

• user-facing copy belongs in translation rows when the block is locale-owned
• shared operational or settings data belongs in shared block settings or explicit relationships
• media should use media_id or block_media ownership paths where applicable
• avoid moving user-facing content into arbitrary shared settings
• keep compatibility storage paths documented when they still affect public output or imports

From CMS 1.98.6, the compatible settings model/API field is backed by relational records. Known core fields use finite typed appearance, media, navigation and content columns. Content bindings, collection configuration and application instance values have separate records; typed nodes retain structure, ordering and historical/plugin extensions. CMS 1.98.8 removed the temporary JSON rollback copies; SQL is authoritative. The editor, translation ownership, API payloads and renderer methods keep their existing contracts; storage migration does not move locale-owned copy into shared settings.

CMS 1.105.9 adds revisioned authoring_settings_schema discovery for all 55 published core blocks. Read the separate create, PATCH and admin write flags before supplying a field. New or changed values must satisfy the declared types, enums and bounds; unsupported fields return validation errors instead of being silently accepted or cleared. This remains a code-owned contract, not an editable schema or a generated form builder.

Unchanged historical values survive unrelated edits and trusted cloning, staging and revisions. New blocks and complete replacements must pass current validation. Plugins without a schema retain their existing behavior; optional plugin scalar schemas do not replace media, application or Dynamic Content validators. HTML remains human-only.

See Per-block authoring settings schemas for operation metadata, compatibility rules and the read-only webblocks:blocks:audit-settings compatibility command. The separate catalog audit below checks shipped forms and renderers, rather than stored settings.

The reference uses the shipped catalog, forms and renderers.

• catalog source: src/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• block edit request normalization: src/Http/Requests/Admin/BlockRequest.php
• persistence helpers: src/Support/Blocks/BlockPayloadWriter.php, src/Support/Blocks/BlockTranslationWriter.php, src/Support/Blocks/BlockTranslationResolver.php
• translation registry: src/Support/Blocks/BlockTranslationRegistry.php
• admin forms: resources/views/admin/blocks/types/*.blade.php
• public renderers: resources/views/pages/partials/blocks/*.blade.php
• coverage references: block catalog, rendering, translation, and slug-specific tests under tests/Feature/

Published core block types currently documented here: 55.

Catalog reconciliation: WebBlocks CMS 1.105.8. The table covers all 55 published core definitions; seven additional definitions remain unpublished. Later phase notes below are historical records, not a second current catalog count.

Operators and developers can run this read-only catalog check:

The command is read-only.

• it does not modify the database
• it does not depend on installed site content
• it reads the shipped core catalog definitions
• it verifies shipped admin form and public renderer file presence
• it reports translation-family metadata and basic container support

The command is a freshness aid for catalog and file-presence drift. It is not a substitute for the fuller contract notes in this document.

Open contract details read-only in Admin -> System -> Block Types.

• each row can open a Block Type Contract modal
• the modal is informational only and does not submit updates
• it shows catalog, admin form, storage, translation, media or relationship, child, renderer, and gap details from shipped code
• it does not make Block Types admin a schema editor or form builder
• custom or draft block types can still open the modal, but may show No shipped contract is documented for this block type yet. when no core contract is defined

Published block types do not each have their own dedicated request class today.

• WebBlocks\Cms\Http\Requests\Admin\BlockRequest is the shared edit request path
• slug-specific branches inside that request normalize fields into current canonical storage
• WebBlocks\Cms\Support\Blocks\BlockPayloadWriter persists the normalized block payload
• WebBlocks\Cms\Support\Blocks\BlockTranslationWriter moves locale-owned fields into translation rows for registered families
• WebBlocks\Cms\Support\Blocks\BlockTranslationResolver resolves translated or fallback values back onto a renderable block instance

Legacy Gallery and Table settings can remain readable when canonical translated content or ordered media is absent. Historical field fallbacks do not make those fields the preferred authoring format. Use the fields documented in the current block matrix.

Draft catalog rows and renderer-only compatibility handles are not published core authoring contracts. Discovery and the read-only contract modal may report that no shipped contract is available for such a row.