diff --git a/core/abstract_tests/ATS_class_dismiss.adoc b/core/abstract_tests/ATS_class_dismiss.adoc index 692fde4c..448330d7 100644 --- a/core/abstract_tests/ATS_class_dismiss.adoc +++ b/core/abstract_tests/ATS_class_dismiss.adoc @@ -14,7 +14,7 @@ include::dismiss/ATS_job-dismiss-op.adoc[] include::dismiss/ATS_job-dismiss-success.adoc[] -NOTE: The response to dismissing a job can be presented in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate against that schema. All supported formats should be exercised. +NOTE: The response to dismissing a job can be presented in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate against that schema. All supported formats should be exercised. [[job-dismiss-schema]] .Schema and Tests for Dismissing a Job diff --git a/core/abstract_tests/ATS_class_job-list.adoc b/core/abstract_tests/ATS_class_job-list.adoc index c51bf2b9..91b4a652 100644 --- a/core/abstract_tests/ATS_class_job-list.adoc +++ b/core/abstract_tests/ATS_class_job-list.adoc @@ -55,7 +55,7 @@ include::job-list/ATS_limit-response.adoc[] include::job-list/ATS_links.adoc[] -NOTE: A job list may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised. +NOTE: A job list may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised. [[job-list-schema]] .Schema and Tests for Job List Content diff --git a/core/abstract_tests/callback/ATS_process-execute-callback.adoc b/core/abstract_tests/callback/ATS_process-execute-callback.adoc index 53d6f398..82212e79 100644 --- a/core/abstract_tests/callback/ATS_process-execute-callback.adoc +++ b/core/abstract_tests/callback/ATS_process-execute-callback.adoc @@ -9,7 +9,7 @@ test-purpose:: Validate the passing of a subscriber-URL in an execute request. test-method:: + -- -1. Configure a URL endpoint to accept message body from the server. +1. Configure a URL endpoint to accept a message body from the server. 2. Create an asynchronous execute request that includes the optional `subscriber` key (see https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/execute.yaml[execute.yaml]. diff --git a/core/abstract_tests/core/ATS_api-definition-op.adoc b/core/abstract_tests/core/ATS_api-definition-op.adoc index 01d9e63f..66065b97 100644 --- a/core/abstract_tests/core/ATS_api-definition-op.adoc +++ b/core/abstract_tests/core/ATS_api-definition-op.adoc @@ -11,7 +11,7 @@ test-method:: -- 1. Construct a path for the API Definition document that ends with `/api`. -2. Issue a HTTP GET request on that path +2. Issue a HTTP GET request on that path. 3. Validate the contents of the returned document using test <>. -- diff --git a/core/abstract_tests/core/ATS_api-definition-success.adoc b/core/abstract_tests/core/ATS_api-definition-success.adoc index bf35398d..e24589d0 100644 --- a/core/abstract_tests/core/ATS_api-definition-success.adoc +++ b/core/abstract_tests/core/ATS_api-definition-success.adoc @@ -9,7 +9,7 @@ test-purpose:: Validate that the API Definition complies with the required struc test-method:: + -- -1. Validate that a document was returned with a status code 200 +1. Validate that a document was returned with a status code 200. 2. Validate the API Definition document against an appropriate schema document. -- diff --git a/core/abstract_tests/core/ATS_conformance-op.adoc b/core/abstract_tests/core/ATS_conformance-op.adoc index 8be42a41..94a71dff 100644 --- a/core/abstract_tests/core/ATS_conformance-op.adoc +++ b/core/abstract_tests/core/ATS_conformance-op.adoc @@ -11,7 +11,7 @@ test-method:: -- 1. Construct a path for each "rel=http://www.opengis.net/def/rel/ogc/1.0/conformance" link on the landing page as well as for the {root}/conformance path. -2. Issue an HTTP GET request on each path +2. Issue an HTTP GET request on each path. 3. Validate the contents of the returned document using test <>. -- diff --git a/core/abstract_tests/core/ATS_conformance-success.adoc b/core/abstract_tests/core/ATS_conformance-success.adoc index bfc2d036..c8c8fbd2 100644 --- a/core/abstract_tests/core/ATS_conformance-success.adoc +++ b/core/abstract_tests/core/ATS_conformance-success.adoc @@ -11,9 +11,9 @@ test-method:: -- 1. Validate that a document was returned with an HTTP status code of 200. -2. Validate the response document against OpenAPI 3.0 schema link: http://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/confClasses.yaml[confClasses.yaml] +2. Validate the response document against OpenAPI 3.0 schema link: http://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/confClasses.yaml[confClasses.yaml]. -3. Validate that the document includes the conformance class "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core" +3. Validate that the document includes the conformance class "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core". 4. Validate that the document list all OGC API conformance classes that the API implements. -- diff --git a/core/abstract_tests/core/ATS_job-exception-no-such-job.adoc b/core/abstract_tests/core/ATS_job-exception-no-such-job.adoc index 5c75a5f3..f9df9ac4 100644 --- a/core/abstract_tests/core/ATS_job-exception-no-such-job.adoc +++ b/core/abstract_tests/core/ATS_job-exception-no-such-job.adoc @@ -19,7 +19,7 @@ test-method:: -- ==== -NOTE: An exception response caused by the use of an invalid job identifier may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the response. All supported formats should be exercised. +NOTE: An exception response caused by using an invalid job identifier may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the response. All supported formats should be exercised. [[job-exception-no-such-job]] .Schema and Tests for the Job Result for Non-existent Job diff --git a/core/abstract_tests/core/ATS_job-results-exception-no-such-job.adoc b/core/abstract_tests/core/ATS_job-results-exception-no-such-job.adoc index 15ed7616..6f3d6212 100644 --- a/core/abstract_tests/core/ATS_job-results-exception-no-such-job.adoc +++ b/core/abstract_tests/core/ATS_job-results-exception-no-such-job.adoc @@ -19,7 +19,7 @@ test-method:: -- ==== -NOTE: The job results page for a job may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the job results for a non-existent job against that schema. All supported formats should be exercised. +NOTE: The job results page for a job may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the job results for a non-existent job against that schema. All supported formats should be exercised. [[job-results-exception-no-such-job]] .Schema and Tests for the Job Result for Non-existent Job diff --git a/core/abstract_tests/core/ATS_job-results-exception-results-not-ready.adoc b/core/abstract_tests/core/ATS_job-results-exception-results-not-ready.adoc index 8569c906..94792853 100644 --- a/core/abstract_tests/core/ATS_job-results-exception-results-not-ready.adoc +++ b/core/abstract_tests/core/ATS_job-results-exception-results-not-ready.adoc @@ -9,7 +9,7 @@ test-purpose:: Validate that the job results retrieved for an incomplete job com test-method:: + -- -1. Create a job as per <> and note the {jobID} assigned to the job; ensure that the job is long-running. +1. Create a job as per <> and note the {jobID} assigned to the job. Ensure that the job is long-running. 2. Issue an HTTP GET request to the URL '/jobs/{jobID}/results' before the job completes execution. @@ -21,7 +21,7 @@ test-method:: -- ==== -NOTE: The job results page for a job may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the job results for an incomplete job against that schema. All supported formats should be exercised. +NOTE: The job results page for a job may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the job results for an incomplete job against that schema. All supported formats should be exercised. [[job-results-exception-results-not-ready]] .Schema and Tests for the Job Result for an Incomplete Job diff --git a/core/abstract_tests/core/ATS_job-results-failed.adoc b/core/abstract_tests/core/ATS_job-results-failed.adoc index d623bd06..fd533b36 100644 --- a/core/abstract_tests/core/ATS_job-results-failed.adoc +++ b/core/abstract_tests/core/ATS_job-results-failed.adoc @@ -9,9 +9,9 @@ test-purpose:: Validate that the job results for a failed job complies with the test-method:: + -- -1. Create a job as per <> but arrange a priori that the job will fail; note the {jobID} assigned to the job. +1. Create a job as per <> but arrange a priori that the job will fail. Note the {jobID} assigned to the job. -2. Ensure that the failed job will not result in an HTTP error code of 404. +2. Ensure that the failed job will not result in an HTTP 404 error code. 3. Issue an HTTP GET request to the URL '/jobs/{jobID}/results'. @@ -23,7 +23,7 @@ test-method:: -- ==== -NOTE: The job results page for a job may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the job results for a failed job against that schema. All supported formats should be exercised. +NOTE: The job results page for a job may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the job results for a failed job against that schema. All supported formats should be exercised. [[job-results-failed-schema]] .Schema and Tests for the Job Result for a Failed Job diff --git a/core/abstract_tests/core/ATS_job-success.adoc b/core/abstract_tests/core/ATS_job-success.adoc index 6c71c727..ceaf7c88 100644 --- a/core/abstract_tests/core/ATS_job-success.adoc +++ b/core/abstract_tests/core/ATS_job-success.adoc @@ -15,7 +15,7 @@ test-method:: -- ==== -NOTE: The status info page for a job may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the status info against that schema. All supported formats should be exercised. +NOTE: The status info page for a job may be retrieved in a one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the status info against that schema. All supported formats should be exercised. [[job-status-info-schema]] .Schema and Tests for the Job Status Info diff --git a/core/abstract_tests/core/ATS_landingpage-success.adoc b/core/abstract_tests/core/ATS_landingpage-success.adoc index af0cffba..f43e7b26 100644 --- a/core/abstract_tests/core/ATS_landingpage-success.adoc +++ b/core/abstract_tests/core/ATS_landingpage-success.adoc @@ -26,7 +26,7 @@ test-method:: ==== -NOTE: The landing page may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the landing page against that schema. All supported formats should be exercised. +NOTE: The landing page may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the landing page against that schema. All supported formats should be exercised. [[landing-page-schema]] .Schema and Tests for Landing Pages diff --git a/core/abstract_tests/core/ATS_process-description-success.adoc b/core/abstract_tests/core/ATS_process-description-success.adoc index 9dda7e4e..630057b9 100644 --- a/core/abstract_tests/core/ATS_process-description-success.adoc +++ b/core/abstract_tests/core/ATS_process-description-success.adoc @@ -15,7 +15,7 @@ test-method:: -- ==== -NOTE: The interface of a process may be describing using a number of different models or process description languages. The following table identifies the applicable schema document for each process description model described in this standard. +NOTE: The interface of a process may be described using one of a number of different models or process description languages. The following table identifies the applicable schema document for each process description model described in this standard. [[process-description-model]] .Schema and Tests for Process Description Models diff --git a/core/abstract_tests/core/ATS_process-exception-no-such-process.adoc b/core/abstract_tests/core/ATS_process-exception-no-such-process.adoc index 46dd44cd..e61f4f65 100644 --- a/core/abstract_tests/core/ATS_process-exception-no-such-process.adoc +++ b/core/abstract_tests/core/ATS_process-exception-no-such-process.adoc @@ -19,7 +19,7 @@ test-method:: -- ==== -NOTE: An exception response caused by the use of an invalid process identifier may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the response. All supported formats should be exercised. +NOTE: An exception response caused by using an invalid process identifier may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the response. All supported formats should be exercised. [[no-such-process]] .Schema and Tests for Non-existent Process diff --git a/core/abstract_tests/core/ATS_process-execute-input-array.adoc b/core/abstract_tests/core/ATS_process-execute-input-array.adoc index 04ac81e3..583bf328 100644 --- a/core/abstract_tests/core/ATS_process-execute-input-array.adoc +++ b/core/abstract_tests/core/ATS_process-execute-input-array.adoc @@ -11,7 +11,7 @@ test-method:: -- 1. Get a description of each process offered by the server using test <>. -2. Inspect the description of each process and identify the list of processes that have inputs with a maximum cardinality greater that one. +2. Inspect the description of each process and identify the list of processes that have inputs with a maximum cardinality greater than one. 3. For each identified process construct an execute request according to test <> taking care to encode the inputs with maximum cardinality > 1 according to the requirement <>. diff --git a/core/abstract_tests/core/ATS_process-execute-input-inline-bbox.adoc b/core/abstract_tests/core/ATS_process-execute-input-inline-bbox.adoc index ad6495ac..00fb722d 100644 --- a/core/abstract_tests/core/ATS_process-execute-input-inline-bbox.adoc +++ b/core/abstract_tests/core/ATS_process-execute-input-inline-bbox.adoc @@ -15,6 +15,6 @@ test-method:: 3. For each identified process construct an execute request according to test <> taking care to encode values for the identified bounding box inputs in-line in the execute request. -4. Verify that each process execute successfulle according to the relevant requirement (one of: <>, <>, <>, <>) based on the combination of execute parameters. +4. Verify that each process executes successfully according to the relevant requirement (one of: <>, <>, <>, <>) based on the combination of execute parameters. -- ==== diff --git a/core/abstract_tests/core/ATS_process-execute-input-inline-binary.adoc b/core/abstract_tests/core/ATS_process-execute-input-inline-binary.adoc index 1b3993d0..3d696aa1 100644 --- a/core/abstract_tests/core/ATS_process-execute-input-inline-binary.adoc +++ b/core/abstract_tests/core/ATS_process-execute-input-inline-binary.adoc @@ -15,6 +15,6 @@ test-method:: 3. For each identified process construct an execute request according to test <> taking care to encode binary input values in-line in the execute request according to requirement <>. -4. Verify that each process execute successfully according to the relevant requirement (one of: <>, <>, <>, <>) base on the combination of execute parameters. +4. Verify that each process executes successfully according to the relevant requirement (one of: <>, <>, <>, <>) base on the combination of execute parameters. -- ==== diff --git a/core/abstract_tests/core/ATS_process-execute-input-inline-mixed.adoc b/core/abstract_tests/core/ATS_process-execute-input-inline-mixed.adoc index fb6402f5..cf0406a0 100644 --- a/core/abstract_tests/core/ATS_process-execute-input-inline-mixed.adoc +++ b/core/abstract_tests/core/ATS_process-execute-input-inline-mixed.adoc @@ -15,6 +15,6 @@ test-method:: 3. For each identified process construct an execute request according to test <> taking care to encode the identified mix-content inputs in-line in the execute request according to requirement <>. -4. Verify that each process execute successfully according to the relevant requirement (one of: <>, <>, <>, <>) base on the combination of execute parameters. +4. Verify that each process executes successfully according to the relevant requirement (one of: <>, <>, <>, <>) base on the combination of execute parameters. -- ==== diff --git a/core/abstract_tests/core/ATS_process-execute-input-inline-object.adoc b/core/abstract_tests/core/ATS_process-execute-input-inline-object.adoc index 73190912..b933f9ec 100644 --- a/core/abstract_tests/core/ATS_process-execute-input-inline-object.adoc +++ b/core/abstract_tests/core/ATS_process-execute-input-inline-object.adoc @@ -15,6 +15,6 @@ test-method:: 3. For each identified process construct an execute request according to test <> taking care to encode the identified object inputs in-line in the execute request according to requirement <>. -4. Verify that each process execute successfulle according to the relevant requirement (one of: <>, <>, <>, <>) based on the combination of execute parameters. +4. Verify that each process executes successfully according to the relevant requirement (one of: <>, <>, <>, <>) based on the combination of execute parameters. -- ==== diff --git a/core/abstract_tests/core/ATS_process-list-limit-def.adoc b/core/abstract_tests/core/ATS_process-list-limit-def.adoc index a4ffb319..ae5218eb 100644 --- a/core/abstract_tests/core/ATS_process-list-limit-def.adoc +++ b/core/abstract_tests/core/ATS_process-list-limit-def.adoc @@ -13,4 +13,4 @@ Verify that the `limit` query parameter complies with its definition in requirem -- ==== -NOTE: The API can define different values for "minimum", "maximum" and "default". +NOTE: An implementation of the Processes API can define different values for "minimum", "maximum" and "default". diff --git a/core/abstract_tests/core/ATS_process-list-success.adoc b/core/abstract_tests/core/ATS_process-list-success.adoc index 5ea48a6b..9ad648a5 100644 --- a/core/abstract_tests/core/ATS_process-list-success.adoc +++ b/core/abstract_tests/core/ATS_process-list-success.adoc @@ -15,7 +15,7 @@ test-method:: -- ==== -NOTE: The process list may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised. +NOTE: The process list may be retrieved in one of two formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised. [[process-list-schema]] .Schema and Tests for Lists content diff --git a/core/abstract_tests/html/ATS_content.adoc b/core/abstract_tests/html/ATS_content.adoc index 6dcb0414..714861ee 100644 --- a/core/abstract_tests/html/ATS_content.adoc +++ b/core/abstract_tests/html/ATS_content.adoc @@ -9,7 +9,7 @@ test-purpose:: Verify the content of an HTML document given an input document an test-method:: + -- -. Validate that the document is an <> document +. Validate that the document is an <> document. . Manually inspect the document and verify that the HTML body contains: diff --git a/core/abstract_tests/html/ATS_definition.adoc b/core/abstract_tests/html/ATS_definition.adoc index 890ef9d0..5ee57924 100644 --- a/core/abstract_tests/html/ATS_definition.adoc +++ b/core/abstract_tests/html/ATS_definition.adoc @@ -9,6 +9,6 @@ test-purpose:: Verify support for HTML test-method:: + -- -Verify that every `200` response of every operation of the API where HTML was requested is of media type `text/html`. +Verify that every `200` response for every operation of the Processes API implementation for which HTML was requested is of media type `text/html`. -- ==== diff --git a/core/abstract_tests/job-list/ATS_limit-def.adoc b/core/abstract_tests/job-list/ATS_limit-def.adoc index d86ee6f7..b08f109d 100644 --- a/core/abstract_tests/job-list/ATS_limit-def.adoc +++ b/core/abstract_tests/job-list/ATS_limit-def.adoc @@ -13,4 +13,4 @@ Verify that the `limit` query parameter complies with its definition in requirem -- ==== -NOTE: The API can define different values for "minimum", "maximum" and "default". +NOTE: An implementation of the Processes API can define different values for "minimum", "maximum" and "default". diff --git a/core/abstract_tests/ogc-process-description/ATS_output-mixed-type.adoc b/core/abstract_tests/ogc-process-description/ATS_output-mixed-type.adoc index e96919d8..eaf0a1e2 100644 --- a/core/abstract_tests/ogc-process-description/ATS_output-mixed-type.adoc +++ b/core/abstract_tests/ogc-process-description/ATS_output-mixed-type.adoc @@ -11,7 +11,7 @@ test-method:: -- 1. Retrieve a description of each process according to test <>. -2. For each process identify if the process has one or more output of mixed type denoted by the use of the `oneOf` JSON Schema keyword. +2. For each process identify if the process has one or more output of mixed type denoted by using the `oneOf` JSON Schema keyword. 3. For each sub-schema or each identified output, verify that the definition validates according to the JSON Schema: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/schema.yaml[schema.yaml]. -- diff --git a/core/recommendations/core/PER_api-definition-uri.adoc b/core/recommendations/core/PER_api-definition-uri.adoc index 39b1ac53..09b6d342 100644 --- a/core/recommendations/core/PER_api-definition-uri.adoc +++ b/core/recommendations/core/PER_api-definition-uri.adoc @@ -4,6 +4,5 @@ [%metadata] label:: /per/core/api-definition-uri -The API definition is metadata about the API and strictly not part of the API -itself, but it MAY be hosted as a sub-resource to the base path of the API, for example, at path `/api`. There is no need to include the path of the API definition in the API definition itself. -==== \ No newline at end of file +The API definition is metadata about the capabilities provided by an API implementation instance and strictly speaking is not part of the API itself, but the definition MAY be hosted as a sub-resource to the base path of the API, for example, at path `/api`. There is no need to include the path of the API definition in the API definition itself. +==== diff --git a/core/recommendations/core/PER_job-results-success-async-many-other-formats.adoc b/core/recommendations/core/PER_job-results-success-async-many-other-formats.adoc index 116c0bc1..ba612f28 100644 --- a/core/recommendations/core/PER_job-results-success-async-many-other-formats.adoc +++ b/core/recommendations/core/PER_job-results-success-async-many-other-formats.adoc @@ -9,6 +9,7 @@ label:: /per/core/job-results-async-many-other-formats . The number of requested outputs is 2 or more. -- -part:: Servers MAY support other response formats or encodings (e.g. ZIP or `multipart/*`) that do not conform to https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/results.yaml[results.yaml]. -part:: This standard does not provide any guidance on these other formats or encodings. +part:: Servers MAY support other response formats or encodings (e.g. ZIP or `multipart/*`) that do not conform to https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/results.yaml[results.yaml]. + +part:: This Standard does not provide any guidance on these other formats or encodings. ==== diff --git a/core/recommendations/core/PER_process-execute-success-sync-many-other-formats.adoc b/core/recommendations/core/PER_process-execute-success-sync-many-other-formats.adoc index e313d735..737eac31 100644 --- a/core/recommendations/core/PER_process-execute-success-sync-many-other-formats.adoc +++ b/core/recommendations/core/PER_process-execute-success-sync-many-other-formats.adoc @@ -9,6 +9,6 @@ label:: /per/core/process-execute-sync-many-other-formats . The number of requested outputs is 2 or more. -- -part:: Servers MAY support other response formats or encodings (e.g. ZIP or `multipart/*`) that do not conform to https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/results.yaml[results.yaml]. -part:: This standard does not provide any guidance on these other formats or encodings. +part:: Servers MAY support other response formats or encodings (e.g. ZIP or `multipart/*`) that do not conform to https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/results.yaml[results.yaml]. +part:: This Standard does not provide any guidance on these other formats or encodings. ==== diff --git a/core/recommendations/core/REC_api-definition-oas.adoc b/core/recommendations/core/REC_api-definition-oas.adoc index ceb2dfe2..33a0120a 100644 --- a/core/recommendations/core/REC_api-definition-oas.adoc +++ b/core/recommendations/core/REC_api-definition-oas.adoc @@ -1,7 +1,5 @@ [[rec_core_api_definition-oas]] [recommendation,type="general",id="/rec/core/api-definition-oas",label="/rec/core/api-definition-oas"] ==== -If the API definition document uses the OpenAPI Specification 3.0, -the document SHOULD conform to the -<>. +If the API definition document is defined using the OpenAPI Specification 3.0, the document SHOULD conform to the <>. ==== diff --git a/core/recommendations/core/REC_job-status.adoc b/core/recommendations/core/REC_job-status.adoc index a9b033d0..20d040b8 100644 --- a/core/recommendations/core/REC_job-status.adoc +++ b/core/recommendations/core/REC_job-status.adoc @@ -18,7 +18,7 @@ Servers SHOULD set the value of the `started` field when a job begins execution [.component,class=part] -- -Servers SHOULD set the value of the `finished` field when the execution of a job has completed and the process is no longer consuming compute resources. +Servers SHOULD set the value of the `finished` field when the execution of a job has completed, and the process is no longer consuming compute resources. -- [.component,class=part] diff --git a/core/recommendations/core/REC_process-execute-preference-applied.adoc b/core/recommendations/core/REC_process-execute-preference-applied.adoc index ac057688..f2c3daa4 100644 --- a/core/recommendations/core/REC_process-execute-preference-applied.adoc +++ b/core/recommendations/core/REC_process-execute-preference-applied.adoc @@ -1,5 +1,5 @@ [[rec_core_process-execute-preference-applied]] [recommendation,type="general",id="/rec/core/process-execute-preference-applied",label="/rec/core/process-execute-preference-applied"] ==== -If an execute request is accompanied with the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-2[`Prefer`] header then, in the <>, servers SHOULD include the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-3[`Preference-Applied`] response header as an indication as to which https://datatracker.ietf.org/doc/html/rfc7240#section-2['Prefer`] tokens were honoured by the server. +If an execute request is accompanied with the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-2[`Prefer`] header then, in the <>, servers SHOULD include the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-3[`Preference-Applied`] response header as an indication as to which https://datatracker.ietf.org/doc/html/rfc7240#section-2['Prefer`] tokens were honored by the server. ==== diff --git a/core/recommendations/core/REC_process-list-next-1.adoc b/core/recommendations/core/REC_process-list-next-1.adoc index 57374214..c66b9383 100644 --- a/core/recommendations/core/REC_process-list-next-1.adoc +++ b/core/recommendations/core/REC_process-list-next-1.adoc @@ -1,5 +1,5 @@ [[rec_core_next-1]] [recommendation,type="general",id="/rec/core/next-1",label="/rec/core/next-1"] ==== -A `200`-response SHOULD include a link to the next page (relation: `next`) of process summaries, if more process summaries have been selected than returned in the response. +If more processes summaries have been selected than returned in the response, a `200`-response SHOULD include a link to the next page (relation: `next`) of process summaries. ==== diff --git a/core/recommendations/core/REC_test-process.adoc b/core/recommendations/core/REC_test-process.adoc index 94fbaa97..43d8ceda 100644 --- a/core/recommendations/core/REC_test-process.adoc +++ b/core/recommendations/core/REC_test-process.adoc @@ -6,5 +6,5 @@ If a server implementing the OGC API - Processes - Part 1: Core is tested using . An Echo process that returns any input that is provided, without any actual processing. . Provide example input data for a specific process. -The process logic SHOULD include a delay, whether through actual processing or a simple sleep mechanism, in order to test asynchronous execution. +The process logic SHOULD include a delay, whether through actual processing or a simple sleep mechanism, to test asynchronous execution. ==== diff --git a/core/recommendations/job-list/REC_next-1.adoc b/core/recommendations/job-list/REC_next-1.adoc index 8171e642..495d0877 100644 --- a/core/recommendations/job-list/REC_next-1.adoc +++ b/core/recommendations/job-list/REC_next-1.adoc @@ -1,5 +1,6 @@ [[rec_job-list_next-1]] [recommendation,type="general",id="/rec/job-list/next-1",label="/rec/job-list/next-1"] ==== -A `200`-response SHOULD include a link to the next page (relation: `next`) of jobs, if more jobs have been selected than returned in the response. +If more jobs have been selected than returned in the respose, a `200`-response SHOULD include a link to the next page (relation: `next`) of jobs. ==== + diff --git a/core/recommendations/job-list/REC_next-3.adoc b/core/recommendations/job-list/REC_next-3.adoc index a10cf316..87a109dc 100644 --- a/core/recommendations/job-list/REC_next-3.adoc +++ b/core/recommendations/job-list/REC_next-3.adoc @@ -1,5 +1,5 @@ [[rec_job-list_next-3]] [recommendation,type="general",id="/rec/job-list/next-3",label="/rec/job-list/next-3"] ==== -The number of jobs in a response to dereferencing a next page link (relation: `next`) SHOULD follow the same rules as for the response to the original query and again include a next page link (relation: `next`), if there are more jobs in the selection that have not yet been returned. +If there are more jobs in the selection that have not yet been returned, the number of jobs in a response to dereferencing a next page link (relation: `next`) SHOULD follow the same rules as for the response to the original query and again include a next page link (relation: `next`). ==== diff --git a/core/requirements/core/REQ_conformance-success.adoc b/core/requirements/core/REQ_conformance-success.adoc index 0c3650d1..b2878810 100644 --- a/core/requirements/core/REQ_conformance-success.adoc +++ b/core/requirements/core/REQ_conformance-success.adoc @@ -7,6 +7,5 @@ identifier:: /req/core/conformance-success A successful execution of the operation SHALL be reported as a response with a HTTP status code `200`. -The content of that response SHALL be based upon the OpenAPI 3.0 schema link:https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/common-core/confClasses.yaml[req-classes.yaml] and -list all OGC API - Processes requirements classes that the server conforms to. +The content of that response SHALL be based upon the OpenAPI 3.0 schema link:https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/common-core/confClasses.yaml[req-classes.yaml] and list all OGC API - Processes conformance classes that an implementation of the Processes API conforms to. ==== diff --git a/core/requirements/core/REQ_job-results-failed.adoc b/core/requirements/core/REQ_job-results-failed.adoc index d337520c..34b025ae 100644 --- a/core/requirements/core/REQ_job-results-failed.adoc +++ b/core/requirements/core/REQ_job-results-failed.adoc @@ -4,8 +4,5 @@ [%metadata] identifier:: /req/core/job-results-failed -If the operation is executed on a failed job using a valid job identifier, the response SHALL have a HTTP error code that corresponds to the reason of the failure. -The content of that response SHALL be based upon the OpenAPI -3.0 schema https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/common-core/exception.yaml[exception.yaml]. -The `type` of the exception SHALL correspond to the reason of the failure, e.g. InvalidParameterValue for invalid input data. +If the operation is executed on a failed job using a valid job identifier, the response SHALL have a HTTP error code that corresponds to the reason for the failure. The content of that response SHALL be based upon the OpenAPI 3.0 schema https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/common-core/exception.yaml[exception.yaml]. The `type` of the exception SHALL correspond to the reason of the failure, e.g. InvalidParameterValue for invalid input data. ==== diff --git a/core/requirements/core/REQ_job-results-success-sync.adoc b/core/requirements/core/REQ_job-results-success-sync.adoc index 47a82354..ec4f0bb3 100644 --- a/core/requirements/core/REQ_job-results-success-sync.adoc +++ b/core/requirements/core/REQ_job-results-success-sync.adoc @@ -3,7 +3,7 @@ ==== [%metadata] identifier:: /req/core/job-results-success-sync -conditions:: The server creates a job when a processes is executed synchronously. +conditions:: The server creates a job when a process is executed synchronously. part:: A successful execution of the operation SHALL include an HTTP https://datatracker.ietf.org/doc/html/rfc8288#section-3[`Link`] header with `rel=monitor` pointing to the created job. part:: When resolving the `rel=monitor` link, the content type of response SHALL be `application/json`. diff --git a/core/requirements/core/REQ_process-execute-success-sync-one-default-content.adoc b/core/requirements/core/REQ_process-execute-success-sync-one-default-content.adoc index 6f30798b..058ce7f2 100644 --- a/core/requirements/core/REQ_process-execute-success-sync-one-default-content.adoc +++ b/core/requirements/core/REQ_process-execute-success-sync-one-default-content.adoc @@ -7,7 +7,7 @@ identifier:: /req/core/process-execute-sync-one-default-content -- . The <> is synchronous, . The number of requested outputs is 1. -. No content negotiation has been sepcified using either HTTP headers or other methods. +. No content negotiation has been specified using either HTTP headers or other methods. -- [.component,class=part] diff --git a/core/requirements/core/REQ_process-execute-success-sync-one.adoc b/core/requirements/core/REQ_process-execute-success-sync-one.adoc index 8c6bec56..0d230ca5 100644 --- a/core/requirements/core/REQ_process-execute-success-sync-one.adoc +++ b/core/requirements/core/REQ_process-execute-success-sync-one.adoc @@ -11,7 +11,7 @@ identifier:: /req/core/process-execute-sync-one [.component,class=part] -- -A successful execution of the the operation SHALL be reported with a response with a HTTP status code `200`. +A successful execution of the operation SHALL be reported with a response with a HTTP status code `200`. -- [.component,class=part] diff --git a/core/requirements/job-list/REQ_datetime-def.adoc b/core/requirements/job-list/REQ_datetime-def.adoc index 0f156d54..6dffe8cc 100644 --- a/core/requirements/job-list/REQ_datetime-def.adoc +++ b/core/requirements/job-list/REQ_datetime-def.adoc @@ -19,7 +19,7 @@ schema: [.component,class=part] -- -The value of the `datetime` parameter is either a date-time value or a time interval. The parameter value SHALL conform to the following syntax (using link:https://tools.ietf.org/html/rfc2234[ABNF]): +The value of the `datetime` parameter is either a date-time value or a time interval. The `datetime` parameter value SHALL conform to the following syntax (using link:https://tools.ietf.org/html/rfc2234[ABNF]): ``` interval-closed = date-time "/" date-time diff --git a/core/requirements/job-list/REQ_datetime-response.adoc b/core/requirements/job-list/REQ_datetime-response.adoc index 406d9434..5940cd32 100644 --- a/core/requirements/job-list/REQ_datetime-response.adoc +++ b/core/requirements/job-list/REQ_datetime-response.adoc @@ -4,5 +4,5 @@ [%metadata] identifier:: /req/job-list/datetime-response -If the parameter is specified with the operation, only jobs that have a value for the `created` property (see: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/statusInfo.yaml[statusInfo.yaml] that intersects the temporal information in the `datetime` parameter SHALL be included in the response. +If the `datetime` parameter is specified with the operation, only jobs that have a value for the `created` property (see: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/statusInfo.yaml[statusInfo.yaml] that intersects the temporal information in the `datetime` parameter SHALL be included in the response. ==== diff --git a/core/requirements/job-list/REQ_processid-response.adoc b/core/requirements/job-list/REQ_processid-response.adoc index 16da6f12..3d30ebfa 100644 --- a/core/requirements/job-list/REQ_processid-response.adoc +++ b/core/requirements/job-list/REQ_processid-response.adoc @@ -4,5 +4,5 @@ [%metadata] identifier:: /req/job-list/processid-response -If the parameter is specified with the operation, only jobs that have a value for the `processID` property (see: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/statusInfo.yaml[statusInfo.yaml]) that matches one of the values specified for the `processID` parameter SHALL be included in the response. +If the `processID` parameter is specified with the operation, only jobs that have a value for the `processID` property (see: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/statusInfo.yaml[statusInfo.yaml]) that matches one of the values specified for the `processID` parameter SHALL be included in the response. ==== diff --git a/core/requirements/job-list/REQ_status-response.adoc b/core/requirements/job-list/REQ_status-response.adoc index c2da9c10..18a17ab2 100644 --- a/core/requirements/job-list/REQ_status-response.adoc +++ b/core/requirements/job-list/REQ_status-response.adoc @@ -4,5 +4,5 @@ [%metadata] identifier:: /req/job-list/status-response -If the parameter is specified with the operation, only jobs that have a value for the `status` property (see: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/statusInfo.yaml[statusInfo.yaml]) that matches one of the specified values of the `status` parameter SHALL be included in the response. +If the `status` parameter is specified with the operation, only jobs that have a value for the `status` property (see: https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/statusInfo.yaml[statusInfo.yaml]) that matches one of the specified values of the `status` parameter SHALL be included in the response. ==== diff --git a/core/requirements/kvp-execute/REQ_input-cardinality.adoc b/core/requirements/kvp-execute/REQ_input-cardinality.adoc index 0a7c3129..4690ace5 100644 --- a/core/requirements/kvp-execute/REQ_input-cardinality.adoc +++ b/core/requirements/kvp-execute/REQ_input-cardinality.adoc @@ -12,7 +12,7 @@ identifier:: /req/kvp-execute/input-cardinality [.component,class=part] -- -A process input having more that one value SHALL be encoded as a list of values according to the query parameter serialization rules of the https://spec.openapis.org/oas/v3.0.3#parameter-object[OpenAPI Specification v3.0.3]. The default list value separator is the comma (",") but other values are possible too. +A process input having more than one value SHALL be encoded as a list of values according to the query parameter serialization rules of the https://spec.openapis.org/oas/v3.0.3#parameter-object[OpenAPI Specification v3.0.3]. The default list value separator is the comma (",") but other values are possible too. -- [.component,class=part] diff --git a/core/requirements/ogc-process-description/REQ_inputs-def.adoc b/core/requirements/ogc-process-description/REQ_inputs-def.adoc index 5923279e..80e57c44 100644 --- a/core/requirements/ogc-process-description/REQ_inputs-def.adoc +++ b/core/requirements/ogc-process-description/REQ_inputs-def.adoc @@ -10,6 +10,6 @@ Each process input definition SHALL be listed in the `inputs` section according [.component,class=part] -- -The key of each process input in the `inputs` section of the process definition SHALL be the identifier for that input. +The key for each process input in the `inputs` section of the process definition SHALL be the identifier for that input. -- ==== diff --git a/core/requirements/ogc-process-description/REQ_outputs-def.adoc b/core/requirements/ogc-process-description/REQ_outputs-def.adoc index 1a67b1e1..b7c19faa 100644 --- a/core/requirements/ogc-process-description/REQ_outputs-def.adoc +++ b/core/requirements/ogc-process-description/REQ_outputs-def.adoc @@ -10,6 +10,6 @@ Each process output definition SHALL be listed in the `outputs` section accordin [.component,class=part] -- -The key of each process input in the `output` section of the process definition SHALL be the identifier for that output. +The key for each process output in the `output` section of the process definition SHALL be the identifier for that output. -- ==== diff --git a/core/sections/clause_0_front_material.adoc b/core/sections/clause_0_front_material.adoc index 5e3cf229..28c75708 100644 --- a/core/sections/clause_0_front_material.adoc +++ b/core/sections/clause_0_front_material.adoc @@ -1,21 +1,20 @@ .Preface -The OGC API - Processes Standard defines how a client application can request the execution of a process, how the inputs to that process can be provided, and how the output from the process is handled. The specification allows for the wrapping of computational tasks into an executable process that can be invoked by a client application. Examples of computational processes that can be supported by implementations of this specification include raster algebra, geometry buffering, constructive area geometry, routing, imagery analysis and several others. +The OGC API - Processes Standard defines how a client application can request the execution of a process, how the inputs to that process can be provided, and how the output from the process is handled. The Standard specified who to "wrap" computational tasks into an executable process that can be invoked by a client application. Examples of computational processes that can be supported by implementations of API Processes include raster algebra, geometry buffering, constructive area geometry, routing, imagery analysis and several others. [abstract] == Abstract -This document defines the OGC API - Processes Standard. This standard builds on the OGC Web Processing Service (WPS) 2.0 Standard and defines the processing interface to communicate over a RESTful protocol using JSON encodings. +The OGC API - Processes Standard specifies a Web API that enables the execution of computing processes, the retrieval of metadata describing their purpose and functionality and the retrieval of the results of the process execution. The requirements specified in the OGC API — Processes Standard build on the OGC Web Processing Service (WPS) 2.0 Standard and specify a processing interface to communicate over a RESTful protocol using JSON encodings. -By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The OGC Web Processing Service (WPS) Interface Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in GIS software as well as specialized processes for spatiotemporal modeling and simulation. While the OGC WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. -The WPS standard provides a robust, interoperable, and versatile protocol for process execution on web services. WPS supports both immediate processing for computational tasks that take little time and asynchronous processing for more complex and time-consuming tasks. Moreover, the WPS standard defines a general process model that is designed to provide an interoperable description of processing functions. WPS is intended to support process cataloguing and discovery in a distributed environment. +By way of background and context, in many cases geospatial or location data (including data from sensors) must be processed before the information can be effectively used. The OGC Web Processing Service (WPS) Interface Standard specifies a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known GIS processes as well as specialized processes for spatiotemporal modeling and simulation. While the OGC WPS Standard was designed with spatial processing in mind, WPS implementations could also be used to readily insert non-spatial processing tasks into a web services environment. The WPS Standard provides a robust, interoperable, and versatile protocol for process execution on web services. Implementations of the WPS Standard can support both immediate processing for computational tasks that take little time and asynchronous processing for more complex and time-consuming tasks. Moreover, the WPS Standard defines a general process model that is designed to provide an interoperable description of processing functions. The WPS Standard was designed to support process cataloging and discovery in a distributed environment. -This API is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. +The requirements in the OGC API – Processes Standard are designed to provide the same implementation functionality as a WPS implementation but are based on a more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The resources that are provided by a server implementing the OGC API - Processes Standard are listed in <> below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. -This following table provide an overview of resources, applicable HTTP methods and links to the related document sections. +This following table provides an overview of resources, applicable HTTP methods and links to the related document sections. [[table_core_resources]] .Requirements class `Core` diff --git a/core/sections/clause_10_encodings.adoc b/core/sections/clause_10_encodings.adoc index ad810da5..7bfb06b3 100644 --- a/core/sections/clause_10_encodings.adoc +++ b/core/sections/clause_10_encodings.adoc @@ -7,26 +7,29 @@ for now, normative statements are often included inline. This will be re-factore === Overview -This clause specifies two pre-defined requirements classes for encodings to be -used with the OGC API Processes. +This clause specifies two pre-defined requirements classes for request and response message encodings to be used by implementations the Processes API. The two classes are: * <> * <> -The JSON encoding is mandatory. +The <> requirements class defines the requirements for encoding Processes API request and response messages using https://tools.ietf.org/html/rfc8259[JSON]. -Note that any server that supports multiple encodings will have to support a mechanism to mint encoding-specific URIs for resources in order to express links, for example, to alternate representations of the same resource. This document does not mandate any particular approach how this is supported by the server. +The <> requirements class defines the requirements for encoding Processes API request and response messages using https://html.spec.whatwg.org/[HTML]. -As clients simply need to dereference the URI of the link, the implementation details and the mechanism how the encoding is included in the URI of the link are not important. Developers interested in the approach of a particular implementation, for example, to manipulate ("hack") URIs in the browser address bar, can study the API definition. +NOTE: The encoding of Processes API request and response messages is distinct from the values that are generated when executing a process. Process output values can be of any type and are not bound by the requirements of the classes defined in this clause. + +NOTE: Any server that supports multiple encodings (JSON or HTML defined in this Standard or other encodings not specified in this Standard) will have to support a mechanism to mint encoding-specific URIs for resources in order to express links, for example, to alternate representations of the same resource. This document does not mandate any approach as to how this is supported by the server. + +As clients simply need to dereference the URI of the link, the implementation detail and the mechanism as to how the encoding is included in the URI of the link are not important. Developers interested in the approach of a particular implementation, for example, to manipulate ("hack") URIs in the browser address bar, can study the API definition. [NOTE] ==== Two common approaches are: -* an additional path for each encoding of each resource (this can be expressed, +* An additional path for each encoding of each resource (this can be expressed, for example, using format specific suffixes like `.html`); -* an additional query parameter (for example, "accept" or "f") that overrides +* An additional query parameter (for example, "accept" or "f") that overrides the Accept header of the HTTP request. ==== @@ -54,6 +57,3 @@ include::../requirements/requirements_class_html.adoc[] include::../requirements/html/REQ_definition.adoc[] include::../requirements/html/REQ_content.adoc[] - - - diff --git a/core/sections/clause_11_oas.adoc b/core/sections/clause_11_oas.adoc index 36460073..b4337480 100644 --- a/core/sections/clause_11_oas.adoc +++ b/core/sections/clause_11_oas.adoc @@ -1,4 +1,3 @@ - [[requirements-class-openapi_3_0-clause]] == Requirements Class "OpenAPI 3.0" @@ -14,15 +13,11 @@ include::../requirements/oas30/REQ_oas-definition-2.adoc[] include::../requirements/oas30/REQ_oas-impl.adoc[] - === Complete definition include::../requirements/oas30/REQ_completeness.adoc[] -Note that APIs that, for example, are access-controlled (see <>), support web cache validation, CORS or that use HTTP redirection will make use of additional HTTP status codes beyond regular codes such as `200` for successful GET requests and `400`, `404` or `500` for error situations. See <>. - -Clients have to be prepared to receive responses not documented in the OpenAPI definition. For example, additional errors may occur in the transport layer outside of the server. - +NOTE: Implementations of the Processes API may also include capabilities that are not specified in this Standard such as access-control (see <>), support for web cache validation, handling of CORS or the use of HTTP redirection. These additional capabilities make use of HTTP status codes that are beyond the regular set of code such as `200` for successful GET requests and `400`, `404` or `500` for error situations (see <>). These additional codes would not necessarily be specified in a OpenAPI document and so clients must be prepared to receive responses not documents in the OpenAPI definition. For example, additional error codes may be generated in the transport layer which is outside the server. [[exceptions]] === Exceptions diff --git a/core/sections/clause_13_callback.adoc b/core/sections/clause_13_callback.adoc index efa3870b..228a0da4 100644 --- a/core/sections/clause_13_callback.adoc +++ b/core/sections/clause_13_callback.adoc @@ -2,7 +2,7 @@ [[Callbacks]] == Requirements Class "Callback" -The Callback conformance class specifies a callback mechanism for completed jobs. In contrast to the pull-based mechanism specified in <> and <>, this conformance class specifies a push-based mechanism, where a subscriber-URL is passed to the API in the execute request. After the job is completed, the result response is sent to the specified URL. +The Callback conformance class specifies a callback mechanism for completed jobs. In contrast to the pull-based mechanism specified in <> and <>, this conformance class specifies a push-based mechanism, where a subscriber-URL is passed to the Processes API in the execute request. After the job is completed, the result response is sent to the specified URL. include::../requirements/requirements_class_callback.adoc[] diff --git a/core/sections/clause_15_kvp-execute.adoc b/core/sections/clause_15_kvp-execute.adoc index 5a26bd35..19b62493 100644 --- a/core/sections/clause_15_kvp-execute.adoc +++ b/core/sections/clause_15_kvp-execute.adoc @@ -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 prefered. +In this example, the `prefer` parameter is used to indicate that asynchronous execution is preferred. [source] ---- @@ -209,7 +209,7 @@ The elements of an array input value can be: * a <>, * a <>, * a <>, -* an embeded array, +* an embedded array, * or references to values using <>. .Array input value examples. @@ -339,11 +339,11 @@ images=[ NOTE: Not sure we should specify this. Binary input values should be by reference only in my opinion. It really makes no sense to specify a binary value by-value in a URL-encoded execute request. Does it? Something small like icons ... maybe? -In some cases, for example in order to pass through firewalls, binary input values need to be encoded in-line in an execute request as a string. +In some cases, for example to pass through firewalls, binary input values need to be encoded in-line in an execute request as a string. include::../requirements/kvp-execute/REQ_binary-input-value.adoc[] -A binary value can be optionally <> with a <> parameter. This is usually done to identify one of a number of possible input types for the specified input parameter. +A binary value can be optionally <> with a <> parameter. This is usually done to identify several possible input types for the specified input parameter. include::../requirements/kvp-execute/REQ_binary-input-value-qualified.adoc[] @@ -414,7 +414,7 @@ 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 parameters names `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] ---- @@ -503,4 +503,4 @@ include::../requirements/kvp-execute/REQ_output.adoc[] === Response -Whether a processes is invoked using a <> that is https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.3[HTTP POST'ed] to the <> or using a URL-encoded request, the behaviour of the server with regard to the response is the same. The details of the response can be found in <>. +Whether a process is invoked using a <> that is https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.3[HTTP POST'ed] to the <> or a URL-encoded request is used, the behavior of the server with regard to the response is the same. The details of the response can be found in <>. diff --git a/core/sections/clause_16_media_types.adoc b/core/sections/clause_16_media_types.adoc index 828f6fa4..b46088b2 100644 --- a/core/sections/clause_16_media_types.adoc +++ b/core/sections/clause_16_media_types.adoc @@ -14,5 +14,5 @@ The media type for an OpenAPI 3.0 definition is `application/vnd.oai.openapi+json;version=3.0` (JSON) or `application/vnd.oai.openapi;version=3.0` (YAML). -NOTE: The OpenAPI media types have not been registered yet with IANA and can +NOTE: The OpenAPI media types have not yet been registered with IANA and may change in the future. diff --git a/core/sections/clause_17_additional-api-building-blocks.adoc b/core/sections/clause_17_additional-api-building-blocks.adoc index effa274b..e1eb9060 100644 --- a/core/sections/clause_17_additional-api-building-blocks.adoc +++ b/core/sections/clause_17_additional-api-building-blocks.adoc @@ -2,18 +2,18 @@ [[additional-api-building-blocks]] == Additional API Building Blocks -The core requirements classes of the Processes API standard are designed for the following workflow: +The core requirements classes of the OGC API-Processes Standard are designed for the following workflow: -. Access the list of available processes -. Access the description of a specific process -. Create an execute JSON request (based on the description) and send it to the server via POST -. Process the status info and/or results +. Access the list of available processes; +. Access the description of a specific process; +. Create an execute JSON request (based on the description) and send it to the server via POST; +. Process the status info and/or results. -This workflow is useful for generic clients that are implemented against the JSON schemas and paths specified in this standard. Generic clients can communicate with any server implementing the OGC API - Processes Standard. However, there may be limitations regarding the handling of input and output formats. +This workflow is useful for generic clients that are implemented against the JSON schemas and paths specified in this Standard. Generic clients can communicate with any server implementing the OGC API - Processes Standard. However, there may be limitations regarding the handling of input and output formats. The approach described above requires implementers of clients to have knowledge about the standard. -This standard uses the OpenAPI specification to define the JSON schemas and OpenAPI MAY also be used to describe the concrete API (see <>). A variety of tools for automatic code generation exist for the OpenAPI specification. This makes it very easy for client and server implementers to work with APIs defined using OpenAPI. However, as the OGC API - Processes Standard defines several JSON schemas and leaves the concrete data types for input and outputs open, the automatic code generation cannot be used to its full extent. To cope with this and thus make the implementation of clients / servers easier for those that are not familiar with OGC (API) standards, additional alternatives to the <> and the paths to processes and jobs are permitted. +This Standard uses the OpenAPI specification to define the JSON schemas and OpenAPI MAY also be used to describe the physical implementation of the API (see <>). A variety of tools for automatic code generation exist for the OpenAPI specification. This makes it very easy for client and server implementers to work with APIs defined using OpenAPI. However, as the OGC API - Processes Standard defines several JSON schemas and leaves the concrete data types for input and outputs open, the automatic code generation cannot be used to its full extent. To cope with this and thus make the implementation of clients / servers easier for those that are not familiar with OGC (API) Standards, additional alternatives to the <> and the paths to processes and jobs are permitted. The following permissions do not affect the mandatory core requirements. diff --git a/core/sections/clause_1_scope.adoc b/core/sections/clause_1_scope.adoc index e5c22b87..08d51de4 100644 --- a/core/sections/clause_1_scope.adoc +++ b/core/sections/clause_1_scope.adoc @@ -1,4 +1,4 @@ == Scope -This OGC Standard specifies a Web API that enables the execution of computing processes and the retrieval of metadata describing their purpose and functionality. Typically, these processes combine raster, vector, coverage and/or point cloud data with well-defined algorithms to produce new raster, vector, coverage and/or point cloud information. +The OGC API - Processes Standard (aka "Processes API") specifies requirements of a Web API that enables the execution of computing processes and the retrieval of metadata describing their purpose and functionality. Typically, these processes combine raster, vector, coverage and/or point cloud data with well-defined algorithms to produce new raster, vector, coverage and/or point cloud information. diff --git a/core/sections/clause_2_conformance.adoc b/core/sections/clause_2_conformance.adoc index 3b307ff7..8e49cd9d 100644 --- a/core/sections/clause_2_conformance.adoc +++ b/core/sections/clause_2_conformance.adoc @@ -2,7 +2,7 @@ [[sc_conformance]] == Conformance -This standard defines seven requirements / conformance classes. +This Standard defines seven requirements / conformance classes. The standardization targets of all conformance classes are "Web APIs." @@ -20,23 +20,23 @@ Two requirements classes depend on the _Core_ and specify representations for th The JSON encoding is mandatory. -The _Core_ does not mandate any encoding or format for the formal definition of the API. OpenAPI 3.0 specification is one option for defining the Processing API. As such a requirements class has been specified for OpenAPI 3.0, which depends on the requirements class _Core_: +The _Core_ does not mandate any encoding or format for the formal definition of the Processes API. OpenAPI 3.0 specification is one option for defining the Processes API. As such a requirements class has been specified for OpenAPI 3.0, which depends on the requirements class _Core_: * <>. -An implementation of the _Core_ requirements class may also decide to use other API definition representations in addition to, or instead of, an OpenAPI 3.0 definition. Examples for alternative API definitions: OpenAPI 2.0 (Swagger), future versions of the OpenAPI specification, an OWS Common 2.0 capabilities document or WSDL. +An implementation of the _Core_ requirements class may also decide to use other API definition representations in addition to, or instead of, an OpenAPI 3.0 definition. Examples for alternative API definitions: OpenAPI 2.0 (Swagger), future versions of the OpenAPI specification, an OWS Common 2.0 capabilities document, or WSDL. [NOTE] ==== OpenAPI 3.0 offers an open, powerful and vendor neutral description format. -While the use of OpenAPI 3.0 for the formal definition of the API is not mandatory, the requests/responses of the API specified in this standard are defined using OpenAPI 3.0 schemas. +While the use of OpenAPI 3.0 for the formal definition of the API is not mandatory, the requests/responses of the API specified in this Standard are defined using OpenAPI 3.0 schemas. See also the note regarding <> ==== -The _Core_ is intended to be a minimal useful API for the execution of processes in the geospatial domain. The Core is designed to map the operations of a Web Processing Service 2.0 instance. +An implementation of the _Core_ is intended to be a minimal useful API for the execution of processes in the geospatial domain. The Core is designed to map the operations of a Web Processing Service 2.0 instance. The _Core_ does not mandate the use of any specific process description to -specify the interface of a process. Instead this standard defines and +specify the interface of a process. Instead this Standard defines and recommends the use of the following conformance class: * <> @@ -54,7 +54,7 @@ Three additional conformance classes are specified that extend the basic functio Additional capabilities such as support for transactions, extended job monitoring, etc., may be specified in future parts of the OGC API - Processes series or as vendor-specific extensions. -Conformance with this standard SHALL be checked using all the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site. +Conformance with this Standard SHALL be checked using all the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site. .Conformance class URIs diff --git a/core/sections/clause_4_terms_and_definitions.adoc b/core/sections/clause_4_terms_and_definitions.adoc index 87eae1d7..6a00a309 100644 --- a/core/sections/clause_4_terms_and_definitions.adoc +++ b/core/sections/clause_4_terms_and_definitions.adoc @@ -12,10 +12,9 @@ A process p is a function that for each input returns a corresponding output p: X -> Y ++++ -where stem:[X] denotes the domain of arguments stem:[x] and stem:[Y] denotes the co-domain of values y. Within this specification, process arguments are referred to as process inputs and result values are referred to as process outputs. Processes that have no process inputs represent value generators that deliver constant or random process outputs. - -The term process is one of the most used terms both in the information and geosciences domain. If not stated otherwise, this specification uses the term process as an umbrella term for any algorithm, calculation or model that either generates new data or transforms some input data into output data as defined in section 4.1 of the WPS 2.0 standard. +where stem:[X] denotes the domain of arguments stem:[x] and stem:[Y] denotes the co-domain of values y. In this Standard, process arguments are referred to as process inputs and result values are referred to as process outputs. Processes that have no process inputs represent value generators that deliver constant or random process outputs. +The term "process" is one of the most used terms both in the information and geosciences domain. If not stated otherwise, this Standard uses the term process as an umbrella term for any algorithm, calculation or model that either generates new data or transforms some input data into output data as defined in section 4.1 of the OGC WPS 2.0 standard. ==== job @@ -28,7 +27,7 @@ JavaScript Object Notation is a lightweight data-interchange format. JSON is eas ==== Link -The term "link" is commonly used as substitute for URL or URI. In this standard, "link" refers to an element described by the schema for a link as shown at <>. This is a JSON element containing properties like "rel" (relation) and "href". The value of the "href" property is an URI. +The term "link" is commonly used as substitute for URL or URI. In this Standard, "link" refers to an element described by the schema for a link as shown at <>. This is a JSON element containing properties such as "rel" (relation) and "href". The value of the "href" property is an URI. ==== Link header diff --git a/core/sections/clause_5_conventions.adoc b/core/sections/clause_5_conventions.adoc index 5a4353e7..734b3eca 100644 --- a/core/sections/clause_5_conventions.adoc +++ b/core/sections/clause_5_conventions.adoc @@ -6,11 +6,11 @@ This section provides details and examples for any conventions used in the docum === Identifiers -The normative provisions in this specification are denoted by the URI +The normative provisions in this Standard are denoted by the URI http://www.opengis.net/spec/ogcapi-processes-1/1.0 -All requirements, permission, recommendations and conformance tests that appear in this document are denoted by partial URIs which are relative to this base. +All requirements, permission, recommendations, and conformance tests that appear in this document are denoted by partial URIs which are relative to this base. === Link relations @@ -25,7 +25,7 @@ The following https://www.iana.org/assignments/link-relations/link-relations.xht * **service-desc**: Identifies service description for the context that is primarily intended for consumption by machines. -** API definitions are considered service descriptions. +** In this Standard, https://swagger.io/specification/v3/[OpenAPI 3.0] is used to provide a formal, machine readable, description of the service but other API definition representations can also be used. * **service-doc**: Identifies service documentation for the context that is primarily intended for human consumption. @@ -35,7 +35,7 @@ The following https://www.iana.org/assignments/link-relations/link-relations.xht * **up**: Refers to a parent document in a hierarchy of documents. -In addition the following link relation types are used for which no applicable registered link relation type could be identified. +In addition, the following link relation types are used for which no applicable registered link relation type could be identified. * **http://www.opengis.net/def/rel/ogc/1.0/conformance**: Refers to a resource that identifies the specifications that the link's context conforms to. @@ -49,15 +49,22 @@ In addition the following link relation types are used for which no applicable r * **http://www.opengis.net/def/rel/ogc/1.0/results**: The target URI points to the results of a job. -Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API. +Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by an implementation of the Processes API. +=== Schemas + +Schemas defined in this Standard are defined using the https://json-schema.org/specification[JSON Schema] standard and are encoded using https://yaml.org/spec/1.2.2/[YAML] which is a human-friendly data serialization language. === Use of HTTPS -For simplicity, this document only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS. This is simply a shorthand notation for "HTTP or HTTPS". In fact, most servers are expected to use <>, not <>. +For simplicity, this Standard only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS. This is simply a shorthand notation for "HTTP or HTTPS". In fact, most servers are expected to use <>, not <>. -OGC Web API standards do not prohibit the use of any valid HTTP option. However, implementers should be aware that optional capabilities which are not in common use could be an impediment to interoperability. +OGC Web API Standards do not prohibit the use of any valid HTTP option. However, implementers should be aware that optional capabilities which are not in common use could be an impediment to interoperability. === HTTP URIs -This document does not restrict the lexical space of URIs used in the API beyond the requirements of the <> and <> IETF RFCs. If URIs include reserved characters that are delimiters in the URI subcomponent, these have to be percent-encoded. See Clause 2 of <> for details. +This Standard does not restrict the lexical space of URIs used in an implementation of the Processes API beyond the requirements of the <> and <> IETF RFCs. If URIs include reserved characters that are delimiters in the URI subcomponent, these must be percent-encoded. See Clause 2 of <> for details. + +=== APIs + +This Standard is primarily concerned with defining the components of a Processes API. That is an API that enables the execution of computing processes, the retrieval of metadata describing their purpose and functionality and the retrieval of the results of the process execution. The reader, however, should be cogniscant of the fact that an implementation of the Processes API as defined in this Standard may be embeded as part of a broader API. For example, a server may implement the https://docs.ogc.org/is/17-069r4/17-069r4.html#_references[Features] and Processes APIs and so common elements (such as the landing page) will contain components of both the https://docs.ogc.org/is/17-069r4/17-069r4.html#_references[Features API] and the Processes API defined in this Standard. When the term "API" is encountered in this Standard, the term is referring only to the components of a Processes API even though the Processes API may be part of a broader API. diff --git a/core/sections/clause_6_overview.adoc b/core/sections/clause_6_overview.adoc index 84306873..a88d7fbb 100644 --- a/core/sections/clause_6_overview.adoc +++ b/core/sections/clause_6_overview.adoc @@ -2,15 +2,15 @@ [[overview]] == Overview -The OGC API - Processes Standard builds on the WPS 2.0 Standard and is modularized. This means that there is a separation between +The OGC API - Processes Standard builds on the WPS 2.0 Standard and is modularized. This means that there is a separation between: -* Core requirements, that specify basic capabilities and can easily be mapped to existing OGC Web Processing Services; -* More advanced functionality, that is not specified in WPS 2.0. +* Core requirements, that specify basic capabilities and can easily be mapped to existing OGC Web Processing Services. +* More advanced functionality that is not specified in WPS 2.0. === Encodings -JSON is the encoding for requests and responses. The inputs and outputs of a process can be any format. The formats are defined at the time of job creation and are fixed for the specific job. +JSON is the encoding for requests and responses. The inputs and outputs of a process can be in any format. The formats are defined at the time of job creation and are fixed for the specific job. <> is recommended as HTML is the core language of the World Wide Web. A server that supports HTML will support browsing with a web browser diff --git a/core/sections/clause_7_core.adoc b/core/sections/clause_7_core.adoc index a5eaf264..e0ee58d6 100644 --- a/core/sections/clause_7_core.adoc +++ b/core/sections/clause_7_core.adoc @@ -1,7 +1,7 @@ == Requirements Class "Core" -The following section describes the core requirements class. +The following section describes the Core requirements class. === Overview @@ -10,21 +10,21 @@ include::../requirements/requirements_class_core.adoc[] A server that implements the OGC API - Processes Standard provides access to processes. -Each implementation of the OGC API - Processes Standard has a single `LandingPage` (path `/`) that provides links to +Each implementation of the OGC API - Processes Standard has a single `LandingPage` (path `/`) that provides links to: * The `APIDefinition` (no fixed path), * The `Conformance` statements (path `/conformance`), * The `processes` metadata (path `/processes`). -Note that additional requirements classes may introduce additional links for the landing page. +Note that additional requirements classes may introduce additional links for inclusion in the landing page. The `APIDefinition` describes the capabilities of the server that can be used by clients to connect to the server or by development tools to support the implementation of servers and clients. Accessing the `APIDefinition` using -HTTP GET returns a description of the API. +HTTP GET returns a description of the an API that includes the Processes API defined in this Standard by may include the description of a broader containing API. Accessing `Conformance` using HTTP GET returns a list of URIs of -requirements classes implemented by the server. +conformance classes implemented by the server. The list of processes contains a summary of each process offered by the OGC API - Processes implementation, including the link to a more detailed description of the process. @@ -40,7 +40,7 @@ After a process is finished (status = success/failed), the results/exceptions ca .Resources in the Core requirements class image::core/figures/PT1_FIG01.png[align="center"] -The OGC API - Processes Standard utilizes elements of the OGC API-Common standard. <> Identifies the API-Common Requirements Classes which are applicable to each section of this standard. +The OGC API - Processes Standard utilizes elements of the OGC API-Common Standard. <> Identifies the API-Common Requirements Classes which are applicable to each section of this Processes API Standard. [[mapping-to-common]] .Mapping API - Processes Sections to API-Common Requirements Classes @@ -58,8 +58,11 @@ The OGC API - Processes Standard utilizes elements of the OGC API-Common [[sc_landing_page]] === Retrieve the API landing page -The following section defines the requirements to retrieve an API landing page. +The following section defines the requirements to retrieve an API landing page that includes Processes API endpoint but may also include endpoints of a broader, containing, API. +In this Standard the term "API" is meant to indicate those elements a + +however, we will limit discussion to those endpoints defined in the Processes Standard but the reader should be cogniscent of the fact that the implemented API may be a broaded API that also contains Processes API components. ==== Operation @@ -72,12 +75,12 @@ include::../requirements/core/REQ_landingpage-success.adoc[] [NOTE] ==== -The term “_...based upon the OpenAPI 3.0 schema..._” used in the requirements of this specification means that OpenAPI 3.0 is used to define: +The term “_...based upon the OpenAPI 3.0 schema..._” used in the requirements of this Standard means that OpenAPI 3.0 is used to define: -* all the required properties of the respective request/response schema, -* and any optional properties of the respective request/response schema. +* All the required properties of the respective request/response schema, +* Any optional properties of the respective request/response schema. -It also means that unless explicitly excluded these schemas are extensible with additional properties not defined in the schema using the https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject[`additionalProperties`] mechanism defined in the https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md[OpenAPI 3.0 specification]. +It also means that unless explicitly excluded these OpenAPI schemas are extensible with additional properties not defined in the schema using the https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject[`additionalProperties`] mechanism defined in the https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md[OpenAPI 3.0 specification]. ==== .Schema for the landing page @@ -114,15 +117,11 @@ See <> for general guidance. [[sc_api_definition]] === Retrieve an API definition -The following section defines the requirements to retrieve an API definition. - +The following section defines the requirements to retrieve an API definition. This API may only implement components of the Processes API defined in this Standard but may define the implementation of a broader API into which the Processes API is embedded. ==== Operation -Every implementation of OGC API - Processes provides an API definition that describes the capabilities -of the server. This definition is used by developers to understand the API, -by software clients to connect to the server, or -by development tools to support the implementation of servers and clients. +Every implementation of OGC API - Processes must provide metadata that describe the functional capabilities of the server instance that the API definition provides access to. In this document, this is known as the "API definition". This definition is used by developers to understand the functionality provided by the API endpoing, so software clients can connect to the server, or by development tools to support the implementation of servers and clients. include::../requirements/core/REQ_api-definition-op.adoc[] @@ -144,23 +143,16 @@ content negotiation to select the desired representation. ==== Two common approaches are: -* an additional path for each encoding of each resource (this can be expressed, +* An additional path for each encoding of each resource (this can be expressed, for example, using format specific suffixes like ".html"); -* an additional query parameter (for example, "accept" or "f") that overrides +* An additional query parameter (for example, "accept" or "f") that overrides the Accept header of the HTTP request. ==== -The API definition document describes the API. In other words, -there is no need to include the `/api` operation in the API definition itself. - -The idea is that any implementation of OGC API - Processes can be used by developers that are familiar with -the API definition language(s) supported by the server. For example, if -an OpenAPI definition is used, it should be possible to create a working -client using the OpenAPI definition. The developer may need to learn a little -bit about geospatial data types, etc., but it should not be required to read -this standard to access the processes and results via the API. +The API definition document describes the API. In other words, there is no need to include the `/api` operation in the API definition itself. +The idea is that any implementation of OGC API - Processes can be used by developers that are familiar with the API definition language(s) supported by the server. For example, if an OpenAPI definition is used, it should be possible to create a working client using the OpenAPI definition. ==== Error situations @@ -171,9 +163,7 @@ See <> for general guidance. ==== Operation -To support "generic" clients for accessing servers implementing OGC API - Processes in general - and -not "just" a specific API / server, the server has to declare the -requirements classes it implements and conforms to. +To support "generic" clients for accessing servers implementing OGC API - Processes in general - and not "just" a specific API / server, the server must declare the requirements classes it implements and conforms to. include::../requirements/core/REQ_conformance-op.adoc[] @@ -215,11 +205,11 @@ This include the correct use of status codes, headers. etc. include::../recommendations/core/REC_http-head.adoc[] -Supporting the method HEAD in addition to GET can be useful for clients and is simple to implement. In particular, the HEAD method is useful in determine the size of a potential response. +Supporting the method HEAD in addition to GET can be useful for clients and is simple to implement. In particular, the HEAD method is useful in determining the size of a potential response. include::../recommendations/core/REC_content-length.adoc[] -Servers implementing https://docs.ogc.org/DRAFTS/17-069r4.html#cross_origin[CORS] will implement the method OPTIONS, too. +Servers implementing https://docs.ogc.org/DRAFTS/17-069r4.html#cross_origin[Cross-Origin Resource Sharing (CORS)] will also implement the OPTIONS method. [[http_status_codes]] ==== HTTP status codes @@ -239,11 +229,11 @@ outside of the server. |=== |Status code |Description |`200` |A successful request. -|`201` |The request was successful and one or more new resources have being created. +|`201` |The request was successful and one or more new resources have been created. |`204` |The request was successful but did not generate any content. |`400` |The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value. |`401` |The request requires user authentication. The response includes a `WWW-Authenticate` header field containing a challenge applicable to the requested resource. -|`403` |The server understood the request, but is refusing to fulfill it. While status code `401` indicates missing or bad authentication, status code `403` indicates that authentication is not the issue, but the client is not authorized to perform the requested operation on the resource. +|`403` |The server understood the request but is refusing to fulfill it. While status code `401` indicates missing or bad authentication, status code `403` indicates that authentication is not the issue, but the client is not authorized to perform the requested operation on the resource. |`404` |The requested resource does not exist on the server. For example, a path parameter had an incorrect value. |`405` |The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests. |`406` |The `Accept` header submitted in the request did not support any of the media types supported by the server for the requested resource. @@ -280,7 +270,7 @@ include::../recommendations/core/REC_html.adoc[] [[sc_limit_parameter]] === Limit parameter -Several resources defined in this specification (see <>, <>) use the `limit` parameter to control the number of results that are presented in a response. +Several resources defined in this Standard (see <>, <>) use the `limit` parameter to control the maximum number of results that are presented in a response page. * The client can request a limit it is interested in. @@ -288,31 +278,31 @@ Several resources defined in this specification (see <> or <>): +As an example, using the default/maximum values of 10/1000 from the OpenAPI fragment in requirement <> or <>: -* If you ask for 10 results, you will get 0 to 10 (as requested) and if there are more, a `next` link; +* If the client asks for 10 results, the client will get 0 to 10 (as requested) and if there are more, a `next` link; -* If you don't specify a limit, you will get 0 to 10 (default) and if there are more, a `next` link; +* If the client does not specify a limit, the client will get 0 to 10 (default) and if there are more, a `next` link; -* If you ask for 5000 results, you might get up to 1000 (server-limited) and if there are more, a `next` link; +* If the client asks for 5000 results, the client might get up to 1000 results (server-limited) and if there are more, a `next` link; -* If you follow the next link from the previous response, you might get up to 1000 additional results and if there are more, a `next` link. +* If the client follows the next link from the previous response, the client might get up to 1000 additional results and if there are more, a `next` link. -This document make requirements and recommendations about links in general and the `next` link in particular at the appropriate resource end points. +This Standard provides requirements and recommendations about links in general and the `next` link in particular at the appropriate resource end points. [[next-link-discussion]] -This document does not mandate any specific implementation approach for the `next` links. +This Stadard does not mandate any specific implementation approach for the `next` links. -An implementation could use opaque links that are managed by the server. It is up to the server to determine how long these links can be dereferenced. Clients should be prepared to receive a 404 response. +An implementation of the Processes API could use opaque links that are managed by the server. It is up to the server to determine how long these links can be dereferenced. Clients should be prepared to receive a 404 response. Another implementation approach is to use an implementation-specific parameter that specifies the index within the result set from which the server begins presenting results in the response, like `offset` or the `startIndex` parameter that was used in <>. -The API will return no `next` link, if it has returned all selected results, and the server knows that. However, the server may not be aware that it has already returned all selected results. For example, if the request states `limit=10` and the query to the backend returns 10 results, the server may not know, if there are more results or not (in most cases there will be more results), unless the total number of results is also computed, which may be too costly. The server will then add the next link, and if there are no more results, dereferencing the next link will return an empty results list and no next link. This behavior is consistent with the statements above. +An implementation of the Processes API will return no `next` link, if all selected results have been returned, and the server knows for certain that there are not further results to be presented. However, in some cases, the server may not be aware that it has already returned all selected results. For example, if the request states `limit=10` and the query to the backend returns exactly 10 results. The server may not know if there are more results or not (in most cases there will be more results), unless the total number of results is also computed, which may be too costly. The server will then prudently add the next link, and if there are no more results, dereferencing the next link will return an empty results list and no next link. This behavior is consistent with the statements above. -Clients should not assume that paging is safe against changes to dataset while a client iterates through `next` links. If a server provides opaque links these could be safe and maintain the state during the original request. Using a parameter for the start index, however, will not be safe. +Clients should not assume that paging is safe against changes to the dataset being accesses while a client iterates through `next` links. If a server provides opaque links these could be safe and maintain the state during the original request. Using a parameter for the start index, however, will not be safe. [[prev-link-discussion]] -This document also makes recommendations about include a `prev` link at the appropriate resource end points. Providing `prev` links supports navigating back and forth between pages, but depending on the implementation approach it may be too complex to implement. +This Standard also has recommendations about including a `prev` link at the appropriate resource end points. Providing `prev` links supports navigating back and forth between pages, but depending on the implementation approach, it may be too complex to implement. === Link headers @@ -322,8 +312,7 @@ include::../recommendations/core/REC_link-header.adoc[] [[sc_process_list]] === Retrieve a process list -The following section defines the requirements to retrieve the available processes offered by the server. - +The following section defines the requirements to retrieve the available processes offered by an implmentation of the Processes API. It should be noted that the number of processes offered via the API may be very different than the number of processes offer by a back-end system upon which the Processes API is implemented. ==== Operation @@ -738,13 +727,13 @@ and an instance of this process input in an execute request might be: ] ---- -In this case, the `mediaType` parameter is used to indicate the specific type of geometry being passed as input in each case; GML Polygon for the first element of the array and GeoJSON Polygon for the second element. +In this case, the `mediaType` parameter is used to indicate the specific type of geometry being passed as input in each case: GML Polygon for the first element of the array and GeoJSON Polygon for the second element. ==== [[binary-value]] *_Binary values:_* -In some cases, for example in order to pass through firewalls, binary input values need to be encoded in-line in an execute request as a string. +In some cases, for example to pass through firewalls, binary input values need to be encoded in-line in an execute request as a string. [[binary-input-value-schema]] .Schema for an in-line binary value @@ -760,7 +749,7 @@ include::../requirements/core/REQ_process-execute-input-inline-binary.adoc[] .Binary value examples. ==== -This is an example of an image process input whose media type is defined in the +Below is an example of an image process input whose media type is defined in the <>. The schema definition for this process input might be: [source,json] @@ -828,15 +817,15 @@ include::../../openapi/schemas/processes-core/bbox.yaml[] NOTE: This schema can also be obtained from https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/bbox.yaml[`bbox.yaml`]. -This schema is meant to be a template for defining bounding box process inputs. If the specified `default` and `enum` are suitable for your purposes then you can reference this file directly in your process description. +This schema is meant to be a template for defining bounding box process inputs. If the specified `default` and `enum` are suitable for the client's requirements then this file can be referenced directly in the process description. include::../recommendations/core/PER_process-execute-input-inline-bbox.adoc[] -NOTE: The `crs` property has been defined using an `anyOf` of either an enumeration or a generic URI string to allow execution requests making use of a CRS other than CRS84 and CRS84h that may be supported by the server to validate with the canonical OGC schema. +NOTE: The `crs` property is defined using an `anyOf` of either an enumeration or a generic URI string to allow execution requests making use of a CRS other than CRS84 and CRS84h. These may be supported by the server to validate against the canonical OGC schema. *_Input validation_* -Process inputs in an execute request and the corresponding process input definition in the <> have a validation relationship. That is to say, that the schema of a process input definition from the <> can be used to validate the component of the corresponding process input value in an execute request that is an instance of <>. +Process inputs in an execute request and the corresponding process input definition in the <> have a validation relationship. That is to say, the schema of a process input definition from the <> can be used to validate the component of the corresponding process input value in an execute request that is an instance of <>. [%unnumbered] ==== @@ -899,7 +888,7 @@ and the following instance in an execute request: The process input value in this execute request is an instance of a <>. -For the purposes of validation, the server need only validate the component of the <> that is an instance of <> against the `schema` fragment from the <>. Specifically, the validation target is: +For the purposes of validation, the server needs to only validate the component of the <> that is an instance of <> against the `schema` fragment from the <>. Specifically, the validation target is: [source,json] ---- @@ -920,7 +909,7 @@ include::../requirements/core/REQ_process-execute-input-validation.adoc[] A process may be executed synchronously or asynchronously. -In which of these two modes a server responds is a function of the job control options specified in the <> and the presence or absence of the HTTP `Prefer` header (http://tools.ietf.org/rfc/rfc7240.txt[IETF RFC 7240]). +Which mode a server responds with is a function of the job control options specified in the <> and the presence or absence of the HTTP `Prefer` header (http://tools.ietf.org/rfc/rfc7240.txt[IETF RFC 7240]). include::../requirements/core/REQ_process-execute-default-execution-mode.adoc[] @@ -951,7 +940,7 @@ A process output can be defined in the <> (synchronous or asynchronous), -* the number of outputs requested, -* the negotiated content type for the response (via the https://www.rfc-editor.org/rfc/rfc2616#section-14.1[HTTP Accept] header), -* and any negotiated client preferences (via the HTTP Prefer header). +* The <> (synchronous or asynchronous), +* The number of outputs requested, +* The negotiated content type for the response (via the https://www.rfc-editor.org/rfc/rfc2616#section-14.1[HTTP Accept] header), +* Any negotiated client preferences (via the HTTP Prefer header). The following table maps the possible responses based on the combinations of these execute parameters. The column headers denote: . *Negotiated execute mode*: see <> -. *Requested # outputs*: the number of output requested in the <> -. *Return preference*: the negotiated <> -. *Response HTTP code*: the https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1[HTTP status code] that the server should generate in this context -. *Response headers*: any required https://datatracker.ietf.org/doc/html/rfc2616#section-14[HTTP headers] that the server must include in this context -. *Response media type*: the value of the HTTP `Content-Type` header that the server should generate in this context -. *Response body*: a description of the content of the response body in this context -. *Req./Rec./Perm.*: the corresponding requirements/recommendations/permission as per this specification +. *Requested # outputs*: The number of output requested in the <> +. *Return preference*: The negotiated <> +. *Response HTTP code*: The https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1[HTTP status code] that the server should generate in this context. +. *Response headers*: Any required https://datatracker.ietf.org/doc/html/rfc2616#section-14[HTTP headers] that the server must include in this context. +. *Response media type*: The value of the HTTP `Content-Type` header that the server should generate in this context. +. *Response body*: A description of the content of the response body in this context. +. *Req./Rec./Perm.*: The corresponding requirements/recommendations/permission as per this Standard. [[table_core_execute_responses]] .Execute responses based on number of requested outputs, request HTTP headers and the size of output values. @@ -1053,7 +1042,7 @@ The following table maps the possible responses based on the combinations of the [NOTE] ==== -This table shows all possible combinations of execute parameters that are specified by this standard. Not all of these combinations need to be implemented by a server conforming to this standard. For example, a server that only offers processes that can be executed synchronously does not need to implement any of the asynchronous requirements. +This above table shows all possible combinations of execute parameters that are specified by this Standard. Not all these combinations need to be implemented by a server conforming to this Standard. For example, a server that only offers processes that can be executed synchronously does not need to implement any of the asynchronous requirements. ==== [[sync_note_3]] @@ -1090,7 +1079,7 @@ include::../../openapi/schemas/processes-core/results.yaml[] NOTE: This schema can also be obtained from https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/results.yaml[`results.yaml`]. -This schema defines a map using the respective output identifier as the key. The value of an output can be returned as an in-line value or by reference. +The https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/results.yaml[`results.yaml`] schema defines a map using the respective output identifier as the key. The value of an output can be returned as an in-line value or by reference. ===== Response requesting a single processing output @@ -1119,7 +1108,7 @@ include::../recommendations/core/PER_process-execute-success-sync-many-other-for ===== Job creation on synchronous process execution -This specification does not mandate that servers create a job as a result of executing a process synchronously. However the following permission is given: +This Standard does not mandate that servers create a job as a result of executing a process synchronously. However, the following permission is given: include::../recommendations/core/PER_process-execute-sync-job.adoc[] @@ -1173,7 +1162,7 @@ include::../../openapi/schemas/processes-core/statusCode.yaml[] NOTE: This schema can also be obtained from https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/statusCode.yaml[`statusCode.yaml`]. -The job status information includes several optional date-time fields that represent milestones in the life cycle of a job. The following are recommended for servers that decide to populate some or all of these date-time fields: +The job status information includes several optional date-time fields that represent milestones in the life cycle of a job. The following are recommended for servers that decide to populate some or all these date-time fields: include::../recommendations/core/REC_job-status.adoc[] @@ -1211,9 +1200,9 @@ include::../requirements/core/REQ_job-exception-no-such-job.adoc[] A process can generate zero or more outputs. This clause specifies how: -* processing results can be retrieved individually in a single request, -* a subset of processing results can be retrieved in a single request, -* or all processing results can be retrieved in a single request. +* Processing results can be retrieved individually in a single request, +* A subset of processing results can be retrieved in a single request, +* All processing results can be retrieved in a single request. [[sc_retrieve_job_results_one]] ==== Retrieving results individually @@ -1243,26 +1232,26 @@ include::../requirements/core/REQ_job-results-param-outputs-empty.adoc[] ===== Overview -The manner in which a server responds when retrieving job results depends on: +The way a server responds when retrieving job results depends on: -* the number of outputs requested, -* the negotiated content type for the response (via the https://www.rfc-editor.org/rfc/rfc2616#section-14.1[HTTP Accept] header) or lack thereof, -* and any negotiated client preferences (via the HTTP Prefer header). +* The number of outputs requested, +* The negotiated content type for the response (via the https://www.rfc-editor.org/rfc/rfc2616#section-14.1[HTTP Accept] header) or lack thereof, +* Any negotiated client preferences (via the HTTP Prefer header). The following table maps the possible responses based on the combinations of these execute parameters. The column headers in the following table denote: -. *Requested # outputs*: the number of outputs requested in the <> -. *Access path*: the API endpoint from which the result(s) can be retrieved -. *Return preference*: the negotiated <> -. *Response HTTP code*: the https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1[HTTP status code] that the server should generate in this context -. *Response media type*: the value of the HTTP `Content-Type` header that the server should generate in this context -. *Response body*: a description of the content of the response body in this context -. *Req./Rec./Perm.*: the corresponding requirements/recommendations/permission as per this specification +. *Requested # outputs*: The number of outputs requested in the <>. +. *Access path*: The API endpoint from which the result(s) can be retrieved. +. *Return preference*: The negotiated <>. +. *Response HTTP code*: The https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1[HTTP status code] that the server should generate in this context. +. *Response media type*: The value of the HTTP `Content-Type` header that the server should generate in this context. +. *Response body*: A description of the content of the response body in this context. +. *Req./Rec./Perm.*: The corresponding requirements/recommendations/permission as per this Standard. [[table_core_getresults_responses]] -.Table mapping get results responses based on the input parameter values used on the original execute request. +.Table mapping `get` results responses based on the input parameter values used on the original execute request. [cols=7,options="header"] |=== |Requested # outputs diff --git a/core/sections/clause_8_ogc-process-description.adoc b/core/sections/clause_8_ogc-process-description.adoc index 3ef14723..5c22f002 100644 --- a/core/sections/clause_8_ogc-process-description.adoc +++ b/core/sections/clause_8_ogc-process-description.adoc @@ -10,12 +10,14 @@ class. include::../requirements/requirements_class_ogc-process-description.adoc[] -The OGC process description is an information model that may be used to specify the interface of a process. This model is an evolution of the process description model originally defined in the http://docs.opengeospatial.org/is/14-065/14-065.html[OGC WPS 2.0.2 Interface Standard] but also includes elements of the http://spec.openapis.org/oas/v3.0.3[OpenAPI Specification]. Specifically, this process description languages uses https://json-schema.org/draft/2020-12/json-schema-core.html[JSON Schema] fragments to define the input and output parameters of a process. As such, this process description provides a bridge from legacy implementations to the OGC API Framework. +The OGC process description is an information model that may be used to specify the interface of a process. This model is an evolution of the process description model originally defined in the http://docs.opengeospatial.org/is/14-065/14-065.html[OGC WPS 2.0.2 Interface Standard] but also includes elements of the http://spec.openapis.org/oas/v3.0.3[OpenAPI Specification]. Specifically, this process description languages uses https://json-schema.org/draft/2020-12/json-schema-core.html[JSON Schema] fragments to define the input and output parameters of a process. As such, this process description provides a bridge from legacy implementations to using the OGC API Framework. + +NOTE: The use of other schema languages for describing the interface to a process is possible but is outside the scope of this Standards. The use of other schemas languages could be described in another Part of the OGC API - Processes series of standards. The process description allows the following information to be specified: * An identifier for the process -* Descriptive metadata about the process; +* Descriptive metadata about the process: ** A title ** A narrative description of the process ** Keywords that can be associated with the process @@ -24,7 +26,7 @@ The process description allows the following information to be specified: * A description of each process output specified using a https://json-schema.org/draft/2020-12/json-schema-core.html[JSON Schema] fragment. * A job control specification that indicates whether the process can be invoked synchronously, asynchronously, or either. * An output transmission specification that indicates how the results of a process are retrieved; either by value or by reference -* A section for additional parameters that are intended for communities of use to extend the process description as required +* A section for additional parameters that are intended for communities of use to extend the process description as required. The following clause defines a JSON-encoding of the OGC process description. @@ -91,7 +93,7 @@ The following JSON Schema fragment illustrates how to define an input of mixed t include::../recommendations/ogc-process-description/REC_format-key.adoc[] -The <> defines a https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.7[set of values] for the `format` key. This specification extends this list by defining the following additional key values for use specifically in OGC process descriptions. +The <> defines a https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.7[set of values] for the `format` key. The Process API Standard extends this list by defining the following additional key values for use specifically in OGC process descriptions. [[format-key-values]] .Additional values for the JSON schema format key for OGC Process Description diff --git a/core/sections/clause_9_security-considerations.adoc b/core/sections/clause_9_security-considerations.adoc index 45962ee0..64daeea0 100644 --- a/core/sections/clause_9_security-considerations.adoc +++ b/core/sections/clause_9_security-considerations.adoc @@ -2,7 +2,7 @@ [[sc_security_considerations]] == Security Considerations -The OGC API - Processes Standard specifies a Web API that enables the execution of computing processes, the retrieval of metadata describing their purpose and functionality and the retrieval of the results of the process execution. The API makes use of different HTTP methods, namely GET, POST and DELETE. (Note that future extensions could introduce additional HTTP methods.) +The OGC API -Processes Standard makes use of different HTTP methods, namely GET, POST and DELETE. (Note that future extensions could introduce additional HTTP methods.) HTTP methods can be classified as @@ -37,7 +37,7 @@ Requirements class "Job list" * <> -The following API operations use unsafe HTTP methods, modify resources and therefore require special attention: +The following API - Processes operations use unsafe HTTP methods, modify resources and therefore require special attention: Requirements class "Core": @@ -50,7 +50,7 @@ Requirements class "Dismiss" === Operations using HTTP GET -Most of the operations defined in this standard are use the safe HTTP GET operation. However, the resources that are returned by these operations contain information that could be used to exploit the API. <> gives an overview of the resources specified in this standard and what kind of information they contain. +Most of the operations defined in the API - Processes Standard use the safe HTTP GET operation. However, the resources that are returned by these operations contain information that could be used to exploit implementations of the Processes API. <> gives an overview of the resources specified in this standard and what kind of information they contain. [[table_core_safe_operations_security]] @@ -68,15 +68,15 @@ Most of the operations defined in this standard are use the safe HTTP GET operat |=== -The resources and contained information in more detail: +The following is more detailed information on the resources: -* The landing page contains links to the API endpoints and so leads to all other resources the API offers. +* The landing page includes links to endpoints that are not defined in the API - Processes Standard and so leads to all the other resources that the containing API offers. * The list of conformance classes could contain information about extensions like "dismiss" that pose additional security issues. * The process list contains process identifiers and links to the respective process descriptions. -* The process description contains all necessary information needed to execute a process. This information can be used to send an JSON execute request to the API that will pass initial sanity checks, for example checks for the correct input/output identifiers. If this barrier is taken by an attacker, issues as discussed in section <> can occur. +* The process description contains all necessary information needed to execute a process. This information can be used to send an JSON execute request to the Process API that will pass initial sanity checks, for example checks for the correct input/output identifiers. If this barrier is taken by an attacker, issues as discussed in section <> can occur. * The job status info contains not only status information, but for finished processes also links to results / exceptions. The results of a process execution are a valuable resource as well as the exceptions that could contain hints about why the execution has failed. @@ -97,8 +97,8 @@ The retrieval of the job list of a process returns the job ids and links to the The execute operation uses HTTP POST to create new processing jobs (process executions). As discussed above, the HTTP POST method is not safe and it poses the following threats if misused: -* The processing can use up considerable server resources, for example computing time, network traffic (when accessing referenced inputs) or storage space for inputs and outputs. -* Malicious inputs can be provided. Either inline in the execute request JSON or referenced. +* The processing can require considerable server resources, for example computing time, network traffic (when accessing referenced inputs) or storage space for inputs and outputs. +* Malicious inputs can be provided either inline in the execute request JSON or by reference by providing URIs to input values in the execute request JSON. [[table_core_execute_operation_security]] .Requirements class 'Core' - Overview of the execute operation and returned sensitive information @@ -110,7 +110,7 @@ The execute operation uses HTTP POST to create new processing jobs (process exec |=== -The ids that are used for new jobs and that are returned in the status info document should be created in a non-guessable way, for example using UUIDs. This will prevent random attempts to get job status information, results / exceptions or even cancel jobs / delete job artifacts. +The new job ids that are returned in the status info document should be created in a non-guessable way, for example using UUIDs. This will prevent random attempts to get job status information, results / exceptions or even cancel jobs / delete job artifacts. include::../recommendations/job-list/REC_access-control-job-list.adoc[] @@ -123,4 +123,4 @@ The optional dismiss extension uses the HTTP DELETE method and can be used to * Cancel a running job, and * Remove artifacts of a finished job. -Both usages pose security related issues. The cancellation of a running job (if not done on purpose) is wasting the resources that the job has used until it was cancelled. The same goes for the unwanted removal of artifacts of a finished job. If the dismiss extension is implemented, access control for the operation should be considered. The dismiss operation is idempotent, as it is specified by this standard to be called using a specific job identifier. The first dismiss request to that identifier will result in a HTTP 200 (OK) status code. Continued dismiss requests using the same identifier result in a HTTP 410 (Gone) error code, but nothing else is changed on the server. A successful dismiss request returns a status info document containing the job identifier and the status "dismissed". This status info document has no further security implications. +Both usages pose security related issues. The cancellation of a running job (if not done on purpose) is wasting the resources that the job used prior to being cancelled. The same issue applies to the unwanted removal of artifacts of a finished job. If the dismiss extension is implemented, access control for the operation should be considered. The dismiss operation is idempotent, as it is specified by this Standard to be called using a specific job identifier. The first dismiss request to that identifier will result in a HTTP 200 (OK) status code. Continued dismiss requests using the same identifier result in a HTTP 410 (Gone) error code, but nothing else is changed on the server. A successful dismiss request returns a status info document containing the job identifier and the status "dismissed". This status info document has no further security implications. diff --git a/openapi/schemas/common-core/landingPage.yaml b/openapi/schemas/common-core/landingPage.yaml index 53e15d35..e17c59eb 100644 --- a/openapi/schemas/common-core/landingPage.yaml +++ b/openapi/schemas/common-core/landingPage.yaml @@ -10,7 +10,7 @@ properties: example: Example server implementing the OGC API - Processes 1.0 Standard attribution: type: string - title: attribution for the API + title: attribution for the Processes API description: The `attribution` should be short and intended for presentation to a user, for example, in a corner of a map. Parts of the text can be links to other resources if additional information is needed. The string can include HTML markup. links: type: array