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.

Sign up for GitHub

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

Changes for closer alignment with OpenEO. #477

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Changes for closer alignment with OpenEO. #477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
56d7b44
Changes for closer alignment with OpenEO.
pvretano Dec 5, 2024
b1f9a19
Changes as per ad-hoc OGC/OpenEO discussion on 05DEC2024.
pvretano Dec 5, 2024
d2d5f3d
Fix typo.
pvretano Dec 5, 2024
107726f
Typo for multi-line descriptions.
pvretano Dec 5, 2024
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
2 changes: 1 addition & 1 deletion openapi/schemas/processes-core/statusCode.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ nullable: false
enum:
- accepted
- running
- succeeded
- successful
pvretano marked this conversation as resolved.
Show resolved Hide resolved
- failed
- dismissed
141 changes: 99 additions & 42 deletions openapi/schemas/processes-core/statusInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,99 @@
type: object
required:
- id
- status
- type
properties:
id:
type: string
processID:
type: string
type:
type: string
example:
- process
- wps
- openeo
status:
$ref: "statusCode.yaml"
message:
type: string
exception:
$ref: "../common-core/exception.yaml"
created:
type: string
format: date-time
started:
type: string
format: date-time
finished:
type: string
format: date-time
updated:
type: string
format: date-time
progress:
type: integer
minimum: 0
maximum: 100
links:
type: array
items:
$ref: "../common-core/link.yaml"
allOf:
- $ref: descriptionType.yaml
- type: object
required:
- id
- type
- status
properties:
id:
type: string
type:
type: string
Copy link

@m-mohr m-mohr Dec 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

process type?

It should probably just describe the encoding of the process property

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the description to indicate that if "type" is "openeo" then the "process" property MUST be present and its value shall be a process graph as per the OpenEO API definition. Otherwise if can be an OAProc process description, a WPS process description, a link to either of these or a link to the request that created the job (e.g. an async coverages request).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want this condition to be more explicit?

Since we have the allOf, we can make use of it.

allOf:
  - $ref: descriptionType.yaml
  - type: object
    # ... all other fields ...
  - if:
      properties:
        type: 
          const: openeo  # or 'enum' equivalent if prefered
    then:
      required:
        - id
        - type
        - status
        - process
      properties:
        process:
          $ref: "<uri-to-openeo-process-graph>"

Copy link

@m-mohr m-mohr Dec 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering whether OGC API - Processes should just define the framework and not have direct dependencies to openEO due to the issue that there are multiple versions of the openEO API...

As long as openEO follows the framework, I guess it's fine, isn't it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm expecting that anyone that wants to do strong schema validation would actually use the reference openEO schemas rather than depend on OGC API, so it's fine if we don't define field requirements of openEO explicitly here.

However, if we do so, I don't see much point to have the long description either for specific frameworks. Saying in the description that process is required when type: openeo doesn't actually enforce or validate anything.

Copy link

@m-mohr m-mohr Dec 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think the spec should not include specifics about openEO. Maybe as an appendix only.

description: |-
An indication of the API that created this job.

This value needs to come from a controlled vocabulary. The
current set of values is

* "process" (indicating that this job was created by an
OAProc process),
* "wps" (indicating that this job was created by a
WPS process),
* "openeo" (indicating that this job was created by an
OpenEO process).
examples:
- process
- wps
- openeo
process:
description: |-
The value of this parameter is a description of the entity that
created this job. The value of this property depends on the value
of the "type" property.

If the value of the "type" property is "process" or "wps" then
this property SHALL be present and its value SHALL be a description
of the process that created this job encoded in-line or referenced
via a link.

If the value of the "type" property is "openeo" then this property
SHALL be present in the status response and its value SHALL be the
process graph as per the OpenEO specification.

If the value of the "type" property is not "process", "wps" or
"openeo" then the value of the property SHOULD be a link pointing
to the entity that created this job (e.g. an asychronous coverage
request URL).
oneOf:
- type: object
- $ref: "../common-core/link.yaml"
status:
description: |-
The status of the job. The value space depends on the value of
the "type" property.

If the value of the "type" property is not "openeo" then the value
space of this property SHALL be defined in "statusCode.yaml".

If the value of the "type" property is "openop" then the value
space of this property SHALL be "created", "queued", "running",
"canceled", "finished" or "error".
oneOf:
- $ref: "statusCode.yaml"
- type: string
enum:
- created
- queued
- running
- canceled
- finished
- error
message:
Comment on lines +64 to +71
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does openEO have a schema for this?
The definition could be more explicit if we actually pointed to $ref: <uri-openeo-schema#status> or wherever it resides.

Copy link

@m-mohr m-mohr Dec 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't do the OGC way with snippets, we only have a monolithic OpenAPI document. In principle you can refer to that though:

"$ref:" "https://raw.githubusercontent.com/Open-EO/openeo-api/refs/tags/1.2.0/openapi.yaml#/components/schemas/batch_job/properties/status"

That reminds me that we should probably version the OpenAPI files on gh-pages with the docs so that it will be

"$ref:" "https://api.openeo.org/1.2.0/openapi.yaml#/components/schemas/batch_job/properties/status"

I hope yaml works, but we could also deploy json.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The second link would be ideal. It's fine with definition anchors. Either YAML or JSON should work.

type: string
exception:
$ref: "../common-core/exception.yaml"
created:
description: |-
The date/time that this job was created.
If the value of the "type" property is "openeo" then this property
SHALL be present in the status response.
type: string
format: date-time
started:
type: string
format: date-time
finished:
type: string
format: date-time
updated:
type: string
format: date-time
progress:
type: integer
minimum: 0
maximum: 100
links:
type: array
items:
$ref: "../common-core/link.yaml"
Loading