Lack of DescribeFeatureType request

[rouault]

Part 1 Core doesn't have a DescribeFeatureType sort of request, which makes it a bit inconvenient for some client like GDAL/OGR that requires to know quite early the schema to be able to expose a layer/ feature collection. For full feature collection ingestion, one can potentially download the whole response and analyze it afterwards to discover the schema. But for filtering based on properties, this wouldn't be an appropriate behaviour.

One way of implementing DescribeFeatureType would be to extend the feature collection metadata. Or in the OpenAPI description, instead of refering to the standard GeoJSON FeatureCollection to refer instead fo a derived FeatureCollection that describes the properties (although that solution would require to have a description for each encoding format, and that probably only works for json-based encodings)

[cportele]

Actually, this is by design. There is no requirement to have an application schema or even feature types in the Core. Since the Core does not support filtering in CQL or similar, the API should be usable without an application schema. In extensions this will clearly change, both because sometimes it is important for data providers or users to be explicit about the schema / support validation and to be able to formulate queries.

By the way, in a handcrafted OpenAPI 2.0 / Swagger variant for one of our demo services we have indeed specified the schema of the features in the OpenAPI definition: https://app.swaggerhub.com/apis/cportele/lika-nrw/0.0.1. In an OpenAPI. In an OpenAPI context this would seem to be the most "natural" approach to me, but it mostly works for JSON encoded data and less for data in XML or other encodings (see also #58).

[cportele]

@rouault We had a discussion here at the hackathon and basically identified three approaches for providing schema information:

1. as part of the OpenAPI definition (see my example above)
2. using links from the collection (see /rec/core/fc-md-descriptions)
3. using a separate endpoint /schema under the collection (the Cubewerx server supports this)

They all have their role / advantages. The first one is easiest for users that do not know or care about WFS and "just" want to use an API. This also leverages the OpenAPI stack and tooling. The second one supports the hypermedia approach and one can determine the schema etc. when accessing and navigating through the information. The third option publishes the information about the schema resource already in the OpenAPI definition. Since all three have their use we want to "allow" all of them.

The first option has a lot of potential for new users, so we agreed that this has a priority for experimenting with it. Peter is looking into supporting it in his implementation.

@pvretano, @cholmes - does this capture the main points of our discussion?

[cholmes]

Yup. And to emphasize the key point: Even should try to implement client support for 1., using https://app.swaggerhub.com/apis/cportele/lika-nrw/0.0.1 And @pvretano will post his implementation here when it's up.

Having that in GDAL client will likely make it a defacto recommendation, for those who write servers and test with GDAL. It'll be good to have GDAL to not have to rely on the schema, but it'd be great to code up the support for reading the schema.

[rouault]

@cholmes https://app.swaggerhub.com/apis/cportele/lika-nrw/0.0.1 is Swagger/OpenAPI 2.0 . It needs to be "ported" to the /api openapi 3.0 first as I'm not fluent enough in openapi to anticipate what it would look like. But yes that's certainly a reasonable option.

[cholmes]

@rouault - gotcha. I talked to @cportele and he said he'd try to update it, but he's got a lot going on. Will update this ticket if it gets done.

[cportele]

@rouault - I have tried to compile an OpenAPI 3.0 version. I did not have much time to verify it, let me know, if you hit any issues.

https://raw.githubusercontent.com/opengeospatial/wfs3hackathon/master/openapi.json

[rouault]

@cportele Thanks I've just added support for it in the GDAL driver. OGR_WFS3_API_URL=https://raw.githubusercontent.com/opengeospatial/wfs3hackathon/master/openapi.json ogrinfo WFS3:https://www.ldproxy.nrw.de/kataster flurstueck -al -q (the OGR_WFS3_API_URL is a hack to use an alternate URL for the /api endpoint)

I'm thinking that the geometry type could also be advertized by specializing the following and indicating which type(s) are possible

          "geometry": {
            "$ref": "#/components/schemas/geometryGeoJSON"
          },

[aaime]

I'm a bit worried about the size of the resulting API document, installations with thousands of layers are not uncommon (the uncommon ones have hundred of thousands of layers), the API document already has a fair amount of redundancy, if all the schemas are also added in it, it will become really large...

[cportele]

@rouault - Thanks, forgot to be update to MultiPolygon only

@aaime - Yes, for servers with many collections that is clearly an issue. I think for these cases the approach to document the schema in the OpenAPI does not work and the OpenAPI definition should fallback to just

• /{name}
• /{name}/{id}

instead of a specific description of each collection.

[cportele]

Discussion in 2018-03-13 web-meeting: No action needed for the Core.

Links to schemas in current implementations:

• http://wfs3hackathon.ldproxy.net/rest/services/test/?f=json (Link from collections document)
• http://www.pvretano.com/cubewerx/cubeserv/default/wfs/3.0.0/foundation/collections/builtupa_1m/schema (separate schema access path)

[cmheazel]

OpenAPI issue 1532 may help here. It is a proposal to allow multiple alternate schemas in the Media Type object. These alternate schemas are not restricted to JSON schema. This allows us to specify multiple schemas in the Response Object, including XML (GML) schema. This feature is likely to make it into the next version of OpenAPI. If this is a feature we want to use, please let me know so that I can argue for the requirement in the TSC.

[cportele]

@cmheazel - Yes, I think that change would be good for supporting XML schema. We knew the current XML support is not really sufficient and so removed all the XML snippets from the OpenAPI examples waiting for an approach to XML that allows us to leverage "our" XML schemas. This approach also avoids the clutter of XML snippets that OpenAPI 3.0 has.

[cmheazel]

@cportele - Thanks. I'll put together an update reflecting the discussions at Mondays TSC meeting. We can discuss specific requirements under this issue.

[mdastous-bentley]

I'm interested in this topic as well, is there a document that summarizes the different options to get the feature(s) schema? My understanding is that, WFS 3.0 will be mainly schema-less, but a schema could be available on some implementations.

[cportele]

This should be addressed by #129 (schema links from the API definition) and #126 (schema links from the resources).

[cportele]

06-MAY-2019 Conference call: Keep it open until #129 is resolved.

[cmheazel]

See Pull Request #256
This may address at least some of the requirements.

[cportele]

Code Sprint 2024-02-27: A draft of "Part 5: Schemas" exists and addresses the need for a feature schema. The part is expected to be submitted for OGC Architecture Board Review and then Public Comment soon. We are, therefore, closing this issue and invite comments on the draft of Part 5.