Merge pull request #405 from pvretano/issue-402

Update definition of the f, prefer and {bbox-input-name}-crs parameters to minimize name collisions.
opengeospatial · Jul 22, 2024 · b972e74 · b972e74
2 parents f24f505 + 78af833
commit b972e74
Show file tree

Hide file tree

Showing 12 changed files with 63 additions and 50 deletions.
diff --git a/core/requirements/core/REQ_process-summary-links.adoc b/core/requirements/core/REQ_process-summary-links.adoc
@@ -4,7 +4,6 @@
 [%metadata]
 identifier:: /req/core/process-summary-links
 
-
 [.component,class=part]
 --
 Each process summary SHALL include a link (relation: `self`) that points to the full description of the process (path: `/processes/{processID}`).
@@ -14,5 +13,4 @@ Each process summary SHALL include a link (relation: `self`) that points to the
 --
 Each process summary SHALL include one or more links (relation: `alternate`) that points to each alternative representation of the full description of the process (path: `/processes/{processID}`).
 --
-
 ====
diff --git a/core/requirements/kvp-execute/REQ_bbox-crs-input-value.adoc b/core/requirements/kvp-execute/REQ_bbox-crs-input-value.adoc
@@ -12,13 +12,13 @@ identifier:: /req/kvp-execute/bbox-crs-input-value
 
 [.component,class=part]
 --
-A bbox-crs input parameter SHALL have the following characteristics:
+A `{bbox-input-name}` input parameter SHALL have the following characteristics:
 
 [source,yaml]
 ----
-include::../../../openapi/parameters/common-crs/bbox-crs.yaml[]
+include::../../../openapi/parameters/processes-core/bbox-crs.yaml[]
 ----
 
-where the token `{bbox-input-name}` represents the identifier of a bbox input parameter and the token  `{bbox-input-name}-crs` represents the identifier of a corresponding input that indicates which CRS is being used for the coordinates of the `{bbox-input-name}` parameter.
+where the token `{bbox-input-name}` represents the identifier of a bbox input parameter and the token  `{bbox-input-name}[crs]` represents the identifier of a corresponding input that indicates which CRS is being used for the coordinates of the `{bbox-input-name}` parameter.
 --
 ====
diff --git a/core/requirements/kvp-execute/REQ_f-definition.adoc b/core/requirements/kvp-execute/REQ_f-definition.adoc
@@ -2,17 +2,22 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/kvp-execute/f-definition*
-^|A |The operation SHALL support a parameter `f` with the following characteristics:
+^|A |The operation SHALL support a response parameter `response[f]` with the following characteristics:
 
 [source,YAML]
 ----
-name: f
+name: response
 in: query
 required: false
 schema:
-  type: string
-  format: uri
-style: form
-explode: false
+  type: object
+  required:
+    - f
+  properties:
+    f:
+      type: string
+      format: uri
+style: deepObject
+explode: true
 ----
 |===
diff --git a/core/requirements/kvp-execute/REQ_f-response.adoc b/core/requirements/kvp-execute/REQ_f-response.adoc
@@ -2,5 +2,5 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/kvp-execute/f-response*
-^|A |The `f` parameter SHALL behave in the same way that the https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.2[HTTP `Accept` header] behaves.
+^|A |The `response[f]` parameter SHALL behave in the same way that the https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.2[HTTP `Accept` header] behaves.
 |===
diff --git a/core/requirements/kvp-execute/REQ_prefer-definition.adoc b/core/requirements/kvp-execute/REQ_prefer-definition.adoc
@@ -2,17 +2,22 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/kvp-execute/prefer-definition*
-^|A |The operation SHALL support a parameter `prefer` with the following characteristics:
+^|A |The operation SHALL support a parameter `response[prefer]` with the following characteristics:
 
 [source,YAML]
 ----
-name: prefer
+name: response
 in: query
 required: false
 schema:
-  type: string
-  format: uri
-style: form
-explode: false
+  type: object
+  required:
+    - prefer
+  properties:
+    prefer:
+      type: string
+      format: uri
+style: deepObject
+explode: true
 ----
 |===
diff --git a/core/requirements/kvp-execute/REQ_prefer-response.adoc b/core/requirements/kvp-execute/REQ_prefer-response.adoc
@@ -2,5 +2,5 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/kvp-execute/f-response*
-^|A |The `prefer` parameter SHALL behave in the same way that the https://datatracker.ietf.org/doc/html/rfc7240[HTTP `Prefer` header] behaves.
+^|A |The `response[prefer]` parameter SHALL behave in the same way that the https://datatracker.ietf.org/doc/html/rfc7240[HTTP `Prefer` header] behaves.
 |===
