feat: round 4 reference and data

schemas/install-manifest.schema.json

@@ -23,21 +23,24 @@
   ],
   "properties": {
     "manifest_version": {
-      "const": 2
+      "const": 2,
+      "description": "Format version of the manifest. install.py refuses a version it does not know."
     },
     "source": {
       "enum": [
         "full",
         "platform",
         "truth"
-      ]
+      ],
+      "description": "Which files the pack was built from: full (the platform's list plus the files its cores load), platform (the list alone) or truth (the cores' files alone)."
     },
     "regions": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "uniqueItems": true
+      "uniqueItems": true,
+      "description": "Region priority the manifest was narrowed to, best first. Empty when it was not narrowed."
     },
     "target": {
       "type": "string",
@@ -79,13 +82,15 @@
       "type": "array",
       "items": {
         "type": "object"
-      }
+      },
+      "description": "Rules install.py follows to find this setup and its BIOS folder on a machine, one per method and operating system."
     },
     "standalone_copies": {
       "type": "array",
       "items": {
         "type": "object"
-      }
+      },
+      "description": "Files install.py also copies into the folders of standalone emulators it finds, or a note it prints when their folder exists."
     },
     "total_files": {
       "type": "integer",
@@ -497,7 +502,7 @@
         },
         "repo_path": {
           "type": "string",
-          "description": "Path in the repository. Fetched from https://raw.githubusercontent.com/Abdess/retrobios/<ref>/<repo_path>, ref being main unless RETROBIOS_REF names a tag."
+          "description": "Path in the repository. Fetched from `https://raw.githubusercontent.com/Abdess/retrobios/<ref>/<repo_path>`, ref being main unless RETROBIOS_REF names a tag."
         },
         "cores": {
           "oneOf": [
@@ -521,7 +526,7 @@
         "release_asset": {
           "type": "string",
           "pattern": "^[^/\\\\]+$",
-          "description": "Asset of the large-files release, fetched from https://github.com/Abdess/retrobios/releases/download/large-files/<asset> instead of repo_path."
+          "description": "Asset of the large-files release, fetched from `https://github.com/Abdess/retrobios/releases/download/large-files/<asset>` instead of repo_path."
         },
         "systems": {
           "description": "Every platform system that declares the file, for the installer's --system.",

schemas/release.schema.json

@@ -5,8 +5,12 @@
   "description": "What the packs of the latest release hold, read from the archives when the release is cut.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["tag", "packs"],
+  "required": ["schema_version", "tag", "packs"],
   "properties": {
+    "schema_version": {
+      "const": 1,
+      "description": "Format version of this record, raised when a field changes meaning or goes away."
+    },
     "tag": { "type": "string", "pattern": "^v[0-9]{4}\\.[0-9]{2}\\.[0-9]{2}$" },
     "packs": {
       "type": "object",

schemas/site-api-envelope.schema.json

@@ -403,7 +403,17 @@
                 },
                 "sha1": {
                   "type": "string",
-                  "pattern": "^[0-9a-f]{40}$"
+                  "pattern": "^[0-9a-f]{40}$",
+                  "description": "SHA1 of the collection file the value designates. A platform or emulator record that designates no collection file has none."
+                },
+                "declared": {
+                  "enum": [
+                    "sha1",
+                    "md5",
+                    "crc32",
+                    "sha256"
+                  ],
+                  "description": "On a copy of a platform or emulator record filed under another hash of its file: the algorithm of the value its owner wrote."
                 },
                 "owner": {
                   "type": "string"