Add section on ows_extra_params for MapServer/MapServer#7360

Author: geographika

en/ogc/ogc_api.txt

@@ -9,7 +9,7 @@
 
 :Author:       Jeff McKenna
 :Contact:      jmckenna at gatewaygeomatics.com
-:Last Updated: 2025-09-11
+:Last Updated: 2025-10-10
 
 .. contents:: Table of Contents
     :depth: 3
@@ -42,9 +42,9 @@ and the relevant emerging OGC API standards.
 
 .. table:: 
    :align: left
-   
+
    +------------+---------------------+
-   | WxS        | OGC API             |          
+   | WxS        | OGC API             |
    +============+=====================+
    | OWS Common | OGC API - Common    |
    +------------+---------------------+   
@@ -58,7 +58,7 @@ and the relevant emerging OGC API standards.
    +------------+---------------------+   
    | SLD        | OGC API - Styles    |
    +------------+---------------------+
-   
+
 Requirements
 ============
 
@@ -360,17 +360,17 @@ Collections
   (JSON) or *ogcapi/collections?f=html* (HTML) such as::
 
     http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/collections?f=html
-  
+
   or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/collections?f=html``
-  
+
   .. image:: ../images/ogcapi-ms4w-collections.png
       :width: 400    
       :class: no-scaled-link
-      
+
   .. TIP::
      See a live MapServer 8.0 `OGCAPI: Features` collection at 
      https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections?f=html      
-      
+
 Collection Items
 ****************
 
@@ -380,30 +380,30 @@ Collection Items
     http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/collections/ + layername + /items?f=json
 
   or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/collections/lakes/items?f=json``
-  
+
   .. TIP::
      Another clear reason to **never** use spaces or special characters in your
      mapfile's layer NAME parameter.     
-  
+
   .. image:: ../images/ogcapi-ms4w-collections-items-geojson.png
       :width: 400    
       :class: no-scaled-link
 
   .. TIP::
      See a live MapServer 8.0 `OGCAPI: Features` collection item (as GeoJSON) at 
      https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections/lakes/items?f=json     
-      
+
 - you can access your OGC API collection items in HTML such as *ogcapi/collections/layername/items?f=html* 
   such as::
 
     http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/collections/ + layername + /items?f=html
-  
+
   or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/collections/lakes/items?f=html``     
 
   .. image:: ../images/ogcapi-ms4w-collections-items-html.png
       :width: 400    
       :class: no-scaled-link
-      
+
   .. TIP::
      See a live MapServer 8.0 `OGCAPI: Features` collection item (in HTML) at 
      https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections/lakes/items?f=html     
@@ -415,13 +415,13 @@ API Document
   (JSON) or *ogcapi/api?f=html* (HTML) such as::
 
     http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/api?f=json
-  
+
   or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/api?f=json``
-  
+
   .. image:: ../images/ogcapi-ms4w-api-json.png
       :width: 400    
       :class: no-scaled-link
-      
+
   .. TIP::
      See a live MapServer 8.0 `OGCAPI: Features` API document (in HTML) at 
      https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/api?f=html    
@@ -444,11 +444,70 @@ Web Object Metadata
 **ows_schemas_location**
 
   .. versionadded:: 8.2.0
-  
+
 - *Description:* (Optional) (Note the name *ows_schemas_location* because all
   OGC Web Services (OWS) use the same metadata) Root of the web tree where
   the family of OGC API JSON Schema files are located. This must be a valid URL
   where the actual .yaml files are located if you want your OpenAPI description
   to be valid. Default is *http://schemas.opengis.net*
 
+.. index::
+   triple: OGCAPI; METADATA; ows_schemas_location
+
+**ows_extra_params**
+
+  .. versionadded:: 8.4.0
+
+- *Description:* (Optional) The ``ows_extra_params`` (or ``oga_extra_params``) metadata entry allows you to append
+  additional query parameters to all URLs generated by MapServer. This can be used, for example, 
+  to include authentication tokens such as JSON Web Tokens (JWT) in your API requests.
+
+  The value supports :ref:`Run-time Substitution <runsub>`, where tokens in the form 
+  ``%TOKEN%``, are replaced with validated values from the query string or cookies.
+  Parameters are validated against the rules in the :ref:`VALIDATION <validation>` block.
+  ``ows_extra_params`` can also be set at the ``LAYER`` ``METADATA`` level, for adding or overriding parameters at the collection-level.
+  Example Mapfile:
+
+  .. code-block:: mapfile
+
+    WEB
+      VALIDATION
+        'token' '^[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+$'
+        'user_id' '^[0-9]+$' # only allow integers
+        'default_token' 'MISSING'
+        'default_user_id' '-1'
+      END
+      METADATA
+        "ows_extra_params" "token=%TOKEN%&user_id=%USER_ID%"
+
+  Example URL::
+
+      http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=html&token=eyJ9.e30.SflKxw&user_id=938
+
+  Will return JSON containing the same parameters and values for all links:
+
+  .. code-block:: json
+
+      {
+        "description": "This is a demo OGC API server.",
+        "links": [
+          {
+            "href": "http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=json&token=eyJ9.e30.SflKxw&user_id=938",
+
+  If a parameter is missing or invalid, it is replaced by the corresponding default value (e.g., ``MISSING`` for token, ``-1`` for user_id).
+  Example URL::
+
+      http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=html&token=@@@@@&user_id=a03kf-9
+
+  Will return:
+
+  .. code-block:: json
+
+      {
+        "description": "This is a demo OGC API server.",
+        "links": [
+          {
+            "href": "http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=json&token=MISSING&user_id=-1",
 
+  The extra parameters are available in HTML templates for the OGC Features API as ``{{ template.extra_params }}``.
+  The templates supplied in the MapServer repository append this value to all URLs by default.