Part 6-properties: SwaggerUI-friendly properties

[jerstlouis]

In SwaggerUI, the current properties.yaml shows as a list box with only foo and bar as valid properties.

What would be the correct way to specify this parameter to get a friendlier UI?
In OGC API - DGGS, we simply used string:

https://schemas.opengis.net/ogcapi/dggs/1.0/openapi/parameters/dggs-core/properties.yaml

https://schemas.opengis.net/ogcapi/dggs/1.0/openapi/parameters/dggs-core/exclude-properties.yaml

The current schema is also missing a description, which could be partly inspired from the DGGS / Coverages one above.

[cportele]

In my view, using an enum makes sense in order to support the UI generation (that is a multi-selection dropdown menu which lists all valid values). Using "string" does not give any guidance on which values are valid and which are not.

Description: In ldproxy we currently use "The properties that should be included for each feature. The parameter value is a comma-separated list of property names. By default, all feature properties with a value are returned."

The schema will provide more information about each property, if enabled for the API. If the information should be in the "properties" description, the description could contain more information about each property.

Alternatively a one-of with constant values and a label/description like for coded-values in the schema could be used (but my guess would be that, e.g., Swagger UI does not render this in a helpful way).

[jerstlouis]

@cportele an enum is only useful if it can be a dynamic endpoint which is also collection-specific, and that is one thing that I have not yet figured out how to do... I don't know if it is possible with OpenAPI 3.1, but probably not for 3.0?

At the moment we have endpoints like: /ogcapi/api/tileMatrixSets that we can $ref in the OpenAPI definition, but for the valid properties this would need the {collectionId} as a parameter ( opengeospatial/ogcapi-common#302 and the various OAS issues I filed or commented upon linked from there).

Otherwise for the building block to be readily useful in assembling a generic API definition the string seems like the best approach (then one is actually able to enter the actual property names in the SwaggerUI edit box after looking at /collections/{collectionId}/schema, rather than not being able to specify anything other than foo and bar).

(note we have the same issue with collection-specific {styleId})

[cportele]

@jerstlouis

By default ldproxy publishes each collection as its own paths (also in OpenAPI 3.0), because all the details are collection-specific including the query parameters / queryables. An OpenAPI definition that is the same for each collection is probably not very helpful to clients/users.

In general, I do not see much value in referencing the schema components in the OGC schema repository. These are mainly there to support formalizing (and illustrate) the requirements.

Part 1 discusses the two approaches and ldproxy follows the second approach:

OpenAPI definitions can be created using different approaches. A typical example is the representation of the feature collections. One approach is to use a path parameter collectionId, i.e., the API definition has only a single path entry for all feature collections. Another approach is to explicitly define each feature collection in a separate path and without a path parameter, which allows to specify filter parameters or explicit feature schemas per feature collection. Both approaches are valid.

[jerstlouis]

@cportele I see that this is working in:

https://demo.ldproxy.net/vineyards/api?f=html#/Access%20data/vineyards.getItems

but you generate e.g.,

      "properties_vineyards" : {
        "name" : "properties",
        "in" : "query",
        "description" : "The properties that should be included for each feature. The parameter value is a comma-separated list of property names. By default, all feature properties with a value are returned.\n\n_Maturity: `PRELIMINARY` (specified in a draft standard; the parameter may change in this API)_",
        "required" : false,
        "style" : "form",
        "explode" : false,
        "schema" : {
          "minItems" : 1,
          "type" : "array",
          "items" : {
            "type" : "string",
            "enum" : [ "registerId", "name", "area_ha", "region", "subregion", "cluster", "village", "village_info", "cadastraldistrict", "searchfield1", "searchfield2", "date", "geometry" ]
          }
        },
        "x-maturity" : "DRAFT_OGC"
      },

for every collection.

That requires regenerating a full new OpenAPI definition for every single deployment and re-generate it if you add a new collection or add features that results in new properties etc.

With OAS 3.1 possibly this can be done now with $dynamicRef (as indicated in OAI/OpenAPI-Specification#2453 (comment)) that could reference the {collectionId} set to vineyards.

But for OAS 3.0, it is probably best to stick to a string for the generic parameter building block, so that people actually using the definition verbatim can still specify the property and aren't stuck with foo and bar.

(The enum version could be commented out with instructions for those who do want to generate an API definition on-the-fly?)

[jerstlouis]

In general, I do not see much value in referencing the schema components in the OGC schema repository. These are mainly there to support formalizing (and illustrate) the requirements.

@cportele My approach is not to reference the OGC schemas, but to use them to automatically (and quickly) bundle an API definition for the implemented requirements classes. Any deployment-specific are dynamic endpoints using a live $ref (but not yet using $dynamicRef since we haven't transitioned to OAS 3.1 yet). This works for {collectionId}, but not for per-collection properties / styles etc.

An OpenAPI definition that is the same for each collection is probably not very helpful to clients/users.

I have quite an opposite view :) If every collection has a completely different OpenAPI definition and the client/user cannot make sense of how all collections follow the same standard requests, it is not very helpful :)

Also if trying to use an OpenAPI definition as a way to write a generic compiled client that will work with any implementation / deployment, a different API definition per collection sounds like a nightmare.

But of course the per-collection specialization is useful... which is perhaps a reason to migrate to 3.1 and start using $dynamicRef :)

[cportele]

@jerstlouis

For me the API definition is mainly for those developers/apps/AI models that do not know or care about the standards, and the API definition should describe the various resources and operations of the API as good as possible.

I think that generic clients implementing the standards will mainly base the implementation on the standards itself, not the OpenAPI definition of an individual API.

But as we state in Part 1, both approaches are valid. Developers/apps/AI models will decide which APIs they use or not.

It is also important to understand that the schema components do not have to be used as they are in the schema repository. This is explicitly allowed in Part 1. So, compiling an OpenAPI definition from the OGC schema repository is possible, but I do not see much value of such an exercise to users of an API. But that is just my view.

Going back to the original comment, we could provide two variants of the "properties" schema, one with enums and one without.

[jerstlouis]

Thanks @cportele

So, compiling an OpenAPI definition from the OGC schema repository is possible, but I do not see much value of such an exercise to users of an API

On one hand I am hoping to make it easier for implementers to assemble OpenAPI definitions so that it can be done quickly and not be too much of a burden.

On the other hand, I would of course like the resulting API definitions to be useful. The OAS limitations (even with 3.1 $dynamicRef I realized) do not make it easy at all.

From an API definition/UI perspective, I find it quite horrible to have to define multiple paths for the same operation, and of course as a fan of thousands of collections this becomes especially important ;).

But really, what is the point of a path parameter if you cannot make use of them to provide a useful API definition?! For me this is an obvious ridiculous limitation of OpenAPI and such capabilities should really be considered for improvements.

[cportele]

But really, what is the point of a path parameter if you cannot make use of them to provide a useful API definition?!

There are good use cases for path parameters. In a Features API, e.g., featureId in /collections/foo/items/{featureId} is a good example.

[jerstlouis]

@cportele Right :) I argue /collections/{collectionId} is also a good use case -- the specification / tools are just not up to par yet ;) Hopefully this will change in a next-gen OAS :)