Merge pull request #378 from pvretano/issue-373

Initial checkin to resolve issue 373.
opengeospatial · Mar 4, 2024 · 1788f27 · 1788f27
2 parents 3eb6764 + ea8d316
commit 1788f27
Show file tree

Hide file tree

Showing 8 changed files with 196 additions and 82 deletions.
diff --git a/core/examples/json/ConfClasses.json b/core/examples/json/ConfClasses.json
@@ -1,8 +1,8 @@
 {
-	"conformsTo": [
-		"http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core",
-		"http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/json",
-		"http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/html",
-		"http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/oas30"
-	]
-}
+  "conformsTo": [
+    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core",
+    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/json",
+    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/html",
+    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/oas30"
+  ]
+}
diff --git a/core/examples/json/LandingPage.json b/core/examples/json/LandingPage.json
@@ -1,42 +1,42 @@
 {
-	"links": [{
-		"href": "http://processing.example.org/oapi-p?f=application/json",
-		"rel": "self",
-		"type": "application/json",
-		"title": "This document"
-	},{
-		"href": "http://processing.example.org/oapi-p?f=text/html",
-		"rel": "alternate",
-		"type": "text/html",
-		"title": "This document as HTML"
-	},
-	{
-		"href": "http://processing.example.org/oapi-p/api?f=application/json",
-		"rel": "service-desc",
-		"type": "application/json",
-		"title": "API definition for this endpoint as JSON"
-	},
-	{
-		"href": "http://processing.example.org/oapi-p/api?f=text/html",
-		"rel": "service-desc",
-		"type": "text/html",
-		"title": "API definition for this endpoint as HTML"
-	},
-	{
-		"href": "http://processing.example.org/oapi-p/conformance",
-		"rel": "http://www.opengis.net/def/rel/ogc/1.0/conformance",
-		"type": "application/json",
-		"title": "OGC API - Processes conformance classes implemented by this server"
-	},
-	{
-		"href": "http://processing.example.org/oapi-p/processes",
-		"rel": "http://www.opengis.net/def/rel/ogc/1.0/processes",
-		"type": "application/json",
-		"title": "Metadata about the processes"
-	},
-	{
-		"href": "http://processing.example.org/oapi-p/jobs",
-		"rel": "http://www.opengis.net/def/rel/ogc/1.0/job-list",
-		"title": "The endpoint for job monitoring"
-	}]
+  "links": [{
+    "href": "http://processing.example.org/oapi-p?f=application/json",
+    "rel": "self",
+    "type": "application/json",
+    "title": "This document"
+  },{
+    "href": "http://processing.example.org/oapi-p?f=text/html",
+    "rel": "alternate",
+    "type": "text/html",
+    "title": "This document as HTML"
+  },
+  {
+    "href": "http://processing.example.org/oapi-p/api?f=application/json",
+    "rel": "service-desc",
+    "type": "application/json",
+    "title": "API definition for this endpoint as JSON"
+  },
+  {
+    "href": "http://processing.example.org/oapi-p/api?f=text/html",
+    "rel": "service-desc",
+    "type": "text/html",
+    "title": "API definition for this endpoint as HTML"
+  },
+  {
+    "href": "http://processing.example.org/oapi-p/conformance",
+    "rel": "http://www.opengis.net/def/rel/ogc/1.0/conformance",
+    "type": "application/json",
+    "title": "OGC API - Processes conformance classes implemented by this server"
+  },
+  {
+    "href": "http://processing.example.org/oapi-p/processes",
+    "rel": "http://www.opengis.net/def/rel/ogc/1.0/processes",
+    "type": "application/json",
+    "title": "Metadata about the processes"
+  },
+  {
+    "href": "http://processing.example.org/oapi-p/jobs",
+    "rel": "http://www.opengis.net/def/rel/ogc/1.0/job-list",
+    "title": "The endpoint for job monitoring"
+  }]
 }
diff --git a/core/examples/json/ProcessDescription.json b/core/examples/json/ProcessDescription.json
@@ -7,10 +7,6 @@
     "async-execute",
     "sync-execute"
   ],
