schema: add validation of argument_specs.yml files (#2131)

Fixes: #1966

.github/workflows/tox.yml

@@ -155,7 +155,7 @@ jobs:
       WSLENV: FORCE_COLOR:PYTEST_REQPASS:TOXENV:TOX_PARALLEL_NO_SPINNER
       # Number of expected test passes, safety measure for accidental skip of
       # tests. Update value if you add/remove tests.
-      PYTEST_REQPASS: 642
+      PYTEST_REQPASS: 644
 
     steps:
       - name: Activate WSL1

examples/roles/broken_argument_specs/meta/argument_specs.yml

@@ -0,0 +1,5 @@
+---
+argument_specs:
+  main:
+    foo: bar # <-- invalid based on json schema
+    options: {}

examples/roles/hello/meta/argument_specs.yml

@@ -0,0 +1,27 @@
+---
+# https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#role-argument-validation
+argument_specs:
+  main:
+    short_description: The main entry point for the role.
+    description: "a longer description"
+    options:
+      my_app_int:
+        type: "int"
+        required: false
+        default: 42
+        description: "The integer value, defaulting to 42."
+        no_log: false
+
+      my_app_str:
+        type: "str"
+        required: true
+        description: "The string value"
+
+  alternate:
+    short_description: The alternate entry point for the my_app role.
+    options:
+      my_app_int:
+        type: "int"
+        required: false
+        default: 1024
+        description: "The integer value, defaulting to 1024."

src/ansiblelint/config.py

@@ -77,6 +77,7 @@
     "inventory": "https://raw.githubusercontent.com/ansible/schemas/main/f/ansible-inventory.json",
     "ansible-lint-config": "https://raw.githubusercontent.com/ansible/schemas/main/f/ansible-lint.json",
     "ansible-navigator-config": "https://raw.githubusercontent.com/ansible/ansible-navigator/main/src/ansible_navigator/data/ansible-navigator.json",
+    "arg_specs": "https://raw.githubusercontent.com/ansible/schemas/main/f/ansible-argument-specs.json",
 }
 
 options = Namespace(

src/ansiblelint/rules/schema.py

@@ -166,6 +166,16 @@ def matchyaml(self, file: Lintable) -> List[MatchError]:
                 "ansible-navigator-config",
                 ["Additional properties are not allowed ('ansible' was unexpected)"],
             ),
+            (
+                "examples/roles/hello/meta/argument_specs.yml",
+                "arg_specs",
+                [],
+            ),
+            (
+                "examples/roles/broken_argument_specs/meta/argument_specs.yml",
+                "arg_specs",
+                ["Additional properties are not allowed ('foo' was unexpected)"],
+            ),
         ),
         ids=(
             # "playbook-fail",
@@ -184,6 +194,8 @@ def matchyaml(self, file: Lintable) -> List[MatchError]:
             "lint-config-broken",
             "navigator",
             "navigator-broken",
+            "argspecs",
+            "argspecs-broken",
         ),
     )
     def test_schema(file: str, expected_kind: str, expected: List[str]) -> None:

src/ansiblelint/schemas/arg_specs.json

@@ -0,0 +1,143 @@
+{
+  "$id": "https://raw.githubusercontent.com/ansible/schemas/main/f/ansible-argument-specs.json",
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "additionalProperties": false,
+  "definitions": {
+    "datatype": {
+      "enum": [
+        "str",
+        "list",
+        "dict",
+        "bool",
+        "int",
+        "float",
+        "path",
+        "raw",
+        "jsonarg",
+        "json",
+        "bytes",
+        "bits"
+      ],
+      "type": "string"
+    },
+    "deprecated_alias": {
+      "properties": {
+        "collection_name": {
+          "type": "string"
+        },
+        "date": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "required": ["name"],
+      "type": "object"
+    },
+    "entry_point": {
+      "additionalProperties": false,
+      "properties": {
+        "author": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "options": {
+          "additionalProperties": {
+            "$ref": "#/definitions/option"
+          },
+          "type": "object"
+        },
+        "short_description": {
+          "type": "string"
+        }
+      },
+      "required": ["options"],
+      "title": "Entry Point",
+      "type": "object"
+    },
+    "option": {
+      "additionalProperties": false,
+      "aliases": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "apply_defaults": {
+        "type": "string"
+      },
+      "deprecated_aliases": {
+        "items": {
+          "$ref": "#/definitions/deprecated_alias"
+        },
+        "type": "array"
+      },
+      "markdownDescription": "xxx",
+      "options": {
+        "$ref": "#/definitions/option"
+      },
+      "properties": {
+        "choices": {
+          "$ref": "#/definitions/datatype"
+        },
+        "default": {
+          "default": "None"
+        },
+        "description": {
+          "description": "Detailed explanation of what this option does. It should be written in full sentences.",
+          "type": "string"
+        },
+        "elements": {
+          "$ref": "#/definitions/datatype"
+        },
+        "fallback": {
+          "default": "None",
+          "type": "string"
+        },
+        "no_log": {
+          "default": false,
+          "type": "boolean"
+        },
+        "option-name": {
+          "description": "The name of the option/argument.",
+          "type": "string"
+        },
+        "required": {
+          "default": false,
+          "type": "boolean"
+        },
+        "type": {
+          "$ref": "#/definitions/datatype",
+          "markdownDescription": "See [argument-spec](https://docs.ansible.com/ansible/latest/dev_guide/developing_program_flow_modules.html#argument-spec"
+        }
+      },
+      "removed_at_date": {
+        "type": "string"
+      },
+      "removed_from_collection": {
+        "type": "string"
+      },
+      "removed_in_version": {
+        "type": "string"
+      },
+      "title": "Option"
+    }
+  },
+  "examples": ["meta/argument_specs.yml"],
+  "markdownDescription": "Add entry point, usually `main`.\nSee [role-argument-validation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#role-argument-validation)",
+  "properties": {
+    "argument_specs": {
+      "additionalProperties": {
+        "$ref": "#/definitions/entry_point"
+      },
+      "markdownDescription": "Add entry point, usually `main`.\nSee [role-argument-validation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#role-argument-validation)"
+    }
+  },
+  "title": "Ansible Argument Specs Schema"
+}