Merge pull request #27 from opengeospatial/processes

Harmonization with OGC API Processes

api/standard/21-000.adoc

@@ -93,11 +93,9 @@ include::clause_6_overview.adoc[]
 
 include::clause_7_api.adoc[]
 
-include::clause_8_ogcapi_processes.adoc[]
+include::clause_8_media_types.adoc[]
 
-include::clause_9_media_types.adoc[]
-
-include::clause_10_security_considerations.adoc[]
+include::clause_9_security_considerations.adoc[]
 
 <<<
 ////

api/standard/clause_5_conventions.adoc

@@ -50,3 +50,10 @@ In the case above, the following changes to the pre-defined OpenAPI component ar
 * If the server supports an XML encoding, `xml` properties may be added to the relevant OpenAPI schema components.
 
 For API definitions that do not conform to the OpenAPI Specification 3.0, the normative statement should be interpreted in the context of the API definition language used.
+
+=== Alignment with OGC API - Processes
+
+The computation of a route is a process that operates on geospatial data typically including a routing network. This document specifies the OGC API building blocks for Routes as API resources. An alternate implementation option for a Routing API is to implement routing as a process using the building blocks specified in the OGC API Processes standard. Both building blocks have been aligned so that the same route definition can be sent to both API options. The alignment between the two OGC API standards is mostly transparent to developers, except for two extensions to the Route Definition object that is submitted in a POST request to the Routes resource (path `/routes`) that would not be necessary for the Routes API:
+
+* an extra "inputs" member that contains the route definition object;
+* extra "value" members in the waypoints, obstacles and temporal constraints objects.

api/standard/clause_7_api.adoc

@@ -219,30 +219,37 @@ properties:
       waypoints:
         type: object
         required:
-          - type
-          - coordinates
+          - value
         properties:
-          type:
-            type: string
-            enum:
-              - MultiPoint
-          coordinates:
-            type: array
-            minItems: 2
-            maxItems: 2
-            items:
-              title: Points along the route
-              type: array
-              minItems: 2
-              items:
-                type: number
+          value:
+            type: object
+            required:
+              - type
+              - coordinates
+            properties:
+              type:
+                type: string
+                enum:
+                  - MultiPoint
+              coordinates:
+                type: array
+                minItems: 2
+                maxItems: 2
+                items:
+                  title: Points along the route
+                  type: array
+                  minItems: 2
+                  items:
+                    type: number
       preference:
         type: string
 ----
 ^|C |The schema of the `preference` member SHALL be extended with `enum` and `default` values to declare the cost functions supported by the server.
 |===
 
-Note that additional members in the route definition can be ignored.
+Additional members in the route definition can be ignored.
+
+NOTE: The content model of the route definition object has been designed so that it can be a valid request to an process execution request according to OGC API - Processes. This adds additional members "inputs" and "value" that would otherwise be unnecessary.
 
 [[req_core_conformance-values]]
 [width="90%",cols="2,6a"]
@@ -312,21 +319,25 @@ in Washington, D.C.
 [source,JSON]
 ----
 {
-  "name": "Reagan Airport to Capitol",
-  "waypoints": {
-    "type": "MultiPoint",
-    "coordinates": [
-      [
-        -77.037722,
-        38.851444
-      ],
-      [
-        -77.009003,
-        38.889931
-      ]
-    ]
-  },
-  "preference": "fastest"
+  "inputs": {
+    "name": "Reagan Airport to Capitol",
+    "waypoints": {
+      "value": {
+        "type": "MultiPoint",
+        "coordinates": [
+          [
+            -77.037722,
+            38.851444
+          ],
+          [
+            -77.009003,
+            38.889931
+          ]
+        ]
+      }
+    },
+    "preference": "fastest"
+  }
 }
 ----
 =================
@@ -1176,31 +1187,37 @@ One or more polygons describing areas the route should avoid.
 ^|*Requirement {counter:req-id}* |*/req/obstacles/input*
 ^|A |The server SHALL support a member with the name "obstacles"
 in the route definition in a HTTP POST request to the path `/routes`
-with the following schema (a GeoJSON MultiPolygon):
+with the following schema (a GeoJSON MultiPolygon, wrapped into a 
+"value" member):
 
 [source,YAML]
 ----
 type: object
 required:
-  - type
-  - coordinates
+  - value
 properties:
-  type:
-    type: string
-    enum:
-      - MultiPolygon
-  coordinates:
-    type: array
-    items:
-      type: array
-      items:
+  value:
+    type: object
+    required:
+      - type
+      - coordinates
+    properties:
+      type:
+        type: string
+        enum:
+          - MultiPolygon
+      coordinates:
         type: array
-        minItems: 4
         items:
           type: array
-          minItems: 2
           items:
-            type: number
+            type: array
+            minItems: 4
+            items:
+              type: array
+              minItems: 2
+              items:
+                type: number
 ----
 |===
 
@@ -1238,18 +1255,23 @@ with the following schema:
 ----
 type: object
 required:
-  - timestamp
+  - value
 properties:
-  timestamp:
-    type: string
-    format: date-time
-    example: "2019-05-23T19:06:32Z"
-  type:
-    type: string
-    default: departure
-    enum:
-      - departure
-      - arrival
+  value:
+    type: object
+    required:
+      - timestamp
+    properties:
+      timestamp:
+        type: string
+        format: date-time
+        example: "2019-05-23T19:06:32Z"
+      type:
+        type: string
+        default: departure
+        enum:
+          - departure
+          - arrival
 ----
 |===