Skip to content
Skip to contents
Skip to reading controls

Search skills⌘K

Setting the file. One moment.

This file

Type

Size

Lines

Position

WordPress
/
WordPress/agent-skills

Block JSON · Wp Block Development · WordPress/agent-skills · Skills Docs

Repo No. 26 · Wp Block Development

↖Back to the cover

Blueprint
Wordpress Router
Wp Abilities API
Wp Abilities Audit
Wp Abilities Verify
Wp Block Development
Appendix · 11 subchapters
Wp Block Themes
Wp Env
Wp Interactivity API
Wp Patterns
Wp Performance
Wp Phpstan
Wp Playground
Wp Plugin Development
Wp Plugin Directory Guidelines
Wp Project Triage
Wp REST API
Wp Wpcli And Ops
Wpds

19 skills · 52 min

Skill 06 · Wp Block Development

Subchapter 6.2

Block JSON

references/block-json.mdMarkdown2 KBView on GitHub

`block.json` (metadata) guidance

Use this file when you’re editing block.json fields or choosing between script/styles fields.

Practical rules

6Up to skill 6Wp Block Development

On this page

block.json (metadata) guidance
Practical rules
API version + schema
Modern asset fields to know
Helpful upstream references

This file

Number: 6.2
Position: 2 of 11
Type: Markdown
Size: 2 KB

Nearby

Previous Attributes And Serialization
Next Creating New Blocks

Source

Treat name as stable API (renaming breaks existing content).
Prefer adding new functionality without changing saved markup; if markup must change, add a deprecated version.
Keep assets scoped: editor assets should not ship to frontend unless needed.

API version + schema

WordPress 6.9+ requires apiVersion 3. The block.json schema now only validates blocks with apiVersion: 3. Older versions (1 or 2) trigger console warnings when SCRIPT_DEBUG is enabled.

Why apiVersion 3 matters:

The post editor will be iframed if all registered blocks have apiVersion 3+.
WordPress 7.0 will always use the iframe editor regardless of apiVersion.
Benefits: style isolation (admin CSS won’t affect editor content), correct viewport units (vw, vh), native media queries.

Migration checklist:

Update apiVersion to 3 in block.json.
Ensure all style handles are declared in block.json (styles not included won’t load in the iframe).
Test blocks that rely on third-party scripts (window scoping may differ).
Add a $schema to improve editor tooling and validation.

References:

Block metadata: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/ (opens in a new tab)
Block API versions: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/ (opens in a new tab)
Iframe migration guide: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/block-migration-for-iframe-editor-compatibility/ (opens in a new tab)
Block schema index: https://schemas.wp.org/ (opens in a new tab)

Modern asset fields to know

This is not a full schema; it’s a “what matters in practice” list:

editorScript / editorStyle: editor-only assets.
script / style: shared assets.
viewScript / viewStyle: frontend view assets.
viewScriptModule: module-based frontend scripts (newer WP).
render: points to a PHP render file for dynamic blocks (newer WP).

Helpful upstream references

Block metadata reference (block.json):
- https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/ (opens in a new tab)
Block.json schema (editor tooling):
- https://schemas.wp.org/trunk/block.json (opens in a new tab)

ReferenceAttributes And Serialization ReferenceCreating New Blocks

references/block-json.md

(opens in a new tab)

Raw file(opens in a new tab)

WordPress/agent-skills(opens in a new tab)