diff --git a/core/sections/clause_15_kvp-execute.adoc b/core/sections/clause_15_kvp-execute.adoc
@@ -77,7 +77,7 @@ inputImage=s3://mybucker/myInputImage.tif&
 bbox=5.8,47.2,15.1,55.1&
 datetime=2019-08-09&
 output=image&
-f=image%2Fjpeg%3B%20q%3D0.5%2Cimage%2Fpng%20q%3D0.8
+response[f]=image%2Fjpeg%3B%20q%3D0.5%2Cimage%2Fpng%20q%3D0.8
 ----
 ====
 
@@ -89,7 +89,7 @@ include::../requirements/kvp-execute/REQ_prefer-response.adoc[]
 
 .Asynchronous execution.
 ====
-In this example, the `prefer` parameter is used to indicate that asynchronous execution is preferred.
+In this example, the `response[prefer]` parameter is used to indicate that asynchronous execution is preferred.
 
 [source]
 ----
@@ -98,8 +98,8 @@ inputImage=s3://mybucker/myInputImage.tif&
 bbox=5.8,47.2,15.1,55.1&
 datetime=2019-08-09&
 output=image&
-f=image%2Fjpeg%3B%20q%3D0.5%2Cimage%2Fpng%20q%3D0.8&
-prefer=handling%3Dlenient%2C%20wait%3D100%2C%20respond-async
+response[f]=image%2Fjpeg%3B%20q%3D0.5%2Cimage%2Fpng%20q%3D0.8&
+response[prefer]=handling%3Dlenient%2C%20wait%3D100%2C%20respond-async
 ----
 ====
 
@@ -414,11 +414,11 @@ An example instance value for a bounding box input named `my_bbox` might be:
 my_bbox=-79.63732855116733,43.570691463538644,-79.10227279076784,43.86582298161152
 ----
 
-This is the same example as above but in a different CRS.  An input parameter named `my_bbox-crs` is used to convey the CRS of the `my_bbox` parameter.
+This is the same example as above but in a different CRS.  An input parameter named `my_bbox[crs]` is used to convey the CRS of the `my_bbox` parameter.
 
 [source]
 ----
-my_bbox=43.570691463538644,-79.63732855116733,43.86582298161152,-79.10227279076784&my_bbox-crs=https://www.opengis.net/def/crs/EPSG/0/4326
+my_bbox=43.570691463538644,-79.63732855116733,43.86582298161152,-79.10227279076784&my_bbox[crs]=https://www.opengis.net/def/crs/EPSG/0/4326
 ----
 
 ====

diff --git a/openapi/parameters/common-crs/bbox-crs.yaml b/openapi/parameters/common-crs/bbox-crs.yaml
diff --git a/openapi/parameters/common-geodata/bbox.yaml b/openapi/parameters/common-geodata/bbox.yaml
@@ -1,4 +1,4 @@
-name: {bbox-parameter-name}
+name: {bbox-input-name}
 in: query
 description: |-
   Only features that have a geometry that intersects the bounding box are selected.

diff --git a/openapi/parameters/processes-core/bbox-crs.yaml b/openapi/parameters/processes-core/bbox-crs.yaml
@@ -0,0 +1,18 @@
+name: inputsCrs
+description: |-
+  Asserts the CRS used for the coordinate values of a bounding
+  box input parameter. The name `inputsCrs` is just a generic
+  name to avoid ambiguity.  It is ignored since explode is set
+  to true.
+in: query
+description: |-
+  Asserts the CRS used for the coordinate values of a bounding
+  box input parameter. 
+required: false
+schema: 
+  type: object
+  patternProperties:
+    "^.+[crs]$":
+      $ref: "../../schemas/processes-core/bbox-def-crs.yaml"
+explode: true
+style: form
diff --git a/openapi/schemas/processes-core/bbox-def-crs.yaml b/openapi/schemas/processes-core/bbox-def-crs.yaml
@@ -0,0 +1,10 @@
+anyOf:
+  - type: string
+    format: uri
+    enum:
+      - "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+      - "http://www.opengis.net/def/crs/OGC/0/CRS84h"
+    default: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+  - type: string
+    format: uri
+    default: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
diff --git a/openapi/schemas/processes-core/bbox.yaml b/openapi/schemas/processes-core/bbox.yaml
@@ -12,13 +12,4 @@ properties:
     items:
       type: number
   crs:
-    anyOf:
-      - type: string
-        format: uri
-        enum:
-          - "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
-          - "http://www.opengis.net/def/crs/OGC/0/CRS84h"
-      - type: string
-        format: uri
-    default: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
-additionalProperties: false
+    $ref: "bbox-def-crs.yaml"