fix: publish each profile document in the envelope

scripts/generate_site.py

@@ -1117,6 +1117,12 @@ def generate_data_page(exports: list[dict]) -> str:
         "Every JSON document carries `schema_version`. Breaking changes use a new "
         "URL prefix (`/api/v2/`); fields may only be added compatibly within v1.",
         "",
+        "One emulator profile without the whole list: "
+        "`api/v1/emulators/<id>.json`, the envelope of `emulators.json` holding "
+        "that one item, its `profile` valid against "
+        "[`emulator.schema.json`](api/v1/schemas/emulator.schema.json). Each "
+        "emulator page links its own.",
+        "",
         "## Bulk downloads",
         "",
         "| Export | Format | Size | SHA256 |",
@@ -4495,10 +4501,21 @@ def _generate(args: argparse.Namespace) -> None:
     for name, profile in public_profiles.items():
         # The profile itself, one small document per core: reusing one
         # meant downloading emulators.json (5.9 MB) and filtering it.
+        # The envelope and item of emulators.json, one item long: the
+        # profile validates against the published schema, which an "id"
+        # beside its fields broke on all 530, and schema_version is there.
         write_if_changed(
             str(docs / "api" / "v1" / "emulators" / f"{name}.json"),
-            json.dumps({"id": name, **profile}, indent=2, sort_keys=True,
-                       ensure_ascii=False, default=str) + "\n",
+            json.dumps(
+                {
+                    "schema_version": 1,
+                    "generated_at": str(db.get("generated_at") or _timestamp()),
+                    "kind": "emulators",
+                    "count": 1,
+                    "items": [{"id": name, "profile": profile}],
+                },
+                indent=2, sort_keys=True, ensure_ascii=False, default=str,
+            ) + "\n",
         )
         page = generate_emulator_page(
             name, profile, db, consumers, suppl_names, data_registry

tests/test_site_exports.py

@@ -627,5 +627,29 @@ class APlatformPageNamesTheFileItTranscribes(unittest.TestCase):
         self.assertIn("revision read is not recorded", page("https://github.com/RetroDECK/components"))
 
 
+class APerCoreDocumentValidates(unittest.TestCase):
+    """api/v1/emulators/<id>.json had no schema_version, and its "id" beside
+    the profile's fields failed the schema published next to it."""
+
+    def test_shape(self):
+        try:
+            import jsonschema  # noqa: PLC0415
+        except ImportError:
+            self.skipTest("jsonschema is not installed")
+        import yaml  # noqa: PLC0415
+
+        root = Path(__file__).resolve().parents[1]
+        source = (root / "scripts" / "generate_site.py").read_text(encoding="utf-8")
+        self.assertNotIn('json.dumps({"id": name, **profile}', source)
+        envelope = json.loads((root / "schemas" / "site-api-envelope.schema.json").read_text())
+        schema = json.loads((root / "schemas" / "emulator.schema.json").read_text())
+        profile = yaml.safe_load((root / "emulators" / "handy.yml").read_text())
+        document = {"schema_version": 1, "generated_at": "2026-10-19T00:00:00Z",
+                    "kind": "emulators", "count": 1,
+                    "items": [{"id": "handy", "profile": profile}]}
+        jsonschema.validate(document, envelope)
+        jsonschema.validate(document["items"][0]["profile"], schema)
+
+
 if __name__ == "__main__":
     unittest.main()