From f1c8591a3c9a9b13ae696abf6ad459fd0812d724 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fabian=20K=C3=A4gy?= <mail@fabian-kaegy.de>
Date: Wed, 20 Jul 2022 11:40:42 +0200
Subject: [PATCH] Docs: Add `variations` key to `block.json` JSON schema
 definition (#42539) (#42553)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 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>

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
---
 .../block-api/block-metadata.md               | 40 +++++++++
 schemas/json/block.json                       | 87 +++++++++++++++++++
 2 files changed, 127 insertions(+)

diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md
index 801a3f0fa47f6..b8f799acedc6b 100644
--- a/docs/reference-guides/block-api/block-metadata.md
+++ b/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",
@@ -407,6 +416,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))
diff --git a/schemas/json/block.json b/schemas/json/block.json
index 2572b322d90b2..cba5919a9112f 100644
--- a/schemas/json/block.json
+++ b/schemas/json/block.json
@@ -466,6 +466,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" ],