Font Library: Add font collection JSON schema (#57736)

* move font family to their on definition

* adding font-collection.json schema

* adding settings

* updating README

* update property name

* resolve json schema references

* throw error on definition not found

* add description

* disallow additional properties

* fix typo in function name

Co-authored-by: Jeff Ong <jonger4@gmail.com>

* fix typo in function name

Co-authored-by: Jeff Ong <jonger4@gmail.com>

* fix wording

Co-authored-by: Jeff Ong <jonger4@gmail.com>

* remove unwanted comment

Co-authored-by: Jeff Ong <jonger4@gmail.com>

* format  js

---------

Co-authored-by: Jeff Ong <jonger4@gmail.com>

bin/api-docs/gen-theme-reference.js

@@ -74,6 +74,42 @@ const keys = ( maybeObject ) => {
 	return Object.keys( maybeObject );
 };
 
+/**
+ * Get definition from ref.
+ *
+ * @param {string} ref
+ * @return {Object} definition
+ * @throws {Error} If the referenced definition is not found in 'themejson.definitions'.
+ *
+ * @example
+ * getDefinition( '#/definitions/typographyProperties/properties/fontFamily' )
+ *  // returns themejson.definitions.typographyProperties.properties.fontFamily
+ */
+const resolveDefinitionRef = ( ref ) => {
+	const refParts = ref.split( '/' );
+	const definition = refParts[ refParts.length - 1 ];
+	if ( ! themejson.definitions[ definition ] ) {
+		throw new Error( `Can't resolve '${ ref }'. Definition not found` );
+	}
+	return themejson.definitions[ definition ];
+};
+
+/**
+ * Get properties from an array.
+ *
+ * @param {Object} items
+ * @return {Object} properties
+ */
+const getPropertiesFromArray = ( items ) => {
+	// if its a $ref resolve it
+	if ( items.$ref ) {
+		return resolveDefinitionRef( items.$ref ).properties;
+	}
+
+	// otherwise just return the properties
+	return items.properties;
+};
+
 /**
  * Convert settings properties to markup.
  *
@@ -96,7 +132,9 @@ const getSettingsPropertiesMarkup = ( struct ) => {
 		const def = 'default' in props[ key ] ? props[ key ].default : '';
 		const ps =
 			props[ key ].type === 'array'
-				? keys( props[ key ].items.properties ).sort().join( ', ' )
+				? keys( getPropertiesFromArray( props[ key ].items ) )
+						.sort()
+						.join( ', ' )
 				: '';
 		markup += `| ${ key } | ${ props[ key ].type } | ${ def } | ${ ps } |\n`;
 	} );

schemas/README.md

@@ -1,6 +1,6 @@
 # Schemas
 
-The collection of schemas used in WordPress, including the `theme.json` and `block.json` schemas.
+The collection of schemas used in WordPress, including the `theme.json`, `block.json` and `font-collection.json` schemas.
 
 JSON schemas are used by code editors to offer tooltips, autocomplete, and validation.
 
@@ -24,6 +24,14 @@ Or in your `theme.json`:
 }
 ```
 
+Or in your `font-collection.json`:
+
+```json
+{
+	"$schema": "https://schemas.wp.org/trunk/font-collection.json"
+}
+```
+
 For a specific version of the schema, replace `trunk` with `wp/X.X`:
 
 ```json
@@ -56,8 +64,16 @@ To allow this you will need to:
 }
 ```
 
+-   update your font collections's `font-collection.json` to include:
+
+```json
+{
+	"$schema": "file://{{FULL_FILE_PATH}}/schemas/json/font-collection.json"
+}
+```
+
 Be sure to replace `{{FULL_FILE_PATH}}` with the full local path to your Gutenberg repo.
 
-With this in place you should now be able to edit either `schemas/json/theme .json` or `schemas/json/block.json` in order to see changes reflected in `theme.json` or `block.json` in your IDE.
+With this in place you should now be able to edit either `schemas/json/theme .json`, `schemas/json/block.json` or `schemas/json/font-collection.json` in order to see changes reflected in `theme.json`, `block.json` or `font-collection.json` in your IDE.
 
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

schemas/json/font-collection.json

@@ -0,0 +1,59 @@
+{
+	"title": "JSON schema for WordPress Font Collections",
+	"$schema": "http://json-schema.org/draft-04/schema#",
+	"type": "object",
+	"properties": {
+		"$schema": {
+			"description": "JSON schema URI for font-collection.json.",
+			"type": "string"
+		},
+		"version": {
+			"description": "Version of font-collection.json schema to use.",
+			"type": "integer",
+			"enum": [ 1 ]
+		},
+		"font_families": {
+			"type": "array",
+			"description": "Array of font families ready to be installed",
+			"items": {
+				"type": "object",
+				"properties": {
+					"font_family_settings": {
+						"description": "Font family settings as in theme.json",
+						"allOf": [
+							{ "$ref": "./theme.json#/definitions/fontFamily" }
+						]
+					},
+					"categories": {
+						"type": "array",
+						"description": "Array of category slugs",
+						"items": {
+							"type": "string"
+						}
+					}
+				},
+				"required": [ "font_family_settings" ],
+				"additionalProperties": false
+			}
+		},
+		"categories": {
+			"type": "array",
+			"description": "Array of category objects",
+			"items": {
+				"type": "object",
+				"properties": {
+					"slug": {
+						"type": "string"
+					},
+					"name": {
+						"type": "string"
+					}
+				},
+				"required": [ "slug", "name" ],
+				"additionalProperties": false
+			}
+		}
+	},
+	"additionalProperties": false,
+	"required": [ "$schema", "version", "font_families" ]
+}