From a63377449804c478cd68a30f25627dc9f5bbed7f Mon Sep 17 00:00:00 2001
From: s-hertel <19572925+s-hertel@users.noreply.github.com>
Date: Thu, 25 Sep 2025 18:00:57 -0400
Subject: [PATCH] Document play argument spec validation

---
 .../rst/playbook_guide/playbooks_intro.rst    | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/docs/docsite/rst/playbook_guide/playbooks_intro.rst b/docs/docsite/rst/playbook_guide/playbooks_intro.rst
index 664b2621ecc..e9fa8a1b8d5 100644
--- a/docs/docsite/rst/playbook_guide/playbooks_intro.rst
+++ b/docs/docsite/rst/playbook_guide/playbooks_intro.rst
@@ -153,6 +153,116 @@ You can use `ansible-lint <https://ansible.readthedocs.io/projects/lint/>`_ for
 
 The `ansible-lint default rules <https://ansible.readthedocs.io/projects/lint/rules/>`_ page describes each error.
 
+.. _play_argument_validation:
+
+Play Argument Validation
+------------------------
+
+Beginning in version 2.20, you can enable argument validation using the play keyword ``validate_argspec``. This adds a :ansplugin:`validate_argument_spec <ansible.builtin.validate_argument_spec#module>` task following play-level fact gathering. This feature is tech preview.
+
+To turn on validation for a play, set ``validate_argspec`` to ``True`` to use the play ``name`` as the argument specification identifier, or set ``validate_argspec`` to a string to use instead of the play ``name``.
+
+When play argument validation is enabled, a corresponding ``<playbook_name>.meta.yml`` file is required in the same directory as the playbook, and must contain a valid argument specification. This is a valid, empty argument specification named ``setup webserver`` for the playbook ``create_webserver.yml``:
+
+.. code-block:: yaml
+
+   # create_webserver.meta.yml
+   argument_specs:
+     setup webserver:
+       options: {}
+
+In the following playbook, both plays validate the play arguments against the ``setup webserver`` arguments:
+
+.. code-block:: yaml
+
+   # create_webserver.yml
+   - name: setup webserver
+     hosts: all
+     validate_argspec: True
+
+   - hosts: all
+     validate_argspec: setup webserver
+
+Specification Format
+--------------------
+
+The play argument specification must be defined in a top-level ``argument_specs`` block within the playbook's ``.meta.yml`` file. All fields are lowercase.
+
+:argument-spec-name:
+
+    * The name of the play or argument specification.
+
+    :description:
+
+        * A description of the play that may contain multiple lines.
+        * This can be a single string or a list of strings.
+
+    :options:
+
+        * This section defines the dictionary of play arguments.
+        * For each play option (argument), you may include:
+
+        :option-name:
+
+            * The name of the option/argument (required).
+
+        :description:
+
+            * Detailed explanation of what this option does. It should be written in full sentences.
+            * This can be a single string or a list of strings.
+
+        :type:
+
+            * The data type of the option. See :ref:`Argument spec <argument_spec>` for allowed values for ``type``. The default is ``str``.
+            * If an option is of type ``list``, ``elements`` should be specified.
+
+        :required:
+
+            * Only needed if ``true``.
+            * If missing, the option is not required.
+
+        :choices:
+
+            * List of option values.
+            * Should be absent if empty.
+
+        :elements:
+
+            * Specifies the data type for list elements when the type is ``list``.
+
+        :options:
+
+            * If this option takes a dict or list of dicts, you can define the structure here.
+
+Sample Specification
+--------------------
+
+.. code-block:: yaml
+
+   # create_webservers.meta.yml
+   description: Set up basic HTTPS-enabled webserver to serve content from a specified document root.
+   argument_specs:
+     setup webserver:
+       options:
+         document_root:
+           description: Path to the directory containing static web content to be served.
+           type: str
+           required: True
+         port:
+           description:
+             - Port number on which the webserver listens for incoming HTTPS connections.
+             - When unspecified, the port is 443.
+           type: int
+         ssl_cert_path:
+           description: Path to the SSL certificate.
+           type: str
+           required: True
+         ssl_key_path:
+           description: Path to the private key corresponding to the SSL certificate.
+           type: str
+           required: True
+
+
 .. seealso::
 
    `ansible-lint <https://ansible.readthedocs.io/projects/lint/>`_