Allow example(s) for in/output format parameters

[soxofaan]

https://github.com/Open-EO/openeo-api/blob/16b1122c7090cc4fedcabace48686a4f73c1c876/openapi.yaml#L5440-L5478

For PNG output format we have a color map parameter, which is a complex object (mapping of buckets to RGBA tuples). It would be handy if we could provide an example of this parameter for documentation purposes.

[soxofaan]

(cc @bossie)

[m-mohr]

I can't really follow. The API spec is file format independant and as such doesn't define specific parameters for file formats. It just gives tha ability to define parameters individually. There are examples for parameters in the API doc, see https://api.openeo.org/#tag/Capabilities/operation/list-file-types and then expand the example... The parameters itself are basically JSON Schema again.

[soxofaan]

There are examples for parameters in the API doc,

I don't mean example parameters, but example value(s) for a given parameter. For example, for the PNG output format we have a "color_map" parameter, which is not a simple string or int and want to provide an example for documentation purposes:

GET /file-formats
{
  "output": {
    "PNG": {
      ...
      "parameters": {
        "color_map": {
          "description": "Mapping of value buckets to RGB(A) values".
          "type": "array",
          "items": {"type": "array", ....
          "example": [
            [[-10, -5], [64, 0, 255, 255]],
            [[-5, 0], [82, 0, 210, 255]],
            ....

I hope this is clear. I understand we can add that anyway, but it could be useful to standardize it and visualize appropriately in the hub and widgets.

[m-mohr]

Aaaah! So you propose adding a new property example(s). As this is basically JSON Schema, you can re-use their examples property: https://json-schema.org/understanding-json-schema/reference/generic.html#id2 Note that this is an array of examples! We could add it specifically to the API if there's a wish for it, but it's allowed already as we say the parameters are JSON Schemas. The Vue components and Web Editor should already render that correctly as well.

[soxofaan]

As this is basically JSON Schema, you can re-use their examples property: https://json-schema.org/understanding-json-schema/reference/generic.html#id2

aha, this is indeed what we need. I failed to find just that occurrence of "example" in those docs, too many false positives :smile:

The Vue components and Web Editor should already render that correctly as well.

great, then there is no further need for specification I think