Complete schema for Antsibull changelogs

src/ansiblelint/config.py

@@ -73,7 +73,7 @@
     {"requirements": "**/requirements.{yaml,yml}"},  # v2 and v1
     {"playbook": "**/molecule/*/*.{yaml,yml}"},  # molecule playbooks
     {"yaml": "**/{.ansible-lint,.yamllint}"},
-    {"changelog": "**/changelog.yml"},
+    {"changelog": "**/changelogs/changelog.yaml"},
     {"yaml": "**/*.{yaml,yml}"},
     {"yaml": "**/.*.{yaml,yml}"},
 ]

src/ansiblelint/schemas/changelog.json

@@ -1,11 +1,39 @@
 {
   "$defs": {
+    "plugin-descriptions": {
+      "items": {
+        "properties": {
+          "description": {
+            "markdownDescription": "Value of `short_description` from plugin `DOCUMENTATION`.",
+            "title": "Description",
+            "type": "string"
+          },
+          "name": {
+            "markdownDescription": "It must not be the FQCN, but the name inside the collection.",
+            "pattern": "[a-zA-Z0-9_]+",
+            "title": "Name",
+            "type": "string"
+          },
+          "namespace": {
+            "type": "null"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
     "release": {
       "additionalProperties": false,
       "properties": {
         "changes": {
           "additionalProperties": false,
           "properties": {
+            "breaking_changes": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
             "bugfixes": {
               "items": {
                 "type": "string"
@@ -18,45 +46,182 @@
               },
               "type": "array"
             },
+            "known_issues": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "major_changes": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
             "minor_changes": {
               "items": {
                 "type": "string"
               },
               "type": "array"
             },
             "release_summary": {
+              "markdownDescription": "This must be valid [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText).",
+              "title": "Release Summary",
               "type": "string"
+            },
+            "removed_features": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "security_fixes": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "trivial": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
             }
           },
           "type": "object"
         },
         "codename": {
           "type": "string"
         },
+        "fragments": {
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "List of strings representing filenames of changelog framents.",
+          "type": "array"
+        },
         "modules": {
           "items": {
             "properties": {
               "description": {
-                "markdownDescription": "Value of `short_description from plugin `DOCUMENTATION`.",
+                "markdownDescription": "Value of `short_description` from plugin `DOCUMENTATION`.",
                 "title": "Description",
                 "type": "string"
               },
               "name": {
-                "markdownDescription": " It must not be the FQCN, but the name inside the collection.",
+                "markdownDescription": "It must not be the FQCN, but the name inside the collection.",
                 "pattern": "[a-zA-Z0-9_]+",
                 "title": "Short module name",
                 "type": "string"
               },
               "namespace": {
-                "markdownDescription": "Must be `null` for plugin and objects. For modules it must be either empty string. The namespace is used to group new modules by their namespace inside the collection.",
+                "markdownDescription": "Must be `''` for modules directly in `plugins/modules/`, or the dot-separated list of directories the module is in inside the `plugins/modules/` directory. The namespace is used to group new modules by their namespace inside the collection.",
                 "title": "Namespace",
-                "type": ["string", "null"]
+                "type": "string"
               }
             },
             "type": "object"
           },
           "type": "array"
         },
+        "objects": {
+          "additionalProperties": false,
+          "properties": {
+            "playbook": {
+              "items": {
+                "properties": {
+                  "description": {
+                    "markdownDescription": "A short description of what the playbook does.",
+                    "title": "Description",
+                    "type": "string"
+                  },
+                  "name": {
+                    "markdownDescription": "It must not be the FQCN, but the name inside the collection.",
+                    "pattern": "[a-zA-Z0-9_]+",
+                    "title": "Short playbook name",
+                    "type": "string"
+                  },
+                  "namespace": {
+                    "type": "null"
+                  }
+                },
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "role": {
+              "items": {
+                "properties": {
+                  "description": {
+                    "markdownDescription": "Value of `short_description` from role's argument spec.",
+                    "title": "Description",
+                    "type": "string"
+                  },
+                  "name": {
+                    "markdownDescription": "It must not be the FQCN, but the name inside the collection.",
+                    "pattern": "[a-zA-Z0-9_]+",
+                    "title": "Short role name",
+                    "type": "string"
+                  },
+                  "namespace": {
+                    "type": "null"
+                  }
+                },
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "type": "object"
+        },
+        "plugins": {
+          "additionalProperties": false,
+          "properties": {
+            "become": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "cache": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "callback": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "cliconf": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "connections": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "filter": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "httpapi": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "inventory": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "lookup": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "netconf": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "shell": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "strategy": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "test": {
+              "$ref": "#/$defs/plugin-descriptions"
+            },
+            "vars": {
+              "$ref": "#/$defs/plugin-descriptions"
+            }
+          },
+          "type": "object"
+        },
         "release_date": {
           "format": "date",
           "markdownDescription": "Use ISO-8601 date format, like 2020-12-31",
@@ -70,15 +235,14 @@
     "semver": {
       "pattern": "\\d+.\\d+.\\d+.*",
       "title": "Version string following SemVer specification.",
-      "type": "string"
+      "type": ["string", "null"]
     }
   },
   "$id": "https://raw.githubusercontent.com/ansible-lint/main/src/ansiblelint/schemas/changelog.json",
   "$schema": "http://json-schema.org/draft-07/schema",
   "additionalProperties": false,
-  "description": "Antsibull Changelog Schema",
-  "examples": ["changelog.yml"],
-  "markdownDescription": "See [Changelog YAML Format](https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md)",
+  "examples": ["changelogs/changelog.yaml"],
+  "markdownDescription": "Antsibull Changelog Schema is based on [changelog.yaml-format.md](https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md).",
   "properties": {
     "ancestor": {
       "$ref": "#/$defs/semver"

test/schemas/.mocharc.json

@@ -2,5 +2,6 @@
   "colors": true,
   "extension": ["ts"],
   "require": "ts-node/register",
+  "slow": "500",
   "spec": "src/**/*.spec.ts"
 }

test/schemas/negative_test/changelogs/invalid-date/changelog.yml → test/schemas/negative_test/changelogs/invalid-date/changelogs/changelog.yaml

@@ -1,3 +1,4 @@
+---
 releases:
   1.0.0:
     release_date: 01-01-2020 # invalid date format, must be ISO-8601 !

test/schemas/negative_test/changelogs/invalid-date/changelog.yml.md → test/schemas/negative_test/changelogs/invalid-date/changelogs/changelog.yaml.md

@@ -9,7 +9,7 @@
     "params": {
       "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d"
     },
-    "schemaPath": "#/$defs/release/properties/release_date/pattern"
+    "schemaPath": "#/properties/release_date/pattern"
   }
 ]
 ```
@@ -23,13 +23,13 @@ stdout:
   "status": "fail",
   "errors": [
     {
-      "filename": "negative_test/changelogs/invalid-date/changelog.yml",
+      "filename": "negative_test/changelogs/invalid-date/changelogs/changelog.yaml",
       "path": "$.releases.1.0.0.release_date",
       "message": "'01-01-2020' is not a 'date'",
       "has_sub_errors": false
     },
     {
-      "filename": "negative_test/changelogs/invalid-date/changelog.yml",
+      "filename": "negative_test/changelogs/invalid-date/changelogs/changelog.yaml",
       "path": "$.releases.1.0.0.release_date",
       "message": "'01-01-2020' does not match '\\\\d\\\\d\\\\d\\\\d-\\\\d\\\\d-\\\\d\\\\d'",
       "has_sub_errors": false

test/schemas/negative_test/changelogs/invalid-plugin-namespace/changelogs/changelog.yaml

@@ -0,0 +1,8 @@
+---
+releases:
+  1.0.0:
+    plugins:
+      lookup:
+        - name: reverse
+          description: Reverse magic
+          namespace: "foo" # namespace must be null for plugins and objects

test/schemas/negative_test/changelogs/invalid-plugin-namespace/changelogs/changelog.yaml.md

@@ -0,0 +1,34 @@
+# ajv errors
+
+```json
+[
+  {
+    "instancePath": "/releases/1.0.0/plugins/lookup/0/namespace",
+    "keyword": "type",
+    "message": "must be null",
+    "params": {
+      "type": "null"
+    },
+    "schemaPath": "#/$defs/plugin-descriptions/items/properties/namespace/type"
+  }
+]
+```
+
+# check-jsonschema
+
+stdout:
+
+```json
+{
+  "status": "fail",
+  "errors": [
+    {
+      "filename": "negative_test/changelogs/invalid-plugin-namespace/changelogs/changelog.yaml",
+      "path": "$.releases.1.0.0.plugins.lookup[0].namespace",
+      "message": "'foo' is not of type 'null'",
+      "has_sub_errors": false
+    }
+  ],
+  "parse_errors": []
+}
+```

test/schemas/negative_test/changelogs/list/changelog.yml.md → test/schemas/negative_test/changelogs/list/changelogs/changelog.yaml.md

@@ -23,7 +23,7 @@ stdout:
   "status": "fail",
   "errors": [
     {
-      "filename": "negative_test/changelogs/list/changelog.yml",
+      "filename": "negative_test/changelogs/list/changelogs/changelog.yaml",
       "path": "$",
       "message": "['this is invalid', 'as changelog must be object (mapping)', 'not an array (sequence)'] is not of type 'object'",
       "has_sub_errors": false

test/schemas/negative_test/changelogs/no-semver/changelog.yml → test/schemas/negative_test/changelogs/no-semver/changelogs/changelog.yaml

@@ -1 +1,2 @@
+---
 releases: foo # <-- not a semver

test/schemas/negative_test/changelogs/no-semver/changelog.yml.md → test/schemas/negative_test/changelogs/no-semver/changelogs/changelog.yaml.md

@@ -23,7 +23,7 @@ stdout:
   "status": "fail",
   "errors": [
     {
-      "filename": "negative_test/changelogs/no-semver/changelog.yml",
+      "filename": "negative_test/changelogs/no-semver/changelogs/changelog.yaml",
       "path": "$.releases",
       "message": "'foo' is not of type 'object'",
       "has_sub_errors": false

test/schemas/negative_test/changelogs/unknown-keys/changelog.yml → test/schemas/negative_test/changelogs/unknown-keys/changelogs/changelog.yaml

@@ -1 +1,2 @@
+---
 release: {} # <- unknown key, correct would be releases

test/schemas/negative_test/changelogs/unknown-keys/changelog.yml.md → test/schemas/negative_test/changelogs/unknown-keys/changelogs/changelog.yaml.md

@@ -23,7 +23,7 @@ stdout:
   "status": "fail",
   "errors": [
     {
-      "filename": "negative_test/changelogs/unknown-keys/changelog.yml",
+      "filename": "negative_test/changelogs/unknown-keys/changelogs/changelog.yaml",
       "path": "$",
       "message": "Additional properties are not allowed ('release' was unexpected)",
       "has_sub_errors": false