diff --git a/conf.py b/conf.py index 32b6831049d..55032ffaf97 100644 --- a/conf.py +++ b/conf.py @@ -410,13 +410,13 @@ class WKTLexer(RegexLexer): r'BACKGROUNDSHADOWSIZE|BANDSITEM|BINDVALS|BROWSEFORMAT|BUFFER|CHARACTER|CLASS|CLASSITEM|' r'CLASSGROUP|CLUSTER|COLOR|COLORRANGE|COMPOSITE|COMPOP|COMPFILTER|CONFIG|' r'CONNECTION|CONNECTIONOPTIONS|CONNECTIONTYPE|DATA|DATAPATTERN|DATARANGE|DEBUG|' - r'DRIVER|DUMP|EMPTY|ENCODING|END|ERROR|EXPRESSION|EXTENT|EXTENSION|FEATURE|' + r'DRIVER|DUMP|EMPTY|ENCODING|END|ENV|ERROR|EXPRESSION|EXTENT|EXTENSION|FEATURE|' r'FILLED|FILTER|FILTERITEM|FOOTER|FONT|FONTSET|FORCE|FORMATOPTION|FROM|GAP|GEOMTRANSFORM|' r'GRID|GRIDSTEP|GRATICULE|GROUP|HEADER|IMAGE|IMAGECOLOR|IMAGETYPE|IMAGEQUALITY|IMAGEPATH|' r'IMAGEURL|INCLUDE|INDEX|INITIALGAP|INTERLACE|INTERVALS|JOIN|KEYIMAGE|KEYSIZE|KEYSPACING|LABEL|' r'LABELCACHE|LABELFORMAT|LABELITEM|LABELMAXSCALE|LABELMAXSCALEDENOM|' r'LABELMINSCALE|LABELMINSCALEDENOM|LABELREQUIRES|LATLON|LAYER|LEADER|LEGEND|' - r'LEGENDFORMAT|LINECAP|LINEJOIN|LINEJOINMAXSIZE|LOG|MAP|MARKER|MARKERSIZE|' + r'LEGENDFORMAT|LINECAP|LINEJOIN|LINEJOINMAXSIZE|LOG|MAP|MAPS|MARKER|MARKERSIZE|' r'MASK|MAXARCS|MAXBOXSIZE|MAXDISTANCE|MAXFEATURES|MAXINTERVAL|MAXSCALE|MAXSCALEDENOM|MINSCALE|' r'MINSCALEDENOM|MAXGEOWIDTH|MAXLENGTH|MAXSIZE|MAXSUBDIVIDE|MAXTEMPLATE|' r'MAXWIDTH|METADATA|MIMETYPE|MINARCS|MINBOXSIZE|MINDISTANCE|' diff --git a/en/development/rfc/ms-rfc-140.txt b/en/development/rfc/ms-rfc-140.txt index e9b0dfdc6e2..b2d3aa8df0c 100644 --- a/en/development/rfc/ms-rfc-140.txt +++ b/en/development/rfc/ms-rfc-140.txt @@ -6,7 +6,7 @@ MS RFC 140: MapServer Homepage :Author: Seth Girvin :Contact: sethg@geographika.co.uk -:Last Updated: 2025-01-18 +:Last Updated: 2025-01-23 :Version: MapServer 8.6 :Status: Draft @@ -21,6 +21,12 @@ would offer greater convenience and maintainability. With the introduction of the :ref:`CONFIG file ` in MapServer 8.0, it is now possible to centrally manage information about all Mapfiles in a deployment. This would ensure that the homepage remains automatically synchronised with both the CONFIG file and the capabilities of the Mapfiles it references. +The homepage would be a "superset" of all available Mapfiles in a MapServer deployment, as listed in the CONFIG file. +Each individual Mapfile would still have its own OGC API landing page, so the homepage is best described as a directory of all landing pages. + +As most MapServer deployments will likely be serving out a combination of WxS and new OGC API services for some time to come, +it will allow both types to be listed together. + 2.1 Proposed Solution ===================== @@ -59,42 +65,73 @@ Requests will look as follows: As the service returns JSON any client-side library can be used to render the output. However a default HTML template will be provided following the same approach as in OGC Features API. +.. note:: + + Even though the JSON format is based on the OGC API, the homepage JSON service will still be generated for a Mapfile even if it only supports + older WxS services. + JSON Structure -------------- JSON will be generated using the nlohmann/json and Inja approach already implemented in :ref:`MS RFC 134: OGC API Support `. -A proposed JSON structure is shown below. Final details may vary. URLs will be constructed based on settings in each individual Mapfile. + +The returned JSON will conform to the the `api-catalog `__, +a draft IETF (Internet Engineering Task Force) standard. An example implementation is the `pygeoapi homepage `__ +(see the associated `pull request `__). The JSON structure is available at +https://demo.pygeoapi.io/api-catalog.json. An extract is shown below: .. code-block:: json { - "id": "TEST_MAPFILE1", // the key in the config file - "name": "My_Mapfile", // the NAME in the Mapfile - "title": "My Mapfile Title", // the TITLE in the Mapfile - "links": [ - { - "href": "https://demo.mapserver.org/cgi-bin/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities", - "title": "GetCapabilities", - "type": "WMS" - }, + "linkset": [ { - "href": "https://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities", - "title": "GetCapabilities", - "type": "WFS" - }, - { - "href": "https://demo.mapserver.org/cgi-bin/wcs?SERVICE=WCS&VERSION=1.0.0&REQUEST=GetCapabilities", - "title": "GetCapabilities", - "type": "WCS" - }, - { - "href": "https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/api?f=html", - "title": "Landing Page", - "type": "OGCAPI" - }, - ] - } + "anchor": "https://demo.pygeoapi.io/master", + "service-desc": [ + { + "href": "https://demo.pygeoapi.io/master/openapi?f=json", + "title": "pygeoapi - latest GitHub 'master' version (JSON)", + "type": "application/vnd.oai.openapi+json" + } + ], + "service-doc": [ + { + "href": "https://demo.pygeoapi.io/master/openapi?f=html", + "title": "pygeoapi - latest GitHub 'master' version (HTML)", + "type": "text/html" + } + ] + }, + +The api-catalog specification allows for an additional ``service-meta`` property *"used to link to additional metadata about the API, +and is primarily intended for machine consumption."* This can be used to add any additional properties from Mapfiles +required to generate a MapServer homepage. ``service-doc`` isn't mandatory property, so WxS service links can ignore this. + +An example of the proposed JSON and metadata is shown below: + +.. code-block:: json + { + "linkset": [ + { + "anchor": "https://demo.mapserver.org/", + "service-desc": [ + { + "href": "https://demo.mapserver.org/cgi-bin/msautotest?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities", + "title": "World WMS service", + "type": "text/xml" + } + ], + "service-meta": { + { + "service-type": "wms", + "title": "WMS demo server for MapServer, used in the msautotest suite", + "keywords": ["layers", "list"], + "mapfile": "msautotest.map", + } + } + }, + +``href`` values will be constructed based on settings in each individual Mapfile. Future Development ------------------