Add play argspec schema validation to schema rule (#4667)

Author: alisonlhart

.config/dictionary.txt

@@ -41,6 +41,7 @@ ansiblelint
 apidoc
 apport
 argparsing
+argspec
 argspecs
 arxcruz
 audgirka

examples/play_argspecs/correct_play_argspec/patterns/example_pattern/playbooks/meta/site.yml

@@ -0,0 +1,114 @@
+# Valid play argspec
+---
+short_description: Advanced config management
+description: This playbook handles complex infrastructure deployments with comprehensive configuration options
+argument_specs:
+  deploy_infrastructure:
+    short_description: Deploy complete infrastructure stack
+    description:
+      - Deploys a multi-tier application infrastructure
+      - Configures web servers, databases, and load balancers
+    author:
+      - Infrastructure Team (@infra-team)
+      - DevOps Engineer (@devops-lead)
+    options:
+      environment:
+        type: str
+        required: true
+        choices:
+          - development
+          - staging
+          - production
+        description: Target deployment environment
+      web_server_count:
+        type: int
+        required: false
+        default: 2
+        description: Number of web servers to deploy
+      database_engine:
+        type: str
+        required: true
+        choices:
+          - postgresql
+          - mysql
+          - mongodb
+        description: Database engine to use
+      enable_ssl:
+        type: bool
+        required: false
+        default: true
+        description: Whether to enable SSL/TLS encryption
+    examples: |
+      # Basic deployment
+      - import_playbook: site.yml
+        vars:
+          environment: production
+          database_engine: postgresql
+          web_server_count: 3
+    return: ~
+  configure_monitoring:
+    short_description: Configure monitoring and alerting systems
+    description:
+      - Sets up comprehensive monitoring stack
+      - Configures alerting rules and notifications
+      - Integrates with external monitoring services
+    author:
+      - Monitoring Team (@monitoring-team)
+    options:
+      monitoring_stack:
+        type: str
+        required: true
+        choices:
+          - prometheus_grafana
+          - elk_stack
+        description: Monitoring stack to deploy
+      alert_channels:
+        type: list
+        required: false
+        default:
+          - email
+        description: Alert notification channels
+    examples: |
+      # Basic monitoring setup
+      - import_playbook: site.yml
+        vars:
+          monitoring_stack: prometheus_grafana
+          alert_channels:
+            - email
+            - slack
+    return: ~
+
+  security_hardening:
+    short_description: Apply security hardening configurations
+    description:
+      - Implements security best practices
+      - Configures firewalls and access controls
+      - Sets up vulnerability scanning
+    author:
+      - Security Team (@security-team)
+    options:
+      security_level:
+        type: str
+        required: true
+        choices:
+          - basic
+          - enhanced
+          - strict
+        description: Level of security hardening to apply
+      enable_firewall:
+        type: bool
+        required: false
+        default: true
+        description: Whether to configure host-based firewall
+      vulnerability_scanning:
+        type: bool
+        required: false
+        default: false
+        description: Enable automated vulnerability scanning
+    examples: |
+      # Basic security hardening
+      - import_playbook: site.yml
+        vars:
+          security_level: enhanced
+          enable_firewall: true
+    return: ~

examples/play_argspecs/incorrect_play_argspec/site.meta.yaml

@@ -0,0 +1,8 @@
+# Violates json schema - missing required fields in argument spec
+---
+short_description: Weather forecast playbook
+description: Gets weather data from airport codes
+argument_specs:
+  weather_check:
+    short_description: Get weather info
+    # Missing required 'options' and 'examples' fields

src/ansiblelint/config.py

@@ -54,6 +54,8 @@
     {"tasks": "**/tasks/**/*.{yaml,yml}"},
     {"rulebook": "**/rulebooks/*.{yml,yaml"},
     {"pattern": "**/patterns/*/meta/pattern.json"},
+    {"play-argspec": "**/patterns/*/playbooks/meta/*.{yaml,yml}"},
+    {"play-argspec": "**/*.meta.{yaml,yml}"},
     {"playbook": "**/playbooks/*.{yml,yaml}"},
     {"playbook": "**/*playbook*.{yml,yaml}"},
     {"role": "**/roles/*/"},

src/ansiblelint/rules/schema.md

@@ -41,6 +41,7 @@ project:
   [role/metadata.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/playbook/role/metadata.py#L79))
   for details.
 - `schema[pattern]` validates Ansible patterns.
+- `schema[[play-argspec]]` validates Ansible playbook [argspec files](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/validate_argument_spec_module.html).
 - `schema[playbook]` validates Ansible playbooks.
 - `schema[requirements]` validates Ansible
   [requirements](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#install-multiple-collections-with-a-requirements-file)

src/ansiblelint/rules/schema.py

@@ -74,6 +74,7 @@ class ValidateSchemaRule(AnsibleLintRule):
         "schema[meta-runtime]": "",
         "schema[molecule]": "",
         "schema[pattern]": "",
+        "schema[play-argspec]": "",
         "schema[playbook]": "",
         "schema[requirements]": "",
         "schema[role-arg-spec]": "",
@@ -382,6 +383,20 @@ def matchyaml(self, file: Lintable) -> list[MatchError]:
                 ],
                 id="pattern_negative",
             ),
+            pytest.param(
+                "examples/play_argspecs/correct_play_argspec/patterns/example_pattern/playbooks/meta/site.yml",
+                "play-argspec",
+                [],
+                id="play_argspec_positive",
+            ),
+            pytest.param(
+                "examples/play_argspecs/incorrect_play_argspec/site.meta.yaml",
+                "play-argspec",
+                [
+                    r"\$.argument_specs.weather_check 'options' is a required property.",
+                ],
+                id="play_argspec_negative",
+            ),
         ),
     )
     def test_schema(

src/ansiblelint/schemas/__store__.json

@@ -38,6 +38,9 @@
   "pattern": {
     "url": "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/pattern.json"
   },
+  "play-argspec": {
+    "url": "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/play-argspec.json"
+  },
   "playbook": {
     "etag": "4f8cbba62fcf8a1fa6e8ef5e42696aec5b0876487478df83a7ffdf8bdbb4abcf",
     "url": "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/playbook.json"

src/ansiblelint/schemas/play-argspec.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/play-argspec.json",
+  "title": "Ansible Playbook Argspec Schema",
+  "description": "See https://docs.ansible.com/ansible/latest/collections/ansible/builtin/validate_argument_spec_module.html",
+  "examples": [
+    "extensions/patterns/*/playbooks/meta/*.yml",
+    "extensions/patterns/*/playbooks/meta/*.yaml",
+    "**/*.meta.yml",
+    "**/*.meta.yaml"
+  ],
+  "type": "object",
+  "properties": {
+    "short_description": {
+      "type": "string",
+      "description": "Brief description of the playbook"
+    },
+    "description": {
+      "type": "string",
+      "description": "Detailed description of the playbook"
+    },
+    "argument_specs": {
+      "type": "object",
+      "description": "Argument specifications for the playbook",
+      "minProperties": 1,
+      "patternProperties": {
+        "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+          "type": "object",
+          "properties": {
+            "short_description": {
+              "type": "string",
+              "description": "Brief description of the argument spec"
+            },
+            "description": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Detailed description lines"
+            },
+            "author": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "List of authors"
+            },
+            "options": {
+              "type": "object",
+              "description": "Available options/parameters",
+              "patternProperties": {
+                "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "enum": [
+                        "str",
+                        "int",
+                        "bool",
+                        "float",
+                        "list",
+                        "dict",
+                        "path",
+                        "raw"
+                      ],
+                      "description": "Parameter type"
+                    },
+                    "required": {
+                      "type": "boolean",
+                      "description": "Whether the parameter is required"
+                    },
+                    "default": {
+                      "description": "Default value for the parameter"
+                    },
+                    "choices": {
+                      "type": "array",
+                      "description": "Valid choices for the parameter"
+                    },
+                    "description": {
+                      "type": "string",
+                      "description": "Description of the parameter"
+                    }
+                  },
+                  "additionalProperties": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "examples": {
+              "type": "string",
+              "description": "Usage examples in YAML format"
+            },
+            "return": {
+              "description": "Return value specification"
+            }
+          },
+          "required": ["short_description", "options", "examples"],
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["short_description", "description", "argument_specs"],
+  "additionalProperties": false
+}

test/schemas/negative_test/play_argspec/site.meta.yaml

@@ -0,0 +1,8 @@
+# Violates json schema - missing required fields in argument spec
+---
+short_description: Weather forecast playbook
+description: Gets weather data from airport codes
+argument_specs:
+  weather_check:
+    short_description: Get weather info
+    # Missing required 'options' and 'examples' fields

test/schemas/negative_test/play_argspec/site.meta.yaml.md

@@ -0,0 +1,50 @@
+# ajv errors
+
+```json
+[
+  {
+    "instancePath": "/argument_specs/weather_check",
+    "keyword": "required",
+    "message": "must have required property 'options'",
+    "params": {
+      "missingProperty": "options"
+    },
+    "schemaPath": "#/properties/argument_specs/patternProperties/%5E%5Ba-zA-Z_%5D%5Ba-zA-Z0-9_%5D*%24/required"
+  },
+  {
+    "instancePath": "/argument_specs/weather_check",
+    "keyword": "required",
+    "message": "must have required property 'examples'",
+    "params": {
+      "missingProperty": "examples"
+    },
+    "schemaPath": "#/properties/argument_specs/patternProperties/%5E%5Ba-zA-Z_%5D%5Ba-zA-Z0-9_%5D*%24/required"
+  }
+]
+```
+
+# check-jsonschema
+
+stdout:
+
+```json
+{
+  "status": "fail",
+  "successes": [],
+  "errors": [
+    {
+      "filename": "negative_test/play_argspec/site.meta.yaml",
+      "path": "$.argument_specs.weather_check",
+      "message": "'options' is a required property",
+      "has_sub_errors": false
+    },
+    {
+      "filename": "negative_test/play_argspec/site.meta.yaml",
+      "path": "$.argument_specs.weather_check",
+      "message": "'examples' is a required property",
+      "has_sub_errors": false
+    }
+  ],
+  "parse_errors": []
+}
+```