Merge pull request #135 from opengeospatial/20240726_2nd_final_staff_…

…edits

20240726 - 2nd final staff edits

core/standard/annex_examples.adoc

@@ -2,7 +2,7 @@
 :appendix-caption: Annex
 [[annex_examples]]
 == Examples (informative)
-This annex provides a set of examples illustrating requests and responses for retrieving maps using capabilities defined by this Maps API.
+This annex provides a set of examples illustrating requests and responses for retrieving maps using capabilities defined by this OGC API - Maps Standard.
 
 === Default map
 The first example shows the response of a map endpoint with a request with no parameters (https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal/map).
@@ -279,7 +279,7 @@ image::images/xmp_hrdem_style2.png[width=550,align="center"]
 
 It is also common for spatial datasets, especially for weather and climate data, to feature additional dimensions beyond space and time,
 such as pressure levels, or additional time dimensions relating to forecasting. These can all be handled in a generic manner also using the `subset` parameter.
-The following two example illustrates how to retrieve a map of the temperature for the whole world at _pressure_ (an extra dimension) levels of 500 and 850 hectopascals:
+The following two examples illustrate how to retrieve a map of the temperature for the whole world at _pressure_ (an extra dimension) levels of 500 and 850 hectopascals:
 
 https://maps.gnosis.earth/ogcapi/collections/climate:cmip5:byPressureLevel:temperature/map?subset=pressure(500)&datetime=2023-07-03&bgcolor=gray
 
@@ -526,7 +526,7 @@ One approach could be to project two points 1 degree of longitude apart around t
 using the implementation's projection library, to obtain the number of CRS units per degree of longitude.
 Transforming (40.7514917°N, 14.5°E) to EPSG:3395 yields (E: 1,614,132.62, N: 4,947,856.85) and transforming (40.7514917°N, 15.5°E) yields (E: 1,725,452.11, N: 4,947,856.85).
 The resulting easting delta (`oneDegEastingDelta` below) is 111,319.49, which in this case can be recognized as the actual physical meters per degree at the equator, rather than at the center latitude used.
-Therefore, in this case implementations effectively needs to apply the reverse correction that had to be applied for Plate Carrée when considering the numbers of true meters per Easting unit.
+Therefore, in this case implementations effectively need to apply the reverse correction that had to be applied for Plate Carrée when considering the numbers of true meters per Easting unit.
 First, `metersPerDegLon` can be computed as in the previous example:
 
 [%unnumbered%]

core/standard/annex_ogc_wms.adoc

