Apply well-formed JSON checks also on peas_local.json if present. (#230)

Added user script `peas_validate_with_json_schema.py` to also
validate PEAS file against the PEAS JSON Schema.

Fixes #228

Author: Gemba

docs/INSTALLATION.md

@@ -5,13 +5,28 @@ You can find detailled installation instructions in the respective section in th
 - [RetroPie on Linux distros with Debian package system](https://github.com/Gemba/skyscraper/blob/master/README.md#installation-of-skyscraper-on-retropie-and-programmable-completion) (Ubuntu, RaspiOS, aso.)
 - Other unixoid OSes first match the dependencies:
 
-    - Linux distros with Debian package system (Ubuntu, RaspiOS, aso.), [without RetroPie](https://github.com/Gemba/skyscraper/blob/master/README.md#linux)
-    - For other Linux distributions assure the [package dependencies](https://github.com/Gemba/skyscraper/blob/master/README.md#linux) are met for your distro
-    - NixOS aficionados are happy with these packages: [NixOS](https://github.com/Gemba/skyscraper/blob/master/README.md#nixos)
-    - macOS users can install the dependencies [via brew](https://github.com/Gemba/skyscraper/blob/master/README.md#macos)
+    - Linux distros with Debian package system (Ubuntu, RaspiOS, aso.), [without
+      RetroPie](https://github.com/Gemba/skyscraper/blob/master/README.md#linux)
+    - For other Linux distributions assure the [package
+      dependencies](https://github.com/Gemba/skyscraper/blob/master/README.md#linux)
+      are met for your distro
+    - NixOS aficionados are happy with these packages:
+      [NixOS](https://github.com/Gemba/skyscraper/blob/master/README.md#nixos)
+    - macOS users can install the dependencies [via
+      brew](https://github.com/Gemba/skyscraper/blob/master/README.md#macos)
 
 After having the dependencies installed proceed with the [install script](https://github.com/Gemba/skyscraper/blob/master/README.md#download-compile-and-install) or use the few [manual commands](https://github.com/Gemba/skyscraper/blob/master/README.md#installing-the-development-version).  
 Last but not least you can also follow these paths:
 
 - [Docker use](https://github.com/Gemba/skyscraper/blob/master/README.md#docker)
-- [Native Windows installation](https://github.com/Gemba/skyscraper/tree/master/win32#readme) (or use WSL2 with a Linux Distro and follow the Linux instructions above)
+- [Native Windows
+  installation](https://github.com/Gemba/skyscraper/tree/master/win32#readme)
+  (or use WSL2 with a Linux Distro and follow the Linux instructions above)
+
+### Supplementary Scripts
+
+These scripts are not essential to work with Skyscraper, but they may come in
+handy if you adapt the platform configuration files, documented in the [Platform
+page](PLATFORMS.md) or want to use the GameBase scraper. You can find an
+overview of the scripts in the respective
+[README](https://github.com/Gemba/skyscraper/blob/master/supplementary/scraperdata/README-Skyscraper-Scripts.md).

docs/PLATFORMS.md

@@ -61,10 +61,11 @@ maintain local changes to the `platforms_idmap.csv` in a separate file with a
 !!! tip "Avoid Duplication"
 
     If you need a specific folder name for a platform (on your setup or due to an
-    EmulationStation theme) use a symbolic link (for example `megadrive` (=folder)
-    and `genesis` (=symlink) on RetroPie setups or another example: `plus4`
-    (=folder) and `c16` (=symlink)) instead of duplicating the platform in the JSON
-    file.
+    EmulationStation theme) use a symbolic link. For example `megadrive` (=folder)
+    and `genesis` (=symlink) on RetroPie setups or `plus4` (=folder) and `c16`
+    (=symlink). Example for ES-DE `n3ds` (=folder) and `3ds` (=symlink) Use this
+    approach instead of duplicating the platform in the JSON file and it saves you
+    from maintaining the `*_local*` files. Command `ln -s <folder> <symlink>`
 
 ### File Two: Exact platform mapping
 
@@ -84,7 +85,11 @@ c64,66,27,40
 
 !!! tip "The Games DB"
 
-    The game data at TGDB is in rare case in different platforms to be found. Prominent example is Sega's Genesis respecitve Mega Drive. For these edgecases you may find the platform ids in the `platforms_idmap.csv` separated with an `|`. This means all platform ids will be tried to find a match in left-to-right order of the definition.
+    The game data at TGDB is in rare case in different platforms to be found.
+    Prominent example is Sega's Genesis respecitve Mega Drive. For these edgecases
+    you may find the platform ids in the `platforms_idmap.csv` separated with an
+    `|`. This means all platform ids will be tried to find a match in left-to-right
+    order of the definition.
 
 
 You can display the number with their platform name on each of the three
@@ -170,8 +175,13 @@ Example: Copy this excerpt from `peas.json`...
 ```
 
 If you have multiple platforms defined in your local file make sure the platform
-blocks are separated by a comma `,`.
-
+blocks are separated by a comma `,`.  
+To validate your `peas_local.json` file you can use the script
+`peas_validate_with_json_schema.py` (you can find it in the
+`supplementary/scraperdata` folder or sibling to the `Skyscraper` executable on
+a RetroPie installation (usually `/opt/retropie/supplementary/skyscraper/`)). See
+the comments in the script for usage, but after installing the dependency it
+boils down to provide the path to your JSON file as parameter to the script.
 
 !!! tip "Case-sensitivity in EmulationStation Configuration"
 
@@ -183,18 +193,18 @@ blocks are separated by a comma `,`.
 Outline:
 
 1. Create a file `peas_local.json` sibling to `peas.json`. Enter in this file an
-   empty `{}` JSON object.
-2. Create a new platform block in `peas_local.json` inside the outer (empty)
-   block created before, or copy an existing block and adapt to your needs. For
-   RetroPie your chosen `<platform_name>` must match the folder in
-   `~/RetroPie/roms/<platform_name>`.
-3. Use `<platform_name>` also in `platforms_idmap_local.csv`. If you need to
+   empty `{}` JSON object. Then create a new platform block in `peas_local.json`
+   inside the outer (empty) block created before, or copy an existing block and
+   adapt to your needs. For RetroPie your chosen `<platform_name>` must match
+   the folder in `~/RetroPie/roms/<platform_name>`.
+2. Use `<platform_name>` also in `platforms_idmap_local.csv`. If you need to
    create an `platforms_idmap_local.csv` put in the column names
    `folder,screenscraper_id,mobygames_id,tgdb_id` (i.e. the first line of
    `platforms_idmap.csv`) . See also below for details of this CSV-file.
-4. If you use RetroPie do add the platform/system also to your `es_systems.cfg`
+3. If you use RetroPie do add the platform/system also to your `es_systems.cfg`
    as documented in the 
    [RetroPie documentation](https://retropie.org.uk/docs/Add-a-New-System-in-EmulationStation/).
+4. That's it. Happy scraping!
 
 There is also a verbatim example, you may skip the next section initially and
 jump directly into the [hands-on example](PLATFORMS.md#sample-usecase-adding-platform-satellaview).
@@ -235,7 +245,11 @@ folder on your filesystem where you keep your games.
 
 !!! example "Use of Aliases"
 
-    The platforms ScummVM and Steam do not have an exact match on Mobygames, however you may scrape successfully for ScummVM and Steam games if you use 'PC', 'DOS', 'Windows', 'Linux' or similar as `"aliases": ...` in the `"scummvm": ...` or `"steam": ...` section of `peas.json`. Usually you find the platforms a game runs on if you lookup the game manually on the scraping website.
+    The platforms ScummVM and Steam do not have an exact match on Mobygames, however
+    you may scrape successfully for ScummVM and Steam games if you use 'PC', 'DOS',
+    'Windows', 'Linux' or similar as `"aliases": ...` in the `"scummvm": ...` or
+    `"steam": ...` section of `peas.json`. Usually you find the platforms a game
+    runs on if you lookup the game manually on the scraping website.
 
 ### Sample Usecase: Adding Platform _Satellaview_
 
@@ -323,12 +337,12 @@ for additional information on this.
 
 - Line 3 defines the platform name, respective the folder name for your ROMs.
   Thus, Skyscraper expects to find ROMs in `/home/pi/RetroPie/roms/satellaview`.
-- Line 6 contains the extensions which are recognized by EmulationStation. These
-  extensions should be also be present in the `"formats":` block of `peas.json`.
-  However, Skyscraper uses case insensitive file extension mapping. The
-  extensions `.7z` and `.zip` are added automagically by Skyscraper, thus the
-  `"formats":` list is usually shorter than the EmulationStation `<extension/>`
-  list.
+- Line 6 contains the extensions which are recognized by EmulationStation
+  (explicitly in lowercase and UPPERCASE). These extensions should be also be
+  present in the `"formats":` block of `peas.json`. However, Skyscraper uses
+  case insensitive file extension mapping (lowercase only). The extensions `.7z`
+  and `.zip` are added automagically by Skyscraper, thus the `"formats":` list
+  is usually shorter than the EmulationStation `<extension/>` list.
 - Line 9: If your theme doesn't support Satellaview, you can also use `snes` as
   <theme> value.
 
@@ -457,7 +471,7 @@ Forum/Skyscraper Thread](https://retropie.org.uk/forum/topic/34588). Thank you!
 
 ### Migrating `platforms.json` and `screenscraper.json`
 
-This section is only applicable if you update from Skyscraper 3.7.7-2.
+This section is only applicable if you update from Skyscraper 3.7.7-2 or earlier.
 
 !!! tip
 

src/platform.cpp

@@ -88,13 +88,20 @@ bool Platform::loadConfig() {
     QJsonDocument json(QJsonDocument::fromJson(jsonData));
 
     if (json.isNull() || json.isEmpty()) {
-        printf("\033[1;31mFile '%s' empty or no JSON format. Now "
+        printf("\033[1;31mFile '%s' empty or invalid JSON format. Now "
                "quitting...\033[0m\n",
                fnPeas.toUtf8().constData());
         return false;
     }
 
-    QJsonObject jObjLocal = loadLocalConfig();
+    bool ok = true;
+    QJsonObject jObjLocal = loadLocalConfig(ok);
+    if (!ok) {
+        printf("\033[1;31mFile '%s' has invalid JSON format. Now "
+               "quitting...\033[0m\n",
+               fnPeasLocal.toUtf8().constData());
+        return false;
+    }
     QJsonObject jObj = json.object();
 
     for (auto plit = jObjLocal.constBegin(); plit != jObjLocal.constEnd();
@@ -116,17 +123,22 @@ bool Platform::loadConfig() {
     return true;
 }
 
-QJsonObject Platform::loadLocalConfig() {
+QJsonObject Platform::loadLocalConfig(bool &ok) {
     QJsonObject peasLocal;
     QFile configFile(fnPeasLocal);
 
     if (configFile.open(QIODevice::ReadOnly)) {
         QByteArray jsonData = configFile.readAll();
-        QJsonDocument json(QJsonDocument::fromJson(jsonData));
+        QJsonParseError err;
+        QJsonDocument json(QJsonDocument::fromJson(jsonData, &err));
 
         if (!json.isNull() && !json.isEmpty()) {
             qDebug() << "successfully loaded" << fnPeasLocal;
             peasLocal = json.object();
+        } else if (err.error != QJsonParseError::NoError) {
+            qWarning()
+                << QString("JSON is malformed: %1").arg(err.errorString());
+            ok = false;
         }
     }
     return peasLocal;
@@ -234,7 +246,7 @@ bool Platform::parsePlatformsIdCsv(const QString &platformsIdCsvFn) {
                     } else {
                         ids[col].append(-1);
                         printf("\033[1;33mFile '%s', line '%s,%s' has "
-                               "unparsable or too negative int value '%s' (use "
+                               "unparsable or too negative number '%s' (use "
                                "-1 for unknown platform id). Assumming -1 for "
                                "now, please fix to mute this warning.\033[0m\n",
                                fn, pkey.toUtf8().constData(),

src/platform.h

@@ -52,7 +52,7 @@ class Platform : public QObject {
 private:
     bool loadPlatformsIdMap();
     bool parsePlatformsIdCsv(const QString &fnplatformsIdCsvFn);
-    QJsonObject loadLocalConfig();
+    QJsonObject loadLocalConfig(bool &ok);
 
     QStringList platforms;
     QVariantMap peas;

supplementary/scraperdata/README-Skyscraper-Scripts.md

@@ -1,15 +1,18 @@
-# Skyscraper supplementary scripts
+# Skyscraper Supplementary Scripts
 
 See also script header for information on usage. You can find additional
-information in Skyscraper's platform documentation (`PLATFORM.md`) for regarding
-this scripts.
+information in Skyscraper's platform documentation (`PLATFORM.md`) regarding
+these scripts.
 
 `deepdiff_peas_jsonfiles.py`: Compare and diff output two `peas.json` files.
 
 `mdb2sqlite.sh`: Convert MS Access MDB format to SQLite (only useful when you
-use the GameBase scraper).
+use the GameBase `-s gamebase` scraper).
 
-`peas_and_idmap_verify.py`: Validate settings in `peas.json` and
+`peas_and_idmap_verify.py`: Validate (crosscheck) settings in `peas.json` and
 `platforms_idmap.csv` and dump a human readable output.
 
+`peas_validate_with_json_schema.py`: Validate a given `peas*.json` file against
+the PEAS JSON Schema `peas-schema.json`.
+
 `README-Skyscraper-Scripts.md`: This file.

supplementary/scraperdata/peas-schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Skyscraper's Platform, Extensions, Aliases and Scraper definition format (PEAS)",
+  "type": "object",
+  "additionalProperties": {
+    "type": "object",
+    "properties": {
+      "aliases": {
+        "type": "array",
+        "description": "Alias(es) of a platform for scraping modules that do not use a platform id. They use the defined alias(es) for a platform match.",
+        "uniqueItems": true,
+        "items": { "type": "string" }
+      },
+      "formats": {
+        "type": "array",
+        "description": "Recognized gamefile extensions, lowercase, unique. Define extension beginning with '*.'.",
+        "uniqueItems": true,
+        "items": {
+          "type": "string",
+          "pattern": "^\\*.[a-z0-9\\.]+$"
+        }
+      }
+    },
+    "required": ["aliases", "formats"]
+  }
+}

supplementary/scraperdata/peas_validate_with_json_schema.py

@@ -0,0 +1,41 @@
+# /usr/bin/env python3
+
+# Validates a JSON file against Skyscraper's PEAS JSON Schema.
+
+# Usage:
+# python3 peas_validate_with_json_schema.py <path/to/peas_local.json>
+
+# Preparation:
+# sudo apt install python3-jsonschema
+
+# (c) 2026 Gemba @ GitHub
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import json
+import sys
+from pathlib import Path
+from jsonschema import validate
+
+if len(sys.argv) != 2:
+    print("[!] Provide a peas.json or peas_local.json file as parameter")
+    sys.exit(1)
+
+peas_file = Path(sys.argv[1])
+
+if not peas_file.exists():
+    print(f"[!] File does not exist: '{peas_file}'")
+    sys.exit(1)
+
+with open(peas_file, "r", encoding="utf-8") as pf:
+    peas_json = json.load(pf)
+
+with open(Path(__file__).parent / "peas-schema.json", "r", encoding="utf-8") as sf:
+    schema = json.load(sf)
+
+try:
+    validate(instance=peas_json, schema=schema)
+except Exception as e:
+    print(f"[-] Validation failed for '{peas_file}':")
+    raise e
+
+print(f"[+] '{peas_file}' validated OK")