Document oga_fallback_to_map_extent and oga_use_default_extent_for_getfeature (#1067)

Author: geographika

en/ogc/ogc_api.txt

@@ -9,7 +9,9 @@
 
 :Author:       Jeff McKenna
 :Contact:      jmckenna at gatewaygeomatics.com
-:Last Updated: 2025-12-12
+:Author:       Seth Girvin
+:Contact:      sethg at geographika.co.uk
+:Last Updated: 2026-03-26
 
 .. contents:: Table of Contents
     :depth: 3
@@ -274,6 +276,8 @@ Example OGC API Server Mapfile
         "ows_getfeatureinfo_formatlist" "text/plain,text/html,application/json,application/vnd.ogc.gml,gml"
         "ows_enable_request"    "*" #REQUIRED
         "oga_html_template_directory" "share/ogcapi/templates/html-bootstrap/" #REQUIRED
+        "oga_fallback_to_map_extent" "true" # Optional. Can improve performance.
+        "oga_use_default_extent_for_getfeature" "false" # Optional. Can improve performance.
       END
     END
 
@@ -302,7 +306,8 @@ Example OGC API Server Mapfile
         "ows_abstract" "Oceans, NaturalEarth dataset, 2020"
         "gml_include_items" "all" #REQUIRED
         "gml_featureid"     "ne_id" #REQUIRED
-        "oga_use_default_extent_for_getfeature" # Optional. Can improve performance.
+        "oga_fallback_to_map_extent" "false" # Optional. Override WEB setting
+        "oga_use_default_extent_for_getfeature" "true" # Optional. Override WEB setting
         "oga_queryable_items" "all"  # required to allow filtering
         "oga_geometry_format" "geometry-polygn"
         "oga_sortable_items" "area"
@@ -462,13 +467,13 @@ Web Object Metadata
 -------------------
 
 .. index::
-   triple: OGCAPI; METADATA; ows_extra_params
+   triple: OGCAPI; METADATA; oga_extra_params
 
-**ows_extra_params**
+**oga_extra_params**
 
   .. versionadded:: 8.6.0
 
-- *Description:* (Optional) The ``ows_extra_params`` (or ``oga_extra_params``) metadata entry allows you to append
+- *Description:* (Optional) The ``oga_extra_params`` (or ``ows_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.
 
@@ -522,6 +527,34 @@ Web Object Metadata
   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.
 
+.. _oga_fallback_to_map_extent:
+
+.. index::
+   triple: OGCAPI; METADATA; oga_fallback_to_map_extent
+
+**oga_fallback_to_map_extent**
+
+  .. versionadded:: 8.8.0
+
+- *Description:* (Optional) (or ``ows_fallback_to_map_extent``)
+  When set to ``true``, if a ``LAYER`` has no explicit
+  :ref:`EXTENT <mapfile-layer-extent>` and no ``ows_extent`` metadata item,
+  MapServer will use the :ref:`MAP EXTENT <mapfile-map-extent>` as a fallback
+  rather than querying the datasource to calculate the layer extent.
+  The full priority order for extent resolution is:
+
+  1. Layer ``ows_extent`` (or namespace-specific ``oga_extent``) metadata
+  2. Layer ``EXTENT``
+  3. Map ``EXTENT``, if this metadata item is set to ``true`` *(this option)*
+  4. Extent calculated from the datasource
+
+  Datasource extent calculation can be very slow for database
+  layers. For some layer types (e.g. raster), it may be near-instant.
+
+  This item can be set in ``MAP WEB METADATA`` to apply to all layers, and
+  can be overridden per-layer in ``LAYER METADATA`` to enable or disable the
+  fallback for specific layers.
+
 .. index::
    triple: OGCAPI; METADATA; oga_features_cache_count
 
@@ -543,20 +576,27 @@ Web Object Metadata
   Size of cache in bytes. See :ref:`wfs_features_cache_size` for details.
 
 .. index::
-   triple: OGCAPI; METADATA; ows_schemas_location
+   triple: OGCAPI; METADATA; oga_geometry_format
 
-**ows_schemas_location**
+**oga_geometry_format**
 
-  .. versionadded:: 8.2.0
+  .. versionadded:: 8.8.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*
+- *Description:* (Optional) Value among "geometry-point", "geometry-multipoint",
+  "geometry-linestring", "geometry-multilinestring", "geometry-polygon",
+  "geometry-multipolygon", "geometry-geometrycollection", "geometry-any" (default value),
+  "geometry-point-or-multipoint", "geometry-linestring-or-multilinestring" 
+  and "geometry-polygon-or-multipolygon"
 
-.. index::
-   triple: OGCAPI; METADATA; oga_queryable_items
+- Example Mapfile:
+
+  .. code-block:: mapfile
+
+    LAYER
+      METADATA
+        "oga_geometry_format" "geometry-polygon-or-multipolygon"
+      END
+    END
 
 **oga_queryable_items**
 
@@ -604,41 +644,52 @@ Web Object Metadata
       END
     END
 
+.. _oga_use_default_extent_for_getfeature:
+
 .. index::
-   triple: OGCAPI; METADATA; oga_geometry_format
+   triple: OGCAPI; METADATA; ows_schemas_location
 
-**oga_geometry_format**
+**oga_use_default_extent_for_getfeature**
 
-  .. versionadded:: 8.8.0
+  .. versionadded:: 8.4.0
 
-- *Description:* (Optional) Value among "geometry-point", "geometry-multipoint",
-  "geometry-linestring", "geometry-multilinestring", "geometry-polygon",
-  "geometry-multipolygon", "geometry-geometrycollection", "geometry-any" (default value),
-  "geometry-point-or-multipoint", "geometry-linestring-or-multilinestring" 
-  and "geometry-polygon-or-multipolygon"
+- *Description:* (Optional) (or ``ows_use_default_extent_for_getfeature``)
+   Use ``MAP`` ``EXTENT`` as a spatial filter if no bbox is in the request.
+   Setting to ``"false"`` can improve performance. See WFS equivalent
+   at :ref:`wfs_use_default_extent_for_getfeature`.
 
-- Example Mapfile:
+**ows_schemas_location**
 
-  .. code-block:: mapfile
+  .. versionadded:: 8.2.0
 
-    LAYER
-      METADATA
-        "oga_geometry_format" "geometry-polygon-or-multipolygon"
-      END
-    END
+- *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; oga_use_default_extent_for_getfeature
+   triple: OGCAPI; METADATA; oga_queryable_items
 
 Layer Object Metadata
 ---------------------
 
+.. index::
+   triple: OGCAPI; METADATA; oga_fallback_to_map_extent
+
+**oga_fallback_to_map_extent**
+
+  .. versionadded:: 8.8.0
+
+  Same as :ref:`oga_fallback_to_map_extent <oga_fallback_to_map_extent>` in ``MAP WEB METADATA``, and can be
+  set here to override the behaviour for individual layers.
+
+  .. index::
+   triple: OGCAPI; METADATA; oga_use_default_extent_for_getfeature
+
 **oga_use_default_extent_for_getfeature**
 
   .. versionadded:: 8.4.0
 
-- *Description:* (Optional) (or ``ows_use_default_extent_for_getfeature``)
-   Use ``MAP`` ``EXTENT`` as a spatial filter if no bbox is in the request.
-   Setting to ``"false"`` can improve performance. See WFS equivalent
-   at :ref:`wfs_use_default_extent_for_getfeature`.
-
+  Same as :ref:`oga_use_default_extent_for_getfeature <oga_use_default_extent_for_getfeature>` in ``MAP WEB METADATA``, and can be
+  set here to override the behaviour for individual layers.

en/ogc/wfs_server.txt

@@ -801,6 +801,22 @@ Web Object Metadata
 
     "wfs_enable_request" "* !GetCapabilities"
 
+.. _wfs_fallback_to_map_extent:
+
+.. index:: 
+   triple: WFS; METADATA; wfs_fallback_to_map_extent
+
+**wfs_fallback_to_map_extent**
+
+  .. versionadded:: 8.8.0
+
+- *Description:* (Optional) (or ``ows_fallback_to_map_extent``)
+  When set to ``true``, if a ``LAYER`` has no explicit
+  :ref:`EXTENT <mapfile-layer-extent>` and no ``ows_extent`` metadata item,
+  MapServer will use the :ref:`MAP EXTENT <mapfile-map-extent>` as a fallback
+  rather than querying the datasource to calculate the layer extent.
+  See :ref:`oga_fallback_to_map_extent <oga_fallback_to_map_extent>` for details
+
 .. index:: 
    triple: WFS; METADATA; wfs_feature_collection
 
@@ -1024,6 +1040,20 @@ Web Object Metadata
   (Required) Human readable title to identify server. 
   WFS TAG Name: Title (WFS 1.0.0, sect. 12.3.3)
 
+.. _wfs_use_default_extent_for_getfeature:
+
+.. index::
+   triple: WFS; METADATA; wfs_use_default_extent_for_getfeature
+
+**wfs_use_default_extent_for_getfeature**
+  (Optional, since MapServer 7.0.4) Whether the MAP.EXTENT should be used in
+  request to datasources in the absence of other spatial filter. This is the
+  default behaviour, but this might affect performance in some use cases. In
+  those cases, setting this item to "false" will avoid the default spatial filter to
+  be appended to the request. This is only implemented for OGR datasources (since 7.0.4),
+  MSSQL2008 (since 7.6), and PostGIS connections (since 8.4).
+  Use **ows_use_default_extent_for_getfeature** to set for both WFS and :ref:`ogcapi`.
+
 .. index:: 
    triple: WFS; LAYER; METADATA
 
@@ -1335,6 +1365,16 @@ Layer Object
   projection units. If wfs_extent is provided then it has priority and
   MapServer will NOT try to read the source file's extents.
 
+.. index:: 
+   triple: WFS; METADATA; wfs_fallback_to_map_extent
+
+**wfs_fallback_to_map_extent**
+
+  .. versionadded:: 8.8.0
+
+  Same as :ref:`wfs_fallback_to_map_extent <wfs_fallback_to_map_extent>` in ``MAP WEB METADATA``, and can be
+  set here to override the behaviour for individual layers.
+
 .. index:: 
    triple: WFS; METADATA; wfs_featureid
 
@@ -1467,16 +1507,9 @@ Layer Object
 .. index::
    triple: WFS; METADATA; wfs_use_default_extent_for_getfeature
 
-.. _wfs_use_default_extent_for_getfeature:
-
 **wfs_use_default_extent_for_getfeature**
-  (Optional, since MapServer 7.0.4) Whether the MAP.EXTENT should be used in
-  request to datasources in the absence of other spatial filter. This is the
-  default behaviour, but this might affect performance in some use cases. In
-  those cases, setting this item to "false" will avoid the default spatial filter to
-  be appended to the request. This is only implemented for OGR datasources (since 7.0.4),
-  MSSQL2008 (since 7.6), and PostGIS connections (since 8.4).
-  Use **ows_use_default_extent_for_getfeature** to set for both WFS and :ref:`ogcapi`.
+  Same as :ref:`wfs_use_default_extent_for_getfeature <wfs_use_default_extent_for_getfeature>` in ``MAP WEB METADATA``, and can be
+  set here to override the behaviour for individual layers.
 
 Layer Metadata API
 ----------------------