@@ -25,7 +25,7 @@ Beside the general alignment with the architecture of the Web (e.g., consistency
 * Clear separation between Core requirements and more advanced capabilities. The _OGC API - Maps - Part 1: Core_ Standard presents the requirements that are
 relevant for almost any organization wanting to share or use maps at a fine-grained level. Additional capabilities deemed useful for several communities will be specified as extensions to the Core API.
 * Technologies that change more frequently are decoupled and specified in separate modules ("requirements classes" in OGC terminology). This enables, for example, the use/re-use of new encodings for spatial data or Web API definition (such as new version of the OpenAPI description document).
-* Modularization is not just about a single "service". OGC API Standards define building blocks that can be reused in APIs implementation in general. In other words, a server supporting _OGC API - Maps_ should not be seen as a standalone service. Rather it should be viewed as a collection of Web API building blocks that together implement _OGC API - Maps_ capabilities. A corollary for this is that it should be possible to implement an API that simultaneously conforms to conformance classes from the Features, Coverages, Maps, Tiles, and other future OGC API standards.
+* Modularization is not just about a single "service". OGC API Standards define building blocks that can be reused in API implementations in general. In other words, a server supporting _OGC API - Maps_ should not be seen as a standalone service. Rather it should be viewed as a collection of Web API building blocks that together implement _OGC API - Maps_ capabilities. A corollary for this is that it should be possible to implement an API that simultaneously conforms to conformance classes from the https://ogcapi.ogc.org/features/[OGC API - Features], https://ogcapi.ogc.org/coverages/[OGC API - Coverages], https://ogcapi.ogc.org/maps/[OGC API - Maps], https://ogcapi.ogc.org/tiles/[OGC API - Tiles], and other future OGC API Standards.
 
 This approach intends to support two types of client developers:
 
@@ -37,7 +37,7 @@ As a result of following a RESTful approach, OGC API implementations are not bac
 
 === Comparison between _WMS_ and _OGC API - Maps_
 
-The OGC WMS and WMTS share the concept of a map and the capability to create and distribute maps at a limited resolution and size.
+The OGC WMS and WMTS Standards share the concept of a map and the capability to create and distribute maps at a limited resolution and size.
 In WMS, the number of rows and columns can be selected by the user within limits and in WMTS the number of rows and columns of the response is predefined in the tile matrix set.
 
 The concept of a map used in OGC API Standards is more abstract than the one used in WMS. Read more about the map concept in the <<overview>>.
@@ -64,12 +64,12 @@ Finally, _OGC API - Maps_ can also be used to represent a vertical dimension. Th
 selecting a vertical subset of features to be rendered on a 2D output, or by rendering a vertical profile.
 Some examples include:
 
-* 3D map to be displayed on virtual reality devices,
-* 1D graph of NDVI over time for a particular point,
-* 1D graph of a temperature over a vertical profile for a given spatial point,
+* a 3D map to be displayed on virtual reality devices,
+* a 1D graph of NDVI over time for a particular point,
+* a 1D graph of a temperature over a vertical profile for a given spatial point,
 * intensity of rain along a latitude and vertical dimension,
-* video over temporal axis,
-* video of temperature representing different elevation levels in different frames of the video.
+* a video over a temporal axis,
+* a video of temperature representing different elevation levels in different frames of the video.
 
 ==== Correspondence between WMS map metadata and OGC API Standards
 
@@ -160,7 +160,7 @@ NOTE: The supported formats for map resources, or more precisely the media types
 NOTE: The `opaque` XML attribute in WMS was rarely useful and has been removed. This attribute indicated whether the map data represents features that probably do not completely fill space and shows the background opaque (true) or transparent (false).
 
 ==== No equivalent to _GetFeatureInfo_ as part of the OGC API - Maps - Part 1
-The OGC Web Map Service _GetFeatureInfo_ operation provides the capability for clients to implement some simple level of user interaction with the map. In essence the user can focus on a point in the map (e.g., by clicking on it) and the client will request from the server some textual information related to the elements represented at that point of the map (a functionality sometimes called "query by location"). If the elements represented in the map are simple features, the result should be related to their properties (attributes). If the map represents a coverage, the result should report the value of the coverage in that position (eventually, if the coverage is multidimensional, it could be a e.g., time series graphic or a vertical profile). The format of the actual response is left to the discretion of the server.
+The OGC Web Map Service _GetFeatureInfo_ operation provides the capability for clients to implement some simple level of user interaction with the map. In essence the user can focus on a point on the map (e.g., by clicking on it) and the client will request from the server some textual information related to the elements represented at that point of the map (a functionality sometimes called "query by location"). If the elements represented in the map are simple features, the result should be related to their properties (attributes). If the map represents a coverage, the result should report the value of the coverage in that position (eventually, if the coverage is multidimensional, it could be a e.g., time series graphic or a vertical profile). The format of the actual response is left to the discretion of the server.
 
 _GetFeatureInfo_ was first proposed in the 2000 version of the OGC Web Map Service Standard. In that environment _GetFeatureInfo_ provided an easy to implement solution for the first step to "queryable" maps. 
 
@@ -170,7 +170,7 @@ Implementers of map clients are encouraged to implement support for OGC API Stan
 
   * In _OGC API - Features_, map coordinates should be transformed to Lon,Lat WGS84 in the client side and implement an HTTP GET request to `/collections/{collectionId}/items?bbox=Lon,Lat,Lon,Lat`.
   * In _OGC API - Coverages_, map coordinates should be transformed to native coordinates and use `/collections/{collectionId}/coverage?bbox=x,y,x,y` or the equivalent "subset" query.
-  * In _OGC API - EDR_, map coordinates should be transformed to a CRS coordinates and use `/collections/{collectionId}/position?coords=POINT(x y)` or by adding a radius query `/collections/{collectionId}/radius?coords=POINT(x y)&within=20&within-units=km`.
+  * In _OGC API - EDR_, map coordinates should be transformed to a CRS that the API supports `/collections/{collectionId}/position?coords=POINT(x y)` or by adding a radius query `/collections/{collectionId}/radius?coords=POINT(x y)&within=20&within-units=km`.
 
 The use of _OGC API - Tiles_ and serving vector tiled content directly also makes creating visualizations with query capabilities directly on the client side possible. Since tiled vector data can contain features, their attributes can be presented to the user when clicked, and a different style can be applied to highlight that selected feature.
 

core/standard/clause_22_map_dataEncodings.adoc

@@ -2,17 +2,17 @@
 == Requirements classes for encodings
 
 The _OGC API - Maps_ Standard is designed to support mapped data that can potentially be encoded and provided in existing geospatial formats or new formats that could be developed in the future.
-Web API deployments may adopt these encodings and declare conformance to them in the list of conformance classes supported by the Web API. 
-The requirements in this section do not limit the number of encodings offered by a Maps Web API deployment.
+Web API deployments may adopt these encodings and declare conformance to them in the list of conformance classes supported by the API. 
+The requirements in this section do not limit the number of encodings offered by a Maps API deployment.
 The intent is to provide a minimum set of encodings that could be implemented by any deployed Maps APIs as well as to provide a practical way to test conformance to this Standard.
-For each of these encodings, a requirements class is defined. A Web API implementing OGC API – Maps classes are free to support other encodings and data formats.
-These other formats may be more convenient for given use cases even though they may not be listed as supported conformance classes by the Web API deployment.
-In addition, the declaration of an encoding in the conformance classes supported does not mean that all the resources provided by an OGC enabled API endpoint should support all of them.
+For each of these encodings, a requirements class is defined. An API implementing OGC API – Maps classes is free to support other encodings and data formats.
+These other formats may be more convenient for given use cases even though they may not be listed as supported conformance classes by the API.
+In addition, the declaration of an encoding in the supported conformance classes does not mean that all the resources provided by an implementation of an OGC API Standard should support all of them.
 Partial support could be conditioned by the nature of the data behind each collection.
 
 === Overview
 
-Six requirements classes for encodings map responses of _OGC API - Maps_ implementation are defined:
+Six requirements classes for map responses of _OGC API - Maps_ implementations supporting various encodings are defined:
 
 * <<rc_png,PNG>>
 * <<rc_jpeg,JPEG>>
@@ -50,8 +50,7 @@ include::requirements/format_jpeg/REQ_content.adoc[]
 [[rc_jpegxl]]
 === Requirements Class "JPEG XL"
 
-https://jpeg.org/jpegxl/[JPEG XL] is a relatively newer image format (compared to PNG and JPEG) with support for both lossy and lossless compression, alpha channels, high bit depths, high image quality, high compression ratio as well as high performance encoding and decoding.
-The format and codec are unencumbered of any patent. Free and open source libraries are available to read and write the format such as https://github.com/libjxl/libjxl[libjxl], released under a 3-clause BSD license.
+https://jpeg.org/jpegxl/[JPEG XL] is a relatively newer image format (compared to PNG and JPEG) with support for both lossy and lossless compression, alpha channels, high bit depths, high image quality, high compression ratio as well as high performance encoding and decoding. Free and open source libraries are available to read and write the format such as https://github.com/libjxl/libjxl[libjxl], released under a 3-clause BSD license.
 Although JPEG XL is not yet widely supported in web browsers at the time of writing this document, this situation is likely to change, and this requirements class is included due to the numerous advantages of JPEG XL
 over the traditional JPEG and PNG encoding, such as avoiding the need for compromising between high compression ratio, image quality and translucency.
 JPEG XL is defined by the multi-part ISO standard Information technology JPEG XL - image coding system, including https://www.iso.org/standard/77977.html[ISO/IEC 18181-1:2022 Part 1: Core coding system] and
@@ -63,7 +62,7 @@ include::requirements/format_jpegxl/REQ_content.adoc[]
 
 [[rc_tiff]]
 === Requirements Class "TIFF"
-One use case for maps is to distribute coverage values as regular grids. In these circumstances, selecting an encoding able to store grid values in their original format and eventually compress them using lossless compression is the right solution. The TIFF format is one of the older formats but is still one of the most popular formats to preserve arrays of data values and defined by the Adobe Systems TIFF v6 specification.
+One use case for maps is to distribute coverage values as regular grids. In these circumstances, selecting an encoding able to store grid values in their original format and eventually compress them using lossless compression is the right solution. The TIFF format is one of the older formats but is still one of the most popular formats to preserve arrays of data values and is defined by the Adobe Systems TIFF v6 specification.
 
 TIFF is a flexible, adaptable file format for handling images and data. The ability to store data in a lossless format makes a TIFF file a useful image archive: Unlike standard JPEG files, a TIFF file using lossless compression such as PackBits or LZW compression.
 
@@ -87,7 +86,7 @@ include::recommendations/format_svg/PER_overflow.adoc[]
 [[rc_html]]
 === Requirements Class "HTML"
 
-Returning a HTML page with a full, operational map browser that allows for interactive navigation over the map (e.g., zoom and pan) is convenient for easy exploration of the data or for testing purposes.
+Returning an HTML page with a full, operational map browser that allows for interactive navigation over the map (e.g., zoom and pan) is convenient for easy exploration of the data or for testing purposes.
 
 include::requirements/requirements_class_format_html.adoc[]
 

core/standard/clause_23_map_apiOperations.adoc

@@ -7,7 +7,7 @@ include::requirements/requirements_class_api_operations.adoc[]
 
 The "API Operations" requirements class defines requirements for providing a definition of a Web API implementing the Maps API Standard using an API definition language.
 This requirements class is intended to be combined with another requirements class specifying requirements for providing an API definition in a particular API definition language and / or version,
-such as the Open API 3.0 requirements class defined in https://docs.ogc.org/is/19-072/19-072.html#_ab6e3c2d-d2dc-4f01-a7d4-8b52133289a0[OGC API - Common - Part 1 :Core], or another eventual requirements class
+such as the OpenAPI 3.0 requirements class defined in https://docs.ogc.org/is/19-072/19-072.html#_ab6e3c2d-d2dc-4f01-a7d4-8b52133289a0[OGC API - Common - Part 1 :Core], or another eventual requirements class
 for OpenAPI 3.1.
 
 === Web API description
@@ -21,18 +21,18 @@ This requirements class depends on the _OGC API - Common_ landing page requireme
 ==== Response
 
 ===== Completeness
-The API definition resulting as a response to this request need to take into consideration the relevant resources specified in the Maps API Standard.
+The API definition resulting as a response to this request needs to take into consideration the relevant resources specified in the Maps API Standard.
 
 include::requirements/api-operations/REQ_completeness.adoc[]
 
 ===== Reusable API components
 
-Reusable components for creating API definitions for implementations of this OGC API - Maps using OpenAPI 3.0 can be found in https://schemas.opengis.net/ogcapi/maps/part1/1.0/openapi .
+Reusable components for creating API definitions for implementations of this OGC API - Maps Standard using OpenAPI 3.0 can be found in https://schemas.opengis.net/ogcapi/maps/part1/1.0/openapi .
+
 
-NOTE: While this specification is in draft status, the components are available from https://github.com/opengeospatial/ogcapi-maps/tree/master/openapi .
 
 A server implementation of the _OGC API – Maps Standard_ can use the content in the openapi directory to generate a response for the API description using OpenAPI 3.0.
-The _ogcapi-maps-1.yaml_ includes paths and components. An implementation should only include the paths that are implemented and remove the references to the paths that are not implemented.
+The _ogcapi-maps-1.yaml_ file includes paths and components. An implementation should only include the paths that are implemented and remove the references to the paths that are not implemented.
 The components part includes parameters, responses and schemas that can be reused as-is. The `api` directory contains JSON files that are templates with enumerated values for collections, styles and tile matrix sets.
 A particular implementation of the Maps API should enumerate the actual resources exposed by the API deployment in the same way.
 The server can select to dynamically implement responses to /api/* (where * is replaced by all-collections, styles,... ) or hardcode the /api/* files with the actual list of resource identifiers in the enumerations.
@@ -47,7 +47,7 @@ The API description of each path provides a description of what parameters to us
 However, the Maps API Standard does not propose a fixed set of paths so there is an issue identifying the requirements classes pertaining to each path in an API instance.
 In other words, the API description alone does not provide enough information by itself.
 Therefore, there is a need to associate the resource paths in the API definition with the resources defined in the various requirements classes.
-The Maps APIs Standard proposes a suffix mechanism to be applied to the operation identifiers of the path (e.g., the `operationId` property in OpenAPI Specification 3.0) to list the requirements classes pertaining to each path.
+The Maps API Standard proposes a suffix mechanism to be applied to the operation identifiers of the path (e.g., the `operationId` property in OpenAPI Specification 3.0) to list the requirements classes pertaining to each path.
 Each path should have a unique operationId suffix, so it is expected that the API instance provides a prefix to the proposed suffixes that make each operation identifier unique.
 
 include::requirements/api-operations/REQ_operation-id.adoc[]