schema: version schema-cloud-config-v1.json

Provide top-level version.schema.cloud-config.json which will be
consumed by https://github.com/SchemaStore/schemastore/ and provided
for json validator tooling.

Rename cloud-init-schema.json to schema-cloud-config-v1.json to allow
space for providing static scoped schema definitions for vendor-data,
meta-data and network-config in the future.

cloudinit/config/schema.py

@@ -21,6 +21,9 @@
 error = partial(error, sys_exit=True)
 LOG = logging.getLogger(__name__)
 
+# Bump this file when introducing incompatible schema changes.
+# Also add new version definition to versions.schema.json.
+USERDATA_SCHEMA_FILE = "schema-cloud-config-v1.json"
 _YAML_MAP = {True: "true", False: "false", None: "null"}
 CLOUD_CONFIG_HEADER = b"#cloud-config"
 SCHEMA_DOC_TMPL = """
@@ -661,8 +664,17 @@ def load_doc(requested_modules: list) -> str:
 
 def get_schema() -> dict:
     """Return jsonschema coalesced from all cc_* cloud-config modules."""
+    # Note versions.schema.json is publicly consumed by schemastore.org.
+    # If we change the location of versions.schema.json in github, we need
+    # to provide an updated PR to
+    # https://github.com/SchemaStore/schemastore.
+
+    # When bumping schema version due to incompatible changes:
+    # 1. Add a new schema-cloud-config-v#.json
+    # 2. change the USERDATA_SCHEMA_FILE to cloud-init-schema-v#.json
+    # 3. Add the new version definition to versions.schema.cloud-config.json
     schema_file = os.path.join(
-        os.path.dirname(os.path.abspath(__file__)), "cloud-init-schema.json"
+        os.path.dirname(os.path.abspath(__file__)), USERDATA_SCHEMA_FILE
     )
     full_schema = None
     try:

cloudinit/config/versions.schema.cloud-config.json

@@ -0,0 +1,18 @@
+{
+  "$id": "https://github.com/canonical/cloud-init/tree/main/cloudinit/config/schema/versions.schema.cloud-config.json",
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "oneOf": [
+    {
+      "allOf": [
+        {
+          "properties": {
+            "version": {
+              "enum": ["22.2", "v1"]
+            }
+          },
+          "$ref": "https://raw.githubusercontent.com/canonical/cloud-init/main/cloudinit/config/schema-cloud-config-v1.json"
+        }
+      ]
+    }
+  ]
+}

tests/unittests/config/test_schema.py

@@ -179,15 +179,11 @@ class TestLoadDoc:
 
     docs = get_module_variable("__doc__")
 
-    # TODO( Drop legacy test when all sub-schemas in cloud-init-schema.json )
     @pytest.mark.parametrize(
         "module_name",
-        (
-            "cc_apt_pipelining",  # new style composite schema file
-            "cc_install_hotplug",  # legacy sub-schema defined in module
-        ),
+        ("cc_apt_pipelining",),  # new style composite schema file
     )
-    def test_report_docs_for_legacy_and_consolidated_schema(self, module_name):
+    def test_report_docs_consolidated_schema(self, module_name):
         doc = load_doc([module_name])
         assert doc, "Unexpected empty docs for {}".format(module_name)
         assert self.docs[module_name] == doc
@@ -329,7 +325,7 @@ def test_validateconfig_schema_of_example(self, schema_id, example):
         """
         schema = get_schema()
         config_load = load(example)
-        # cloud-init-schema is permissive of additionalProperties at the
+        # cloud-init-schema-v1 is permissive of additionalProperties at the
         # top-level.
         # To validate specific schemas against known documented examples
         # we need to only define the specific module schema and supply