Docs.

readme.md

@@ -253,7 +253,7 @@ Schemas are available via an OPTIONS request to the REST API endpoints, but the
 
 ### Are these schemas automatically generated from WordPress core?
 
-No. I started down that path (using [wp-parser-lib](https://github.com/johnbillion/wp-parser-lib)) but realised it's quicker to generate them manually and then copy most of the documentation from core, especially as I'm adding extra documentation and schemas for properties when I can.
+No, but they are automatically tested against output from WordPress core to ensure their correctness. Extra documentation and schemas for properties have been added where possible, so generating them directly from WordPress core isn't desirable.
 
 ### How do I know the schemas are accurate?
 

tests/bin/build-wp-types.sh

@@ -4,18 +4,24 @@
 # -o pipefail Produce a failure return code if any command errors
 set -eo pipefail
 
+# Set additionalProperties to false for all partial schemas
 for file in schemas/rest-api/partials/**/*.json
 do
 	./node_modules/node-jq/bin/jq --tab '. + { "additionalProperties": false }' "$file" > tmp && mv tmp "$file"
 done
 
+# Generate TypeScript types
 ./node_modules/.bin/json2ts -i schema.json -o packages/wp-types/index.ts --style.trailingComma=all --style.useTabs
 
+# Revert additionalProperties
 for file in schemas/rest-api/partials/**/*.json
 do
 	./node_modules/node-jq/bin/jq --tab 'del(.additionalProperties)' "$file" > tmp && mv tmp "$file"
 done
 
+# Append append.ts to the generated types
 cat packages/wp-types/append.ts >> packages/wp-types/index.ts
+
+# Don't export the partial interfaces
 sed -i.bak 's/export interface WP_REST_API_Partial_/interface WP_REST_API_Partial_/g' packages/wp-types/index.ts
 rm packages/wp-types/index.ts.bak

tests/bin/test.sh

@@ -4,6 +4,7 @@
 # -o pipefail Produce a failure return code if any command errors
 set -eo pipefail
 
+# Validate a schema file
 function validate_schema() {
 	local file="$1"
 	local base=${file//schemas\//}
@@ -18,6 +19,7 @@ function validate_schema() {
 	./node_modules/.bin/ajv validate --spec=draft2019 --strict --strict-schema=false -c ajv-formats -m tests/external-schemas/hyper-schema.json -r schema.json -r $rflag -s "$file" -d "tests/data/$filename/*.json"
 }
 
+# Modify a schema file using a jq transformation and an optional jq condition
 function modify_schema() {
 	local file="$1"
 	local changes="$2"
@@ -35,6 +37,7 @@ function modify_schema() {
 	mv tmp "$file"
 }
 
+# Cleanup function to remove unevaluatedProperties and additionalProperties
 function cleanup() {
 	for file in schemas/rest-api/*.json
 	do
@@ -47,15 +50,20 @@ function cleanup() {
 	done
 }
 
+# Files to ignore when disallowing additional properties
 IGNORE_FILES=("schemas/rest-api/error.json")
 
+# Always cleanup regardless of how the script exits
 trap cleanup EXIT
 
+# Validate all PHP object schemas
 for file in schemas/*.json
 do
 	validate_schema "$file"
 done
 
+# Disallow additional root properties in all REST API schemas (via unevaluatedProperties)
+# Disallow additional properties in the _embedded field in all REST API schemas
 for file in schemas/rest-api/*.json
 do
 	if [[ "${IGNORE_FILES[*]}" =~ "${file}" ]]
@@ -66,11 +74,12 @@ do
 	modify_schema "$file" '.properties._embedded += { "additionalProperties": false }' '.properties._embedded != null'
 done
 
+# Validation for REST API collections:
 for file in schemas/rest-api/collections/*.json
 do
 	validate_schema "$file"
 done
 
-# Validation for REST API entities that don't have a collection:
+# Validation for REST API entities that don't have a directly corresponding collection:
 validate_schema schemas/rest-api/global-style-variation.json
 validate_schema schemas/rest-api/global-style-config.json