decorations req. class added in response to issue #97

core/standard/20-058.adoc

@@ -98,6 +98,8 @@ include::clause_7_map_core.adoc[]
 
 include::clause_7a_map_background.adoc[]
 
+include::clause_7b_map_decorations.adoc[]
+
 include::clause_8_map_tilesetsList.adoc[]
 
 include::clause_9_map_paramCollectionsSelection.adoc[]

core/standard/clause_2_conformance.adoc

@@ -47,6 +47,18 @@ The _maps background_ conformance class allows requesting a particular backgroun
 |Map |`/map?bgcolor={bgcolor}&transparent={transparent},...`
 |===
 
+*<<rc_decorations>>* (http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/decorations)
+
+The _maps decorations_ conformance class allows adding a title, a legend, a scale bar, a compass, a situation map,  an attribution text a lat/long graticule, and a CRS grid directly on top of a map.
+
+[#table_resource_decorations,reftext='{table-caption} {counter:table-num}']
+.Overview of resource and common direct links that corresponds to the decorations
+[cols="33,66",options="header"]
+|===
+|Resource name |Example of possible paths
+|Map |`/map?map-title={map-title}&legend={legend}&scale-bar={scale-bar}&compass={compass}&situation-map={situation-map}&graticule={graticule}&crs-grid={crs-grid}&attribution=attribution...`
+|===
+
 *<<rc_collections-selection>>* (http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/collections-selection)
 
 The _maps geodata selection_ conformance class allows to list specific geospatial data resources from which to retrieve maps.

core/standard/clause_7b_map_decorations.adoc

@@ -0,0 +1,52 @@
+[[rc_decorations]]
+== Requirement Class "Map Decorations"
+
+=== Overview
+
+[[background-overview]]
+
+include::requirements/requirements_class_decorations.adoc[]
+
+This requirement class describes parameters to add a title, a legend, a scale bar, a compass, a situation map, an attribution text or logo, a lat/long graticule, and a CRS grid to the map.
+
+NOTE: The work "element" or "parts" normally designates the previous enumerations. However "element" is used in many other contexts so the authors decided to call the "decorations" in this section.
+
+Many of these decorations can be better generated by the client that shows the map, so these parameters are reserved to create maps that are going to be used as static illustrations (e.g. as images in web pages). If the map is going to be presented alone as an illustration, these decorations could be make the map more informative and more "cartographic" (see for example https://reference.yourdictionary.com/resources/5-basic-parts-of-any-map.html). When a map is going to be presented overlaid with other maps these elements may interfere and collide, impeding the correct visualization or the result and are not recommended.
+
+=== Map operation
+
+The map core of this standard defines how to get a map. This requirements class specifies parameters to add some decorations on top of it
+
+==== Parameters for map decorations
+The title, legend, scale-bar, compass, situation-map, attribution, graticule and crs-grid,  parameters indicate if and where the decorations elements will be situated on top of the map.
+
+include::requirements/decorations/REQ_title-definition.adoc[]
+
+NOTE: The style and size of the text of the title is at complete discretion of the server
+
+include::requirements/decorations/REQ_legend-definition.adoc[]
+
+include::requirements/decorations/REQ_scale-bar-definition.adoc[]
+
+include::requirements/decorations/REQ_compass-definition.adoc[]
+
+NOTE: It is up to de server to decide how the compass can look like being some possibilities a full wind rose or a simple arrow to the north.
+
+include::requirements/decorations/REQ_situation-map-definition.adoc[]
+
+include::requirements/decorations/REQ_attribution-definition.adoc[]
+
+NOTE: The attribution may be represented as a text naming the responsible party of the data represented in the map or a logo of the responsible party organzation.
+
+REQ_include::requirements/decorations/graticule-definition.adoc[]
+
+NOTE: A graticule is a network of lines on a map that delineate the geographic expressed as lines of equal latitude or longitude (a.k.a. meridians and parallels). A graticule added to a map in a lat/long CRS (such as CRS:84) will appear as a set of vertical and horizontal strait lines. In other CRSs, meridians a parallels may result in curbed lines.
+
+include::requirements/decorations/REQ_crs-grid-definition.adoc[]
+
+NOTE: A CRS grid is a network of lines on a map that delineate the CRS coordinates expressed as lines of equal X or Y. A CRS grid added results in a set of vertical and horizontal strait lines.
+
+==== Response
+A successful GET response is described in the core class (http://www.opengis.net/spec/ogcapi-maps-1/1.0/conf/core)
+
+include::requirements/decorations/REQ_map-success.adoc[]

core/standard/requirements/decorations/REQ_attribution-definition.adoc

@@ -0,0 +1,27 @@
+[[req_decorations_attribution-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/attribution-definition*
+^|A |The map operation SHALL support an optional parameter `attribution` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: attribution
+   in: query
+   description: Add a attribution into the map
+   style: form
+   schema:
+     type: string
+      enum:
+        - none
+        - topLeft
+        - topCenter
+        - topRight
+        - middleLeft
+        - middleRight
+        - bottomLeft
+        - bottomCenter
+        - bottomRight
+      default: none
+----
+^|B |The absence of the parameter `attribution` or the value `none` SHALL be interpreted as "no attribution in the map". Other values SHALL be interpreted as the position where the attribution should appear
+|===

core/standard/requirements/decorations/REQ_compass-definition.adoc

@@ -0,0 +1,27 @@
+[[req_decorations_compass-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/compass-definition*
+^|A |The map operation SHALL support an optional parameter `compass` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: compass
+   in: query
+   description: Add a compass into the map
+   style: form
+   schema:
+     type: string
+      enum:
+        - none
+        - topLeft
+        - topCenter
+        - topRight
+        - middleLeft
+        - middleRight
+        - bottomLeft
+        - bottomCenter
+        - bottomRight
+      default: none
+----
+^|B |The absence of the parameter `compass` or the value `none` SHALL be interpreted as "no compass in the map". Other values SHALL be interpreted as the position where the compass should appear
+|===

core/standard/requirements/decorations/REQ_crs-grid-definition.adoc

@@ -0,0 +1,17 @@
+[[req_decorations_crs-grid-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/crs-grid-definition*
+^|A |The map operation SHALL support an optional parameter `crs-grid` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: crs-grid
+   in: query
+   description: Add a crs-grid into the map
+   style: form
+   schema:
+      type: boolean
+      default: false
+----
+^|B |The absence of the parameter `crs-grid` or the value `false` SHALL be interpreted as "no CRS grid in the map".
+|===

core/standard/requirements/decorations/REQ_graticule-definition.adoc

@@ -0,0 +1,17 @@
+[[req_decorations_graticule-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/graticule-definition*
+^|A |The map operation SHALL support an optional parameter `graticule` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: graticule
+   in: query
+   description: Add a graticule into the map
+   style: form
+   schema:
+      type: boolean
+      default: false
+----
+^|B |The absence of the parameter `graticule` or the value `false` SHALL be interpreted as "no graticule in the map".
+|===

core/standard/requirements/decorations/REQ_legend-definition.adoc

@@ -0,0 +1,27 @@
+[[req_decorations_legend-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/legend-definition*
+^|A |The map operation SHALL support an optional parameter `legend` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: legend
+   in: query
+   description: Add a legend into the map
+   style: form
+   schema:
+     type: string
+      enum:
+        - none
+        - topLeft
+        - topCenter
+        - topRight
+        - middleLeft
+        - middleRight
+        - bottomLeft
+        - bottomCenter
+        - bottomRight
+      default: none
+----
+^|B |The absence of the parameter `legend` or the value `none` SHALL be interpreted as "no legend in the map". Other values SHALL be interpreted as the position where the legend should appear
+|===

core/standard/requirements/decorations/REQ_map-success.adoc

@@ -0,0 +1,6 @@
+[[req_decorations_map-success]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/map-success*
+^|A |In the case of raster image media type (e.g. image/jpeg or image/png) the number of columns and rows SHALL be exactly the ones specified in the `width` and `height` parameters respectively.
+|===

core/standard/requirements/decorations/REQ_map-title-definition.adoc

@@ -0,0 +1,27 @@
+[[req_decorations_map-title-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/map-title-definition*
+^|A |The map operation SHALL support an optional parameter `map-title` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: map-title
+   in: query
+   description:  a title into the map
+   style: form
+   schema:
+     type: string
+      enum:
+        - none
+        - topLeft
+        - topCenter
+        - topRight
+        - middleLeft
+        - middleRight
+        - bottomLeft
+        - bottomCenter
+        - bottomRight
+      default: none
+----
+^|B |The absence of the parameter `map-title` or the value `none` SHALL be interpreted as "no title in the map". Other values SHALL be interpreted as the position where the title should appear
+|===

core/standard/requirements/decorations/REQ_scale-bar-definition.adoc

@@ -0,0 +1,27 @@
+[[req_decorations_scale-bar-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/scale-bar-definition*
+^|A |The map operation SHALL support an optional parameter `scale-bar` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: scale-bar
+   in: query
+   description: Add a scale bar into the map
+   style: form
+   schema:
+     type: string
+      enum:
+        - none
+        - topLeft
+        - topCenter
+        - topRight
+        - middleLeft
+        - middleRight
+        - bottomLeft
+        - bottomCenter
+        - bottomRight
+      default: none
+----
+^|B |The absence of the parameter `scale-bar` or the value `none` SHALL be interpreted as "no scale bar in the map". Other values SHALL be interpreted as the position where the scale bar should appear
+|===

core/standard/requirements/decorations/REQ_situation-map-definition.adoc

@@ -0,0 +1,27 @@
+[[req_decorations_situation-map-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/decorations/situation-map-definition*
+^|A |The map operation SHALL support an optional parameter `situation-map` with the characteristics defined in the OpenAPI Specification 3.0 fragment
+[source,YAML]
+----
+  name: situation-map
+   in: query
+   description: Add a situation-map into the map
+   style: form
+   schema:
+     type: string
+      enum:
+        - none
+        - topLeft
+        - topCenter
+        - topRight
+        - middleLeft
+        - middleRight
+        - bottomLeft
+        - bottomCenter
+        - bottomRight
+      default: none
+----
+^|B |The absence of the parameter `situation-map` or the value `none` SHALL be interpreted as "no situation map is required in the map". Other values SHALL be interpreted as the position where the situation map should appear
+|===

core/standard/requirements/requirements_class_decorations.adoc

@@ -0,0 +1,8 @@
+[[rc_maps-decorations]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Class Decorations*
+2+|http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/decorations
+|Target type |Web API
+|Dependency |http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/core
+|===

core/standard/requirements/scaling/REQ_cell-size-definition.adoc

@@ -12,7 +12,6 @@
       cell size of the viewport to present the response in millimeters.
     required: false
     style: form
-    explode: false
     schema:
       type: number
 ----

core/standard/requirements/scaling/REQ_height-definition.adoc

@@ -12,7 +12,6 @@
       Height of the viewport to present the response in pixel units (the map subset).
     required: false
     style: form
-    explode: false
     schema:
       type: number
 ----

core/standard/requirements/scaling/REQ_map-success.adoc

@@ -2,5 +2,5 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/scaling/map-success*
-^|A |In the case of raster image media type (e.g. image/jpeg or image/png) the number of columns and rows SHALL be exactly the ones specified in the `width` and `height` parameters respectively.
+^|A |The map SHALL include the decorations requested and in the requested position.
 |===

core/standard/requirements/scaling/REQ_width-definition.adoc

@@ -12,7 +12,6 @@
       Width of the viewport to present the response in pixel units (the map subset).
     required: false
     style: form
-    explode: false
     schema:
       type: number
 ----