Docs: Add variations key to block.json JSON schema definition (#4…

…2539)

* add variations key to block.json JSON schema definition
* Update docs/reference-guides/block-api/block-metadata.md with information about variations key

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

docs/reference-guides/block-api/block-metadata.md

@@ -40,6 +40,15 @@ Starting in WordPress 5.8 release, we encourage using the `block.json` metadata
 			"message": "This is a notice!"
 		}
 	},
+	"variations": [
+		{
+			"name": "example",
+			"title": "Example",
+			"attributes": {
+				"message": "This is an example!"
+			},
+		}
+	]
 	"editorScript": "file:./build/index.js",
 	"script": "file:./build/script.js",
 	"viewScript": "file:./build/view.js",
@@ -421,6 +430,37 @@ It provides structured example data for the block. This data is used to construc
 
 See the [the example documentation](/docs/reference-guides/block-api/block-registration.md#example-optional) for more details.
 
+### Variations
+
+- Type: `object[]`
+- Optional
+- Localized: Yes (`title`, `description`, and `keywords` of each variation only)
+- Property: `variations`
+- Since: `WordPress 5.9.0`
+
+```json
+{
+	"variations": [
+		{
+			"name": "example",
+			"title": "Example",
+			"attributes": {
+				"level": 2,
+				"message": "This is an example!"
+			},
+			"scope": [ "block" ],
+			"isActive": [ "level" ]
+		}
+	]
+}
+```
+
+Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality. Each block variation is differentiated from the others by setting some initial attributes or inner blocks. Then at the time when a block is inserted these attributes and/or inner blocks are applied.
+
+_Note: In JavaScript you can provide a function for the `isActive` property, and a React element for the `icon`. In the `block.json` file both only support strings_
+
+See the [the variations documentation](/docs/reference-guides/block-api/block-variations.md) for more details.
+
 ### Editor Script
 
 -   Type: `WPDefinedAsset` ([learn more](#wpdefinedasset))

schemas/json/block.json

@@ -482,6 +482,93 @@
 					}
 				}
 			]
+		},
+		"variations": {
+			"type": "array",
+			"description": "Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality.",
+			"items": {
+				"type": "object",
+				"required": [ "name", "title" ],
+				"additionalProperties": false,
+				"properties": {
+					"name": {
+						"type": "string",
+						"description": "The unique and machine-readable name."
+					},
+					"title": {
+						"type": "string",
+						"description": "A human-readable variation title."
+					},
+					"description": {
+						"type": "string",
+						"description": "A detailed variation description."
+					},
+					"category": {
+						"description": "A category classification, used in search interfaces to arrange block types by category.",
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"enum": [
+									"text",
+									"media",
+									"design",
+									"widgets",
+									"theme",
+									"embed"
+								]
+							}
+						]
+					},
+					"icon": {
+						"description": "An icon helping to visualize the variation. It can have the same shape as the block type.",
+						"type": "string"
+					},
+					"isDefault": {
+						"type": "boolean",
+						"default": false,
+						"description": "Indicates whether the current variation is the default one."
+					},
+					"attributes": {
+						"type": "object",
+						"description": "Values that override block attributes."
+					},
+					"innerBlocks": {
+						"type": "array",
+						"items": {
+							"type": "array"
+						},
+						"description": "Initial configuration of nested blocks."
+					},
+					"example": {
+						"type": "object",
+						"description": "Example provides structured data for the block preview. You can set to undefined to disable the preview shown for the block type."
+					},
+					"scope": {
+						"type": "array",
+						"description": "The list of scopes where the variation is applicable.",
+						"items": {
+							"enum": [ "inserter", "block", "transform" ]
+						},
+						"default": [ "inseter", "block" ]
+					},
+					"keywords": {
+						"type": "array",
+						"description": "An array of terms (which can be translated) that help users discover the variation while searching.",
+						"items": {
+							"type": "string"
+						}
+					},
+					"isActive": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						},
+						"description": "The list of attributes that should be compared. Each attributes will be matched and the variation will be active if all of them are matching."
+					}
+				}
+			}
 		}
 	},
 	"required": [ "name", "title" ],