-  "outputTransmission": [
-    "value",
-    "reference"
-  ],
   "inputs": {
     "stringInput": {
       "title": "String Literal Input Example",
@@ -122,14 +118,7 @@
             "contentSchema": "http://schemas.opengis.net/gml/3.2.1/geometryBasic2d.xsd"
           },
           {
-            "allOf": [
-              {
-                "format": "geojson-geometry"
-              },
-              {
-                "$ref": "http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometryGeoJSON.yaml"
-              }
-            ]
+            "format": "geojson-geometry"
           }
         ]
       }
@@ -151,8 +140,8 @@
     "imagesInput": {
       "title": "Inline Images Value Input",
       "description": "This is an example of an image input.  In this case, the input is an array of up to 150 images that might, for example, be a set of tiles.  The oneOf[] conditional is used to indicate the acceptable image content types; GeoTIFF and JPEG 2000 in this case.  Each input image in the input array can be included inline in the execute request as a base64-encoded string or referenced using the link.yaml schema.  The use of a base64-encoded string is implied by the specification and does not need to be specified in the definition of the input.",
-      "minOccurs": 1,
-      "maxOccurs": 150,
+	   "minOccurs": 1,
+	   "maxOccurs": 150,
       "schema": {
         "oneOf": [
           {

diff --git a/core/examples/json/ProcessList.json b/core/examples/json/ProcessList.json
@@ -1,17 +1,13 @@
 {
   "processes": [
     {
-	"id": "EchoProcess",
-	"title": "EchoProcess",
-	"version": "1.0.0",
+      "id": "EchoProcess",
+      "title": "EchoProcess",
+      "version": "1.0.0",
       "jobControlOptions": [
         "async-execute",
         "sync-execute"
       ],
-      "outputTransmission": [
-        "value",
-        "reference"
-      ],
       "links": [
         {
           "href": "https://processing.example.org/oapi-p/processes/EchoProcess",

diff --git a/core/requirements/ogc-process-description/REQ_inputs-def.adoc b/core/requirements/ogc-process-description/REQ_inputs-def.adoc
@@ -5,7 +5,7 @@
 identifier:: /req/ogc-process-description/inputs-def
 [.component,class=part]
 --
-Each process input definition SHALL be listed in the `inputs` section according to the JSON Schema: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/inputDescription.yaml[inputDescription.yaml].
+Each process <<process-input-schema,input definition>> SHALL be listed in the `inputs` section according to the JSON Schema: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/inputDescription.yaml[inputDescription.yaml].
 --
 
 [.component,class=part]

diff --git a/core/sections/clause_7_core.adoc b/core/sections/clause_7_core.adoc
@@ -487,12 +487,150 @@ NOTE: This schema can also be obtained from https://raw.githubusercontent.com/op
 [[sc_process_inputs]]
 ===== Process inputs
 
-*_Overview:_*
+====== Overview
 
 Each process input is a name/value pair that appears in the `inputs` section of
-an execute request.
+an execute request as show in the following example:
+
+```
+"inputs": {
+   "inputName1": <input value 1>,
+   "inputName2": <input value 2>,
+   etc.
+}
+```
+
+The actual name of each input is its identifier as specified by the input's definition in the <<sc_process_description,process description>>.
+
+====== Cardinality
+
+The cardinality on an input is specified using the `minOccurs` and `maxOccurs` parameters from the input's definition in the <<sc_process_description,process description>>.  The default values of `minOccurs` and `maxOccurs` are 1 indicating that a single input of the corresponding name must be specified in an execute request.  The following table covers the various combinations of `minOccurs` and `maxOccurs` values.
+
+[[cardinality_rules]]
+.Cardinality rules for process inputs.
+[cols="10,10,60,40",options="header"]
+|===
+|minOccurs |maxOccurs |Interpretation |Example
+|0 |0 |Not Allowed |
+|0 |1 |A single input value *may* be optionally specified. | "input": {value}
+|1 |1 |A single input value *must* be specified. | "input": {value}
+|1 |N |At least 1 input value *must* be specified.  +
+Regardless of the number of input values provided, those values *must* be encoded using an array. | "input": [{value}] OR +
+"input": [{value1},...,{valueN}]
+|M |N |All values provided *must* be encoded using an array. |"input": [{value1},...,{valueM}] OR +
+"input": [{value1},...,{valueM},...,{valueN}]
+|===
+
+NOTE: The tokens `{value}`, `{value1}`, `{valueN}` or `{valueM}` represent values of the type expected for the input according to its definition.  This can include array values.
+
+====== Interaction of `minOccurs`/`maxOccurs` and `minItems`/`maxItems`
+
+The `schema` member of the <<process-input-schema,input definition>> in the <<sc_process_description,process description>> defines the schema of a single instance of an input.  If the input happens to be an array then the `minItems` and `maxItems` properties may be used to define the limits of the array.  The use of `minItems` and `maxItems` in the definition of the input does not affect how `minOccurs` and `maxOccurs` are interpreted and the same <<cardinality_rules,cardinality rules>> apply.
+
+Consider the following definitions of an input named "input".
+
+[[schema_examples]]
+.Schema examples for cardinality
+[cols="50a,50a",options="header"]
+|===
+|Example Schema| Examples instances
+|
+[[row1-example]]
+[source,yaml]
+----
+inputs:
+  input:
+    schema:
+      type: array
+      maxItems: 2
+      items:
+        type: string
+----
+
+In this case the schema of an input value is defined as an array and so will always be encoded as an array in an execute request.
+|
+[source,JSON]
+----
+"input": ["value1"]
+----
+*or*
+[source,JSON]
+----
+"input": ["value1","value2"]
+----
+|
+[source,yaml]
+----
+inputs:
+  input:
+    maxOccurs: 2
+    schema:
+      type: string
+----
+
+In this case, the schema of the input is defined as a plain string with a cardinality of 2.  Inputs with cardinalities of greater than 1 are encoded as arrays in an execute request.  This situation is equivalently encoded to the <<row1-example,previous row>>. +
+Servers, however, being internally aware of the definition of each input, can disambiguate the input values accordingly (treating the values in this example as string values and the values in the <<row1-example,above example>> as arrays of values).
+|
+[source,JSON]
+----
+"input": ["value1"]
+----
+*or*
+[source,JSON]
+----
+"input": ["value1","value2"]
+----
+|
+[source,yaml]
+----
+inputs:
+  input:
+    maxOccurs: 2
+    schema:
+      type: array
+      maxItems: 2
+      items:
+        type: string
+----
+
+In this case we have an input with cardinality greater than 1 but that has values that themselves are defined as arrays.  Since inputs with cardinality greater than 1 are encoded as arrays in an execute request, the result is that the inputs are encoded as arrays of arrays.
+|
+[source,JSON]
+----
+"input": [["value1"]]
+----
+*or*
+[source,JSON]
+----
+"input": [["value1","value2"]]
+----
+*or*
+
+[source,JSON]
+----
+"input": [["value1"],["value2"]]
+----
+*or*
+
+[source,JSON]
+----
+"input": [["value1","value3"],["value2"]]
+----
+*or*
+
+[source,JSON]
+----
+"input": [["value1"],["value2","value3"]]
+----
+*or*
+
+[source,JSON]
+----
+"input": [["value1","value4"],["value2","value3"]]
+----
+|===
 
-The name of each input is its identifier as specified by the input's definition in the <<sc_process_description,process description>>.
+====== Input values 
 
 include::../requirements/core/REQ_process-execute-inputs.adoc[]
 

diff --git a/core/sections/clause_8_ogc-process-description.adoc b/core/sections/clause_8_ogc-process-description.adoc
@@ -137,14 +137,7 @@ The following JSON Schema fragment illustrates the use of the `format` key to in
         "contentSchema": "http://schemas.opengis.net/gml/3.2.1/geometryBasic2d.xsd"
       },
       {
-        "allOf": [
-          {
-            "format": "geojson-geometry"
-          },
-          {
-            "$ref": "http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometryGeoJSON.yaml"
-          }
-        ]
+        "format": "geojson-geometry"
       }
     ]
   }

diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc
@@ -58,5 +58,3 @@ include::../requirements/ogcapppkg/deploy/REQ_body.adoc[]
 ==== OGC Application Package body
 
 include::../requirements/ogcapppkg/replace/REQ_body.adoc[]
-
-