Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify outputs #434

Merged
merged 2 commits into from
Aug 5, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions core/abstract_tests/ATS_class_core.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ conformance-test:: /conf/core/process-execute-default-outputs
conformance-test:: /conf/core/process-execute-input-array
conformance-test:: /conf/core/process-execute-input-inline-bbox
conformance-test:: /conf/core/process-execute-input-inline-binary
conformance-test:: /conf/core/process-execute-input-inline-mixed
conformance-test:: /conf/core/process-execute-input-inline-multiple-type
conformance-test:: /conf/core/process-execute-input-inline-object
conformance-test:: /conf/core/process-execute-inputs
conformance-test:: /conf/core/process-execute-input-validation
Expand Down Expand Up @@ -116,7 +116,7 @@ include::core/ATS_process-execute-input-array.adoc[]

include::core/ATS_process-execute-input-inline-object.adoc[]

include::core/ATS_process-execute-input-inline-mixed.adoc[]
include::core/ATS_process-execute-input-inline-multiple-types.adoc[]

include::core/ATS_process-execute-input-inline-binary.adoc[]

Expand Down
8 changes: 4 additions & 4 deletions core/abstract_tests/ATS_class_ogc-process-description.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@ identifier:: http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/ogc-process
subject:: <<rc_ogc-process-description,http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/ogc-process-description>>
classification:: Target Type:Web API
conformance-test:: /conf/ogc-process-description/input-def
conformance-test:: /conf/ogc-process-description/input-mixed-type
conformance-test:: /conf/ogc-process-description/input-multiple-types
conformance-test:: /conf/ogc-process-description/inputs-def
conformance-test:: /conf/ogc-process-description/json-encoding
conformance-test:: /conf/ogc-process-description/links
conformance-test:: /conf/ogc-process-description/output-def
conformance-test:: /conf/ogc-process-description/output-mixed-type
conformance-test:: /conf/ogc-process-description/output-multiple-types
conformance-test:: /conf/ogc-process-description/outputs-def
====

Expand All @@ -24,10 +24,10 @@ include::ogc-process-description/ATS_inputs-def.adoc[]

include::ogc-process-description/ATS_input-def.adoc[]

include::ogc-process-description/ATS_input-mixed-type.adoc[]
include::ogc-process-description/ATS_input-multiple-types.adoc[]

include::ogc-process-description/ATS_outputs-def.adoc[]

include::ogc-process-description/ATS_output-def.adoc[]

include::ogc-process-description/ATS_output-mixed-type.adoc[]
include::ogc-process-description/ATS_output-multiple-types.adoc[]
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
[[ats_core_process-execute-input-inline-mixed]]
[[ats_core_process-execute-input-inline-multiple-types]]

[abstract_test]
====
[%metadata]
identifier:: /conf/core/process-execute-input-inline-mixed
target:: /req/core/process-execute-input-inline-mixed
test-purpose:: Validate that inputs of mixed content encoded in-line in an execute request are correctly processed.
identifier:: /conf/core/process-execute-input-inline-multiple-types
target:: /req/core/process-execute-input-inline-multiple-types
test-purpose:: Validate that inputs of multiple types encoded in-line in an execute request are correctly processed.
test-method::
+
--
1. Get a description of each process offered by the server using test <<ats_core_process-description,/conf/core/process-description>>.

2. Inspect the description of each process and identify the subset of processes that have inputs of mixed content using the `oneOf[]` JSON Schema construct to define several alternate input value schemas.
2. Inspect the description of each process and identify the subset of processes that have inputs of multiple types using the `oneOf[]` JSON Schema construct to define several alternate input value schemas.

3. For each identified process construct an execute request according to test <<ats_core_process-execute-request,/conf/core/process-execute-request>> taking care to encode the identified mix-content inputs in-line in the execute request according to requirement <<req_core_process-execute-input-inline-mixed,/req/core/process-execute-input-inline-mixed>>.
3. For each identified process construct an execute request according to test <<ats_core_process-execute-request,/conf/core/process-execute-request>> taking care to encode the identified mix-content inputs in-line in the execute request according to requirement <<req_core_process-execute-input-inline-multiple-types,/req/core/process-execute-input-inline-multiple-types>>.

