block.json and Registration

The first block-editor releases described a block only in JavaScript, with its scripts and styles registered by hand in PHP, so the server, the REST API and the Block Directory knew little about it. block.json moves the description into data:

The blocks live in lumen-catalog/src/blocks/<name>/ and are built into lumen-catalog/build/blocks/<name>/. Each source folder holds a block.json and the files it references:

Source: Block Editor Handbook: File structure of a block

src/Blocks.php is a PHP class in the Lumen\Catalog namespace, autoloaded by Composer like Plugin.php; the JavaScript and SCSS under src/blocks/ are inputs to the build and are not shipped.

A static block: the editor saves its HTML into the post content, and WordPress prints that HTML as it is.

Source: Block Editor Handbook: Metadata in block.json

title and coverUrl are sourced attributes: their values are read back from the saved HTML (the element matching the selector), so they are not repeated in the block comment. bookId, isbn and showIsbn have no source and are stored as JSON in the comment delimiter. The card provides lumen/bookId as context to the blocks inside it (its InnerBlocks, for example the hooked "Buy at your local bookshop" block).

A dynamic block: the editor saves only the comment delimiter with the attributes, and render.php produces the HTML on every request, so a newly published book appears without re-saving any page.

Source: Block Editor Handbook: Metadata in block.json

The block reads postId and postType from its context so that, placed in a single-book template, it leaves the current book out of the list. The context part of its render.php (the rest of the file runs a WP_Query and prints the list with every value escaped; render.php itself is covered in Static and Dynamic Blocks):

Source: Block Editor Handbook: Static or Dynamic rendering of a block

render.php runs inside a closure, so its variables are local to it, but WPCS and Plugin Check still treat them as globals: the lumen_catalog_ prefix keeps the global-prefix rule quiet, while a shorter $lumen_* name is reported, as described in Coding Standards and Static Analysis. view.js is a short ES module that uses Intl.RelativeTimeFormat to rewrite the <time> elements of books published in the last month as "3 days ago"; it imports nothing, and WordPress loads it only on pages that contain the block.

The tables list every top-level field of the 7.1 schema, with the version that added it to register_block_type_from_metadata() where it is later than 5.8.

The Block API version tells the editor how the block expects to be wrapped and where it can run:

Source: Block Editor Handbook: API Versions

The editor canvas runs in an <iframe> so that theme and block styles apply to the content without admin CSS leaking in, and so that viewport-relative units and media queries match the front end. The Site Editor and the template editor have always been iframed. The post editor got there in steps:

So setting "apiVersion": 3 no longer changes where a block runs in 7.1; it states that the block has been tested there. What breaks inside the iframe is code that reaches for the admin page: the editor scripts run in the parent window, but the block’s DOM lives in the iframe’s document. document.querySelector() from an edit component finds nothing, and listeners on window never fire for the canvas. CSS enqueued on admin pages (admin_enqueue_scripts) does not reach the content, and styles added with enqueue_block_editor_assets are copied into the iframe only as a fallback, with a console warning ("was added to the iframe incorrectly"). Use the block’s own editorStyle and style (or enqueue_block_assets, which loads inside the iframe), and get the document from an element:

Source: Block Editor Handbook: Migrating to the iframe editor

The full list of cases to watch for is the "Technical considerations for the iframe editor" section of the handbook page above, which the Make WordPress Core post on the 7.1 change points to; the usual fix is the same: resolve ownerDocument and defaultView from a ref.

@wordpress/scripts finds every block.json under the source path, builds each script, module and style it names, copies block.json and the render file, and with --blocks-manifest writes one PHP file with the metadata of all blocks. viewScriptModule files are only built with --experimental-modules:

Source: Block Editor Handbook: @wordpress/scripts

--source-path replaces the older --webpack-src-dir, which 37.0.0 still accepts. npm run build writes, per block, block.json, index.js with index.asset.php, the CSS (editor.scss imported by index.js becomes index.css, style.scss becomes style-index.css, each with an -rtl twin for right-to-left languages), render.php, view.js with view.asset.php, and build/blocks/blocks-manifest.php for all blocks. book-card/index.asset.php returns the WordPress packages the script imports, which are loaded from core rather than bundled (react-jsx-runtime, wp-block-editor, wp-blocks, wp-components, wp-i18n), and a content hash as the version (29cc23afde8cfc4ca016). view.asset.php has 'type' => 'module' and no dependencies. blocks-manifest.php returns an array keyed by folder name, with each block.json converted to PHP (abridged):

Source: Block Editor Handbook: @wordpress/scripts, build-blocks-manifest

The manifest is a build artefact: it is regenerated on every build and shipped with build/, and it must be rebuilt whenever a block.json changes, or the server keeps registering the old metadata.

The client side does not read block.json from disk. When the editor loads, WordPress serializes the server registry (get_block_editor_server_block_settings()) into the page, and editorScript calls registerBlockType() with the metadata and the JavaScript-only settings:

Source: Block Editor Handbook: Registration of a block

registerBlockType() merges its defaults, the server-bootstrapped definition and the object passed in, then runs the blocks.registerBlockType filter; metadata.name is enough because the server sent the rest. A block registered only in JavaScript has no server definition: no assets are enqueued for it, render_block() does not know its attribute defaults, and the REST block-types endpoint does not list it.

WP_Block_Type_Registry::get_instance() holds every block registered on the request. A small script run with wp eval-file shows what the server made of each block.json:

Source: Code Reference: WP_Block_Type_Registry

The attributes after the block’s own are added by WordPress: lock and metadata for every block, className unless supports.className is false, and one or more per support (align, style, backgroundColor, textColor, fontSize, anchor). render_callback is the closure built from render. The script lumen-book-card-editor-script points at build/blocks/book-card/index.js with the five dependencies and the hash version from index.asset.php; the style lumen-book-card-style uses the block’s version, 0.1.0 (or the file’s modification time when SCRIPT_DEBUG is on). WP_Block_Metadata_Registry::has_metadata( $path . '/book-card' ) returns true, which confirms that the metadata came from the manifest rather than from block.json.

A page containing the three blocks is stored as:

Source: Block Editor Handbook: Data Flow and Data Format

and served at https://lumenpress.test/new-books/ as (inside Post Content):

Between them, lumen/latest-books printed a <ul class="wp-block-lumen-latest-books"> with Night Ferry and A Map of Quiet Rooms. The <head> of the same page carries the two style files inline (lumen-book-card-style-inline-css, lumen-latest-books-style-inline-css) and the module <script id="lumen-latest-books-view-script-module-js-module" src="…/build/blocks/latest-books/view.js?ver=5a9580424a03f2b76fc4" type="module">. A page without the blocks loads none of them.

WordPress 7.0 added blocks that need no JavaScript and no build step. A block registered in PHP with a render_callback and 'supports' => array( 'autoRegister' => true ) is registered in the editor automatically, previewed with server-side rendering, and given inspector controls generated from its attributes. Lumen uses one for its submissions call to action, the second half of the Blocks class:

Source: Make WordPress Core: PHP-only block registration

How it works in 7.1.3, as read from the registry on the running site:

The limits are deliberate: no InnerBlocks, no save, no rich text, media pickers or textareas, no sourced attributes, and each attribute change costs a REST round trip for the preview (in which postId context is not populated in 7.1). PHP-only blocks suit small, configurable, server-rendered pieces such as the call to action; the book card stays a JavaScript block. WordPress 6.9, the plugin’s minimum, has no autoRegister: the block renders on the front end, but nothing registers it in the editor.

A block’s icon in block.json is a Dashicon slug. For an SVG, set icon in registerBlockType() to an element or an object with src, background and foreground; a PHP-only block, which has no JavaScript, uses a Dashicon slug.

WordPress 7.1 added an Icons API (wp_register_icon_collection(), wp_register_icon(), wp_get_icon() and the read-only /wp/v2/icons and /wp/v2/icon-collections REST routes). It does not change block type icons: in 7.1.3 the editor still resolves a block’s icon exactly as before. The registry feeds the core Icon block’s picker, which groups icons by collection, and lets PHP print a sanitized SVG. Lumen registers its own collection for use in content and in render.php:

Source: Make WordPress Core: Registering and rendering SVG icons in WordPress 7.1

wp_get_icon() returned the SVG with width and height set to 20, role="img" and aria-label="Book", and GET /wp/v2/icons/lumen (for a user who can edit_posts) returned ["lumen/open-book"]. Icon names are collection/icon-name, the collection must exist first, core is the collection WordPress uses for its own icons, and the SVG is reduced to a small allowlist of elements (strokes are removed), so icons should be drawn with fills.

Source: Code Reference: WP_Block_Type_Registry::register()

block.json is not a trust boundary. Attributes come from post content, which any user with edit_posts can write by hand in the code editor or through the REST API, so render.php and render callbacks treat them as untrusted input: cast numbers, sanitize_key() slugs and escape every value on output, as the Lumen callbacks do; get_block_wrapper_attributes() is the one value printed unescaped, because it returns escaped attributes. A dynamic block that queries the database must not reveal drafts or private posts: get_posts() returns only published posts by default, and any change to post_status needs a capability check. Static blocks are filtered by KSES on save for users without unfiltered_html, so markup a block’s save produces must survive KSES, or the block becomes invalid when an Author edits it. The fuller treatment is in Security for Developers.

None of the three older books (WordPress All-in-One For Dummies, Pro WordPress, Ultimate WordPress Handbook) covers block development or block.json; Pro WordPress builds features as shortcodes and widgets, and the Ultimate WordPress Handbook still says "reusable blocks", which 6.3 renamed synced patterns. Tutorials written for WordPress 5.x are the usual source of outdated registration code:

The full list for the section is in Where Older Books and Tutorials Are Outdated.