diff --git a/www/docs/static/schema.json b/www/docs/static/schema.json
index 617bb1ade..763cb2edf 100644
--- a/www/docs/static/schema.json
+++ b/www/docs/static/schema.json
@@ -216,7 +216,8 @@
 							{
 								"type": "boolean"
 							}
-						]
+						],
+						"description": "you can now remove this"
 					},
 					"files": {
 						"items": {
@@ -1122,7 +1123,8 @@
 						"type": "string"
 					},
 					"tap": {
-						"$ref": "#/$defs/RepoRef"
+						"$ref": "#/$defs/RepoRef",
+						"description": "use repository instead"
 					},
 					"repository": {
 						"$ref": "#/$defs/RepoRef"
@@ -1140,7 +1142,8 @@
 						"type": "string"
 					},
 					"plist": {
-						"type": "string"
+						"type": "string",
+						"description": "use service instead"
 					},
 					"install": {
 						"type": "string"
@@ -1400,7 +1403,8 @@
 						"type": "string"
 					},
 					"index": {
-						"$ref": "#/$defs/RepoRef"
+						"$ref": "#/$defs/RepoRef",
+						"description": "use repository instead"
 					},
 					"repository": {
 						"$ref": "#/$defs/RepoRef"
@@ -2083,7 +2087,8 @@
 						"type": "array"
 					},
 					"scoop": {
-						"$ref": "#/$defs/Scoop"
+						"$ref": "#/$defs/Scoop",
+						"description": "use scoops insteads"
 					},
 					"scoops": {
 						"items": {
@@ -2222,7 +2227,7 @@
 					},
 					"build": {
 						"$ref": "#/$defs/Build",
-						"description": "deprecated: use builds instead"
+						"description": "use builds instead"
 					},
 					"force_token": {
 						"type": "string",
@@ -2553,7 +2558,8 @@
 						"type": "array"
 					},
 					"bucket": {
-						"$ref": "#/$defs/RepoRef"
+						"$ref": "#/$defs/RepoRef",
+						"description": "use repository instead"
 					},
 					"repository": {
 						"$ref": "#/$defs/RepoRef"
@@ -3035,7 +3041,8 @@
 							{
 								"type": "boolean"
 							}
-						]
+						],
+						"description": "you can now remove this"
 					}
 				},
 				"additionalProperties": false,