4. Verify that each process executes successfully according to the relevant requirement (one of: <<ats_core_process-execute-success-async,/req/core/process-execute-success-async>>, <<ats_core_process-execute-sync-many-json,/req/core/process-execute-sync-many-json>>, <<ats_core_process-execute-sync-one,/req/core/process-execute-sync-one>>, <<ats_core_process-execute-sync-one-default-content,/req/core/process-execute-sync-one-default-content>>) base on the combination of execute parameters.
--
Expand Down
2 changes: 1 addition & 1 deletion core/abstract_tests/core/ATS_process-execute-inputs.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ test-purpose:: Validate that servers can accept input values both inline and by
test-method::
+
--
1. Verify that the server passes tests <<ats_core_process-execute-input-inline-binary,/conf/core/process-execute-input-inline-binary>>, <<ats_core_process-execute-input-inline-mixed,/conf/core/process-execute-input-inline-mixed>>, <<ats_core_process-execute-input-inline-object,/conf/core/process-execute-input-inline-object>>, <<ats_core_process-execute-input-inline-bbox,/conf/core/process-execute-input-inline-bbox>> .
1. Verify that the server passes tests <<ats_core_process-execute-input-inline-binary,/conf/core/process-execute-input-inline-binary>>, <<ats_core_process-execute-input-inline-multiple-types,/conf/core/process-execute-input-inline-multiple-types>>, <<ats_core_process-execute-input-inline-object,/conf/core/process-execute-input-inline-object>>, <<ats_core_process-execute-input-inline-bbox,/conf/core/process-execute-input-inline-bbox>> .

2. For each test, specify the input value in-line in the execute request.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
[[ats_ogc-process-description_input-mixed-type]]
[[ats_ogc-process-description_input-multiple-types]]

[abstract_test]
====
[%metadata]
identifier:: /conf/ogc-process-description/input-mixed-type
target:: /req/ogc-process-description/input-mixed-type
test-purpose:: Validate that each input of mixed type complies with the required structure and contents.
identifier:: /conf/ogc-process-description/input-multiple-types
target:: /req/ogc-process-description/input-multiple-types
test-purpose:: Validate that each input of multiple type complies with the required structure and contents.
test-method::
+
--
1. Retrieve a description of each process according to test <<ats_core_process-description,/conf/core/process-description>>.

2. For each process identify if the process has one or more inputs of mixed type.
2. For each process identify if the process has one or more inputs of multiple types.

3. For each sub-schema of each identified input, 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].
--
Expand Down
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
[[ats_ogc-process-description_output-mixed-type]]
[[ats_ogc-process-description_output-multiple-types]]

[abstract_test]
====
[%metadata]
identifier:: /conf/ogc-process-description/output-mixed-type
target:: /req/ogc-process-description/output-mixed-type
test-purpose:: Validate that each output of mixed type complies with the required structure and contents.
identifier:: /conf/ogc-process-description/output-multiple-types
target:: /req/ogc-process-description/output-multiple-types
test-purpose:: Validate that each output of multiple types complies with the required structure and contents.
test-method::
+
--
1. Retrieve a description of each process according to test <<ats_core_process-description,/conf/core/process-description>>.

2. For each process identify if the process has one or more output of mixed type denoted by using the `oneOf` JSON Schema keyword.
2. For each process identify if the process has one or more output of multiple types 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].
--
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[[per_core_process-execute-multiple-output-pkg]]
[permission]
====
[%metadata]
identifier:: /per/core/process-execute-multiple-output-pkg

A server MAY, through content negotiation, respond with something other than that specified by requirement <<req_core_process-execute-sync-many-json,/req/core/process-execute-sync-many-json>>. A server MAY, for example, respond with a https://www.iso.org/standard/60101.html[ZIP] file or a https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html[multi-part MIME] document containing all the requested output values.
====
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_access-control-expose-headers]]
[recommendation,type="general",id="/rec/core/access-control-expose-headers",label="/rec/core/access-control-expose-headers"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/access-control-expose-headers

If the server is intended to be accessed from the browser and if Cross-origin resource sharing is supported, the `Access-Control-Expose-Headers` header SHOULD be used and the header SHOULD contain the value `location` to enable the browser to access the `location` header of the response.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_api-definition-oas.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_api_definition-oas]]
[recommendation,type="general",id="/rec/core/api-definition-oas",label="/rec/core/api-definition-oas"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/api-definition-oas

If the API definition document is defined using the OpenAPI Specification 3.0, the document SHOULD conform to the <<rc_oas30,OpenAPI Specification 3.0 requirements class>>.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_content-length.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_content-length]]
[recommendation,type="general",id="/rec/core/content-length",label="/rec/core/content-length"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/content-length

The server SHOULD include the HTTP 1.1 `Content-Length` header in all responses.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_cross-origin.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_cross-origin]]
[recommendation,type="general",id="/rec/core/cross-origin",label="/rec/core/cross-origin"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/cross-origin

If the server is intended to be accessed from the browser, cross-origin requests SHOULD be supported. Note that support can also be added in a proxy layer on top of the server.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_html.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_html]]
[recommendation,type="general",id="/rec/core/html",label="/rec/core/html"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/html

To support browsing an implementation of OGC API - Processes with a web browser and to enable search engines to crawl and index a process, implementations SHOULD consider to support an HTML encoding.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_http-head.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_http-head]]
[recommendation,type="general",id="/rec/core/http-head",label="/rec/core/http-head"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/http-head

The server SHOULD support the HTTP 1.1 method HEAD for all resources that support the method GET.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_job-links.adoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_job-links]]
[recommendation,type="general",id="/rec/core/job-links",label="/rec/core/job-links"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/job-links

[.component,class=part]
--
Servers SHOULD include a link (`rel="monitor"`) pointing to a resource that can be used to monitor the progress of a job.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_job-results-async-many-json-prefer-minimal]]
[recommendation,type="general",id="/rec/core/job-results-async-many-json-prefer-minimal",label="/rec/core/job-results-async-many-json-prefer-minimal"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/job-results-async-many-json-prefer-minimal

[.component,class=conditions]
--
The negotiated https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[return preference] is `minimal`.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_job-results-async-many-json-prefer-none]]
[recommendation,type="general",id="/rec/core/job-results-async-many-json-prefer-none",label="/rec/core/job-results-async-many-json-prefer-none"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/job-results-async-many-json-prefer-none

[.component,class=conditions]
--
A return preference is _**not**_ specified via the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[`prefer`] header.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_job-results-async-many-json-prefer-representation]]
[recommendation,type="general",id="/rec/core/job-results-async-many-json-prefer-representation",label="/rec/core/job-results-async-many-json-prefer-representation"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/job-results-async-many-json-prefer-representation

[.component,class=conditions]
--
The negotiated https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[return preference] is `representation`.
Expand Down
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_job-status.adoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_job-status]]
[recommendation,type="general",id="/rec/core/job-status",label="/rec/core/job-status"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/job-status

[.component,class=part]
--
Servers SHOULD set the value of the `processID` field if it is known.
Expand Down
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_link-header.adoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_link-header]]
[recommendation,type="general",id="/rec/core/link-header",label="/rec/core/link-header"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/link-header

[.component,class=part]
--
Links included in payload of responses SHOULD also be included as `Link` headers in the HTTP response according to <<rfc8288,RFC 8288, Clause 3>>.
Expand Down
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_ogc-process-description.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_ogc-process-description]]
[recommendation,type="general",id="/rec/core/ogc-process-description",label="/rec/core/ogc-process-description"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/ogc-process-description

Implementations SHOULD consider supporting the <<ogc_process_description,OGC process description>>.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_problem-details.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_problem-details]]
[recommendation,type="general",id="/rec/core/problem-details",label="/rec/core/problem-details"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/problem-details

A server SHOULD include a "Problem Details" report in an error response in accordance with https://datatracker.ietf.org/doc/html/rfc7807[RFC 7807].
====
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_process-execute-handle-prefer]]
[recommendation,type="general",id="/rec/core/process-execute-handle-prefer",label="/rec/core/process-execute-handle-prefer"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-handle-prefer

A client that accompanies an execute request with the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-2[`Prefer`] header asserting a https://tools.ietf.org/html/rfc7240#section-4.1[`respond-async`] preference and/or a https://tools.ietf.org/html/rfc7240#section-4.3[`wait`] preference SHOULD be prepared to receive either an asynchronous or a synchronous response.
====
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_process-execute-handle-return-preference]]
[recommendation,type="general",id="/rec/core/process-execute-handle-return-preference",label="/rec/core/process-execute-handle-return-preference"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-handle-return-preference

A client that accompanies an execute request with the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-2[`Prefer`] header asserting a https://tools.ietf.org/html/rfc7240#section-4.2[`return`] preference SHOULD be prepared to receive output values either:

* in-line in the response,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_process-execute-honor-prefer]]
[recommendation,type="general",id="/rec/core/process-execute-honor-prefer",label="/rec/core/process-execute-honor-prefer"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-honor-prefer

[.component,class=part]
--
If an execute request is accompanied with the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-2[`Prefer`] header asserting a https://tools.ietf.org/html/rfc7240#section-4.1[`respond-async`] preference, then the server SHOULD honor that preference and response asynchronously if, according to the job control options in the <<sc_process_description,process description>>, the process can be executed asynchronously.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_process-execute-honor-prefer-return]]
[recommendation,type="general",id="/rec/core/process-execute-honor-prefer-return",label="/rec/core/process-execute-honor-prefer-return"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-honor-prefer-return

If an execute request *is accompanied* with the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-2[`Prefer`] header asserting a https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[`return`] preference, then the server SHOULD honor that preference.

See requirements:
Expand Down
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_process-execute-mode-auto.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_process-execute-mode-auto]]
[recommendation,type="general",id="/rec/core/process-execute-mode-auto",label="/rec/core/process-execute-mode-auto"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-mode-auto

A client that requests a process be executed in `auto` mode SHOULD be prepared to receive either an asynchronous or a synchronous response.
====
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_process-execute-preference-applied]]
[recommendation,type="general",id="/rec/core/process-execute-preference-applied",label="/rec/core/process-execute-preference-applied"]
[recommendation]
====
[%metadata]
identifier:: /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 <<sc_execute_response,response>>, 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.
====
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
[[rec_core_process-execute-sync-many-json-prefer-minimal]]

[recommendation,type="general",id="/rec/core/process-execute-sync-many-json-prefer-minimal",label="/rec/core/process-execute-sync-many-json-prefer-minimal"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-sync-many-json-prefer-minimal
[.component,class=conditions]
--
. The <<sc_execution_mode,negotiated execution mode>> is synchronous.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
[[rec_core_process-execute-sync-many-json-prefer-none]]
[recommendation,type="general",id="/rec/core/process-execute-sync-many-json-prefer-none",label="/rec/core/process-execute-sync-many-json-prefer-none"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-sync-many-json-prefer-none
[.component,class=conditions]
--
. The <<sc_execution_mode,negotiated execution mode>> is synchronous.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[[rec_core_process-execute-sync-many-json-prefer-representation]]
[recommendation,type="general",id="/rec/core/process-execute-sync-many-json-prefer-representation",label="/rec/core/process-execute-sync-many-json-prefer-representation"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/process-execute-sync-many-json-prefer-representation

[.component,class=conditions]
--
. The <<sc_execution_mode,negotiated execution mode>> is synchronous.
Expand Down
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_process-list-next-1.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_next-1]]
[recommendation,type="general",id="/rec/core/next-1",label="/rec/core/next-1"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/next-1

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.
====
5 changes: 4 additions & 1 deletion core/recommendations/core/REC_process-list-next-2.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[[rec_core_next-2]]
[recommendation,type="general",id="/rec/core/next-2",label="/rec/core/next-2"]
[recommendation]
====
[%metadata]
identifier:: /rec/core/next-2

Dereferencing a next page link (relation: `next`) SHOULD return additional process summaries from the set of selected process summaries that have not yet been returned.
====
Loading
Loading