Skip to content

Document oga metadata items #1067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
geographika wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document oga metadata items #1067

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 87 additions & 36 deletions en/ogc/ogc_api.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand All @@ -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**

Expand Down Expand Up @@ -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.
51 changes: 42 additions & 9 deletions en/ogc/wfs_server.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
----------------------
Expand Down