Merge branch 'doc-json-schema' into doc-preview

.github/workflows/checkbox-stable-release.yml

@@ -45,7 +45,7 @@ jobs:
           LP_CREDENTIALS: ${{ secrets.LP_CREDS }}
           CHECKBOX_REPO: ${{ github.repository }}
         run: |
-          tools/release/lp-copy-packages.py
+          tools/release/lp_copy_packages.py checkbox-dev beta checkbox-dev stable
 
   checkbox_core_snap:
     name: Checkbox core snap packages

docs/reference/submission-schema.rst

@@ -1,49 +1,15 @@
-Test Schema
-===============
+.. _submission_schema:
 
-1. Embed source
-----------------
-.. jsonschema::
+Submission Schema
+==================
 
-    {
-        "$schema": "http://json-schema.org/draft-04/schema#",
-        "title": "An example",
-        "id": "http://example.com/schemas/example.json",
-        "description": "This is just a tiny example of a schema rendered by `sphinx-jsonschema <http://github.com/lnoor/sphinx-jsonschema>`_.\n\nYes that's right you can use *reStructuredText* in a description.",
-        "type": "string",
-        "minLength": 10,
-        "maxLength": 100,
-        "pattern": "^[A-Z]+$"
-
-    }
+Checkbox :ref:`Submission files <submission-files>` provide a summary of the test results and in-depth information that help analyzing the tests. 
 
-1. Embed sections from json file
------------------------------------
+This document describes the schema the ``submission.json`` files that's sent to the `Certification website <https://certification.canonical.com>`_ as part of the submission. To get the latest schema definition file in Json, go to the Checkbox `GitHub repository <https://github.com/canonical/checkbox/blob/main/submission-schema/schema.json>`_.
 
-This part include two sections:
+.. important:: 
 
-.. code-block::
-
-    .. jsonschema:: schema.json#/definitions/Result
-        
-    .. jsonschema:: schema.json#/definitions/Outcome
-
-
-.. jsonschema:: ../../submission-schema/schema.json#/definitions/Result
-    :lift_definitions:
-    :auto_reference:
-    :auto_target:
-
-.. jsonschema:: ../../submission-schema/schema.json#/definitions/Outcome
-
-3. Embed whole file
----------------------
-
-This part include one file:
-
-.. code-block::
-    
-    .. jsonschema:: ../../submission-schema/schema.json
+    The schema described in this document is work-in-progress and being reviewed. If you need assistance in validating the schema, please contact the Checkbox team.
 
 .. jsonschema:: ../../submission-schema/schema.json
     :lift_definitions:

docs/tutorial/using-checkbox/test-report.rst

@@ -133,8 +133,10 @@ in the search bar, you can view all test results related to audio testing.
     The xz compressed tarball is a comprehensive archive that includes the 
     aforementioned reports and all associated attachments, such as I/O logs 
     and binary files. You can extract the tarball with ``tar -xf 
-    sumbission.tar.xz -C /path/to/destination``.
+    submission.tar.xz -C /path/to/destination``.
 
     Certification Website only accepts submissions tarballs, from which it 
     extracts the ``submission.json`` file to create a new test report in the 
-    database. 
+    database. 
+
+For a detailed description of the ``submission.json`` file, see the :doc:`../../reference/submission-schema` reference.

providers/base/units/audio/jobs.pxu

@@ -691,7 +691,7 @@ command:
   diff "$PLAINBOX_SESSION_SHARE"/audio_settings_before_suspend "$PLAINBOX_SESSION_SHARE"/audio_settings_after_suspend_30_cycles
 
 id: audio/detect-playback-devices
-_summary: Check that at least one audio playback device exits
+_summary: Check that at least one audio playback device exists
 plugin: shell
 category_id: com.canonical.plainbox::audio
 flags: also-after-suspend

submission-schema/README.md

@@ -82,3 +82,19 @@ Python classes can be created directly from input JSONs.
 ```bash
 npm run generate-python-types-from-input-jsons
 ```
+
+#### Simplifying the schema with `manipulate-schema.py`
+
+`manipulate-schema.py` is a tool that helps you manipulate the schema, by removing and renaming definitions included in it.
+
+To replace a type definition with a replacement value, do:
+
+```bash
+./collapse-type.py path_to_schema.json definition_to_remove replacement_value -o output_file.json
+```
+
+To rename a type definition:
+
+```bash
+./collapse-type.py path_to_schema.json old_definition_name -r -n new_definition_name -o output_file.json
+```

submission-schema/manipulate-schema.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+#
+# A tool to collapse or rename a type definition in a JSON schema.
+
+import json
+import argparse
+from typing import Dict, Any, List, Union
+
+
+def modify_definition(
+    schema: Dict[str, Any], definition_key: str, replacement: str, new_name: str
+) -> Dict[str, Any]:
+    if new_name and definition_key in schema["definitions"]:
+        schema["definitions"][new_name] = schema["definitions"][definition_key]
+        del schema["definitions"][definition_key]
+        replacement = {"$ref": f"#/definitions/{new_name}"}
+
+    if not new_name and definition_key in schema["definitions"]:
+        del schema["definitions"][definition_key]
+
+    def replace_refs(
+        obj: Union[Dict[str, Any], List[Any]]
+    ) -> Union[Dict[str, Any], List[Any]]:
+        if isinstance(obj, dict):
+            if obj.get("$ref") == f"#/definitions/{definition_key}":
+                return replacement
+            else:
+                return {k: replace_refs(v) for k, v in obj.items()}
+        elif isinstance(obj, list):
+            return [replace_refs(elem) for elem in obj]
+        else:
+            return obj
+
+    return replace_refs(schema)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Collapse or rename a type definition in a JSON schema."
+    )
+    parser.add_argument("schema", type=str, help="Path to the JSON schema file.")
+    parser.add_argument(
+        "definition",
+        type=str,
+        help="The key of the definition to remove or rename.",
+    )
+    parser.add_argument(
+        "replacement",
+        type=str,
+        nargs="?",
+        default=None,
+        help='The replacement for the definition (e.g., "string"). If renaming, this is ignored.',
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help="Output file path. If not provided, prints to stdout.",
+    )
+    parser.add_argument(
+        "-n",
+        "--new-name",
+        type=str,
+        default=None,
+        help="New name for the definition if renaming.",
+    )
+
+    args = parser.parse_args()
+    if args.new_name and args.replacement:
+        parser.error(
+            "Replacement (-r/--replacement) is not allowed when renaming a definition."
+        )
+
+    with open(args.schema, "r") as file:
+        schema = json.load(file)
+
+    modified_schema = modify_definition(
+        schema, args.definition, args.replacement, args.new_name
+    )
+
+    if args.output:
+        with open(args.output, "w") as file:
+            json.dump(modified_schema, file, indent=4)
+    else:
+        print(json.dumps(modified_schema, indent=4))
+
+
+if __name__ == "__main__":
+    main()