{"id":70,"date":"2024-10-03T11:59:36","date_gmt":"2024-10-03T16:59:36","guid":{"rendered":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/?page_id=70"},"modified":"2025-04-03T09:30:59","modified_gmt":"2025-04-03T13:30:59","slug":"block-json","status":"publish","type":"page","link":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/handbook\/wp-core\/block-architecture\/block-json\/","title":{"rendered":"block.json"},"content":{"rendered":"\n<p>Review the&nbsp;<a href=\"https:\/\/developer.wordpress.org\/block-editor\/getting-started\/fundamentals\/block-json\/\">official block.json&nbsp;documentation<\/a> for an introduction to this file.<\/p>\n\n\n\n<p>The&nbsp;<code>block.json<\/code>&nbsp;file simplifies the process of defining and registering a block by using the same block\u2019s definition in JSON format to register the block on both the server and the client (Block Editor).<\/p>\n\n\n\n<p>The&nbsp;<a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/\">Metadata in block.json<\/a>&nbsp;documentation has a comprehensive guide on all the properties you can use in a&nbsp;<code>block.json<\/code>&nbsp;file for a block. Some of the most common options allow you to specify:<\/p>\n\n\n\n<ul><li>The block\u2019s basic metadata.<\/li><li>The files that dictate the block\u2019s functionality, appearance, and output.<\/li><\/ul>\n\n\n\n<h3 id=\"basic-metadata-of-a-block\">Basic metadata of a block<\/h3>\n\n\n\n<p>Using&nbsp;<code>block.json<\/code>&nbsp;properties, you can define how the block will be uniquely identified and what information is displayed in the Block Editor. These properties include:<\/p>\n\n\n\n<ul><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#api-version\"><code>apiVersion<\/code><\/a>:<\/strong>&nbsp;Specifies the&nbsp;<a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-api-versions\/\">API<\/a>&nbsp;version the block uses. Use the latest version unless you have specific requirements.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#name\"><code>name<\/code><\/a>:<\/strong>&nbsp;The unique name of the block, including namespace (e.g.,&nbsp;<code>my-plugin\/my-custom-block<\/code>).<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#title\"><code>title<\/code><\/a>:<\/strong>&nbsp;The display title for the block, shown in the Inserter.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#category\"><code>category<\/code><\/a>:<\/strong>&nbsp;The category under which the block appears in the Inserter. Common categories include&nbsp;<code>text<\/code>,&nbsp;<code>media<\/code>,&nbsp;<code>design<\/code>,&nbsp;<code>widgets<\/code>, and&nbsp;<code>theme<\/code>.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#icon\"><code>icon<\/code><\/a>:<\/strong>&nbsp;An icon representing the block in the Inserter. This can be a&nbsp;<a href=\"https:\/\/developer.wordpress.org\/resource\/dashicons\">Dashicon<\/a>&nbsp;slug or a custom SVG icon.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#description\"><code>description<\/code><\/a>:<\/strong>&nbsp;A short description of the block, providing more context than the title.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#keywords\"><code>keywords<\/code><\/a>:<\/strong>&nbsp;An array of keywords to help users find the block when searching.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#text-domain\"><code>textdomain<\/code><\/a>:<\/strong>&nbsp;The text domain for the block, used for internationalization.<\/li><\/ul>\n\n\n\n<h3 id=\"files-for-the-blocks-behavior-output-or-style\">Files for the block\u2019s behavior, output, or style<\/h3>\n\n\n\n<p>The&nbsp;<code>block.json<\/code>&nbsp;file also allows you to specify the essential files for a block\u2019s functionality:<\/p>\n\n\n\n<ul><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#editor-script\"><code>editorScript<\/code><\/a>:<\/strong>&nbsp;A JavaScript file or files for use only in the Block Editor.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#editor-style\"><code>editorStyle<\/code><\/a>:<\/strong>&nbsp;A CSS file or files for styling within the Block Editor.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#script\"><code>script<\/code><\/a>:<\/strong>&nbsp;A JavaScript file or files loaded in both the Block Editor and the front end.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#style\"><code>style<\/code><\/a>:<\/strong>&nbsp;A CSS file or files applied in both the Block Editor and the front end.<\/li><li><strong><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-metadata\/#view-script\"><code>viewScript<\/code><\/a>:<\/strong>&nbsp;A JavaScript file or files intended solely for the front end.<\/li><\/ul>\n\n\n\n<h2>Schema Validation<\/h2>\n\n\n\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-full\"><img loading=\"lazy\" width=\"538\" height=\"376\" src=\"\/gutenberg\/files\/2025\/04\/block-json-schema-1.png\" alt=\"\" class=\"wp-image-672\"\/><figcaption>VSCode validating the block.json file for WordPress 5.8<\/figcaption><\/figure><\/div>\n\n\n\n<p>The first line of block.json should be a $schema property that defines a schema for the file. This will help your code editor provide validation and autocomplete of valid JSON Properties. <\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>`\"$schema\": \"https:\/\/schemas.wp.org\/trunk\/block.json\",`<\/code><\/pre>\n\n\n\n<p>Setting the $schema to <code>\/trunk<\/code> version will load the latest. However we are usually several versions behind in WordPress so you can instead set the $schema property to use a <code>\/wp\/x.x\/<\/code> specific version in the url:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>`\"$schema\": \"https:\/\/schemas.wp.org\/wp\/5.8\/block.json\",`<\/code><\/pre>\n\n\n\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img loading=\"lazy\" width=\"560\" height=\"299\" src=\"\/gutenberg\/files\/2025\/04\/block-json-schema-2.png\" alt=\"\" class=\"wp-image-673\"\/><figcaption>Autocomplete in VSCode<\/figcaption><\/figure><\/div>\n","protected":false},"excerpt":{"rendered":"<p>Review the&nbsp;official block.json&nbsp;documentation for an introduction to this file. The&nbsp;block.json&nbsp;file simplifies the process of defining and registering a block by using the same block\u2019s definition in JSON format to register the block on both the server and the client (Block Editor). The&nbsp;Metadata in block.json&nbsp;documentation has a comprehensive guide on all the properties you can use [&hellip;]<\/p>\n","protected":false},"author":3670,"featured_media":0,"parent":98,"menu_order":5,"comment_status":"closed","ping_status":"closed","template":"","meta":[],"status-is-a-reserved-term":[],"assignee":[],"_links":{"self":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/70"}],"collection":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/users\/3670"}],"replies":[{"embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/comments?post=70"}],"version-history":[{"count":7,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/70\/revisions"}],"predecessor-version":[{"id":674,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/70\/revisions\/674"}],"up":[{"embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/98"}],"wp:attachment":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/media?parent=70"}],"wp:term":[{"taxonomy":"status-is-a-reserved-term","embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/status-is-a-reserved-term?post=70"},{"taxonomy":"assignee","embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/assignee?post=70"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}