More flexible path structure under /collections

[pvretano]

Right now the core indicates that the the path to a collection of features is /collections/{name}. This path structure is a little rigid in some use cases such has organizing the collections into themes. A request was made to loosen up that structure a bit to allow things like /collections/path1/path2/{name} to accomodate additional organization structures on the feature collections. See issue #64 for additional discussion.

[lieberjosh]

The simplicity of the collections path is appealing. What if there was the option of another thematic path, such as /themes, that provided one or more different ways to organize features? Then it would be possible to support whatever classification schemes the service provider deemed useful, even alternative taxonomic and mereotopological schemes. They could be discovered by following rel links and/or by providing a scheme “map” at the /themes or /themes/theme_name level in SKOS or another graph representation. —Josh

…

On Mar 19, 2018, at 1:51 PM, Panagiotis (Peter) A. Vretanos ***@***.***> wrote: Right now the core indicates that the the path to a collection of features is /collections/{name}. This path structure is a little rigid in some use cases such has organizing the collections into themes. A request was made to loosen up that structure a bit to allow things like /collections/path1/path2/{name} to accomodate additional organization structures on the feature collections. See issue #64 <#64> for additional discussion. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#90>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AExWhqXlBBIlh3WmNBq-L0X9C3RevWVrks5tf_AHgaJpZM4SwnmY>.

[pvretano]

@lieberjosh, I think that approach is really nice but would most likely fall into the category of "extension" to the core. I was thinking of something simpler that could be done in the core and was suggested by @cholmes. The core would allow an arbitrary number of path elements between the /collections resource and the leaf collection resource. Doing a GET at any level gets you aggregate metadata about the immediate child levels below it. So, consider: . Doing a GET at any level gets you the aggregate metadata about the first child level. So 'GET /collections' gets you the metadata about 'Governmental Units', 'Hydrography' and 'Transportation'. Doing a 'GET /collections/Hydrography' gets you the metadata about each layer under the 'Hydrography' theme (i.e. 'Hydrographic Areas (1:24000)', 'HydrographicAreas (1:100000), etc.). This approach kinda mirrors how the WMS organizes layers.
To get the features themselves, you do a GET on the /collections/{path to leaf node}/items resource (e.g. GET /collections/Hydrography/Point Features/items).

[rcoup]

@pvretano so would the “name” be Hydrography/Point Features? Or just Point Features? (though would need to be globally unique). Or do we introduce an additional property for the Hydrography bit?

[jvanulde]

@pvretano why wouldn't one just do a 'GET /Hydrography/Point Features/items'? I don't see a need for collections...

[lieberjosh]

My feeling is that this is not in fact simpler than /themes. It’s pretty much the same, under a different top level path, except without something that gives the client an overall view of the scheme by which the path elements (i.e. taxonomy) are organized. I’m suggesting that /collections provide a simple and uniform access to the service holdings, while (possibly multiple) more involved paths are offered separately. Still could be an extended capability, of course. As an aside, it is also possible that the provider would want to classify features not just by type but “thematically", so there might be a case for fetching “collections of collections” of features, e.g. /hydro/catchments/items vs /hydro/catchments/interiorcatchments/items. This is more like the WMS hierarchy, that one may request any level of the hierarchy as a map layer.

…

On Mar 19, 2018, at 2:36 PM, Panagiotis (Peter) A. Vretanos ***@***.***> wrote: @lieberjosh <https://github.com/lieberjosh>, I think that approach is really nice but would most likely fall into the category of "extension" to the core. I was thinking of something simpler that was suggested by @cholmes <https://github.com/cholmes>. The core would allow an arbitrary number of path elements between the /collections resource and the leaf collection resource. Doing a GET at any level gets you aggregate metadata about the immediate child levels below it. So, consider: <https://user-images.githubusercontent.com/4433459/37613271-f8eb92be-2b7d-11e8-9542-b27fad4a2fb1.png>. Doing a GET at any level gets you the aggregate metadata about the first child level. So 'GET /collections' gets you the metadata about 'Governmental Units', 'Hydrography' and 'Transportation'. Doing a 'GET /collections/Hydrography' gets you the metadata about each layer under the 'Hydrography' theme (i.e. 'Hydrographic Areas (1:24000)', 'HydrographicAreas (1:100000), etc.). This approach kinda mirrors how the WMS organizes layers. To get the features themselves, you do a GET on the {leaf node}/items resource (e.g. GET /collections/Hydrography/Point Features/items). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#90 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AExWhpiG1BNi0sPyfcXBAVZ2lqtxavH5ks5tf_qVgaJpZM4SwnmY>.

[rcoup]

@lieberjosh even if you had a theme concept you still need globally unique collection identifiers under /collections/? Which I guess tends for them to be {namespace}__{collection} (as Andrea implemented in #64 discussion) or something equivalent. Or servers just fallback to numeric/UUID identifiers.

(I like the theme concept in principle, especially as collections could conceivably fall into multiple themes)

[pvretano]

@rcoup The {name} path element does not need to be unique but the complete resource URI does. So, "/collections/Hydrography/Point Feature" is a different resource than "/collections/Bob/Point Features". Underneath the covers, these URIs could point to the same Oracle table (for example) but such implementation details would be opaque to clients.

@jvanulde Joost, I am not tied to the existence of the "/collections" path element. I was just trying to extend the current paradigm (i.e. /collections is defined in core) slightly. I (... pointed out in issue #64 ) prefer a completely hypermedia driven approach where the server advertises the URIs of its collection resources in its landing page. (e.g. I mocked this approach up here: http://www.pvretano.com/cubewerx/cubeserv/default/wfs/3.0.0/foundation?f=json)

[pvretano]

@lieberjosh Yeah, I am starting to think that it is best to keep the core simple and have a /themes extension as you described.
@rcoup I think that under Josh's approach, /collections would only be 1 level deep pointing directly to the service holdings. Any hierarchy would need to be described under /themes. @lieberjosh Josh, did I get that right?

[cmheazel]

Observations and diatribe:

1. Many of the users of these services will be analytics, no humans involved. So everything required to use the service must be formalized in the standard or be machine readable through an OpenAPI document.
2. OpenAPI allows us to define a path using the Server Object. Server Objects provide a URL template and enumerations of the valid values for each variable in the template.
3. Server Objects can be defined for the service as a whole, for a single path, or for a single operation.
4. Server Objects do not provide a description of the purpose served by the variables in the template. Therefore, we need a URL construct with enough structure to convey those semantics. Consider a template which consists of path elements which are defined in the standard and implementation unique variables which lie between the standardized path elements. The standardized elements serve as delimiters. Variables between delimiters will have a well defined purpose (semantics). An analytic will "know" the purpose of the variables based on the known semantics of the bounding delimiters.
   example: https://{authority}/collections/{theme}/features/{name}
   collections - delimiter indicating the start of the collections path
   {theme} - optional theme path element(s)
   features - delimiter indicating the end of the theme path and start of the features
   {name} - feature names
   (NOTE: the enumerated list of valid values for {theme} also defines the thematic structure of the collection)
5. One more wrinkle. There is no requirement that the {authority} of a path is the same as the authority of the OpenAPI document. Nor is there a restriction that a path can only be used by a single "service". A path is a microservice in it's own right. Paths are aggregated but not contained by the higher level service. Since a path may be accessed through more than one landing page or OpenAPI document, everything you need to know to use that Path should be captured in the Path Item Object.

[rcoup]

@cmheazel can you add an example?

So... {theme} here can be delimited? With /?

And in the collections response, you'd see something like this? (I guess your /features/ maps to /items/ in the spec?)

 "collections": [
    {
      "name": "some/theme/buildings",
      "title": "Buildings",
      "description": "Buildings in the city of Bonn.",
      "extent": {
        "bbox": [ 7.01, 50.63, 7.22, 50.78 ]
      },
      "links": [
        { "href": "http://data.example.org/collections/some/theme/buildings/items",
          "rel": "item", "type": "application/geo+json",
          "title": "Buildings" }
        { "href": "http://example.org/concepts/building.html",
          "rel": "describedBy", "type": "text/html",
          "title": "Feature catalogue for buildings" }
      ]
    }
  ]

[cmheazel]

The capability I describe is in OpenAPI, not is the collections response. That being said, the same technique could be applied. I'll put together an example. However, I want to make sure it is right so it might take a little time.

[lieberjosh]

Yes: "under Josh's approach, /collections would only be 1 level deep pointing directly to the service holdings. Any hierarchy would need to be described under /themes."

[lieberjosh]

Re: "globally unique collection identifiers under /collections/"

The issue of identifiers vs locators is much larger than WFS. It is a well known problem, for example, that if you use a URL as a global identifier, i.e. URI, there isn't really an HTTP-native way of asserting that another URL is an equivalent URI. One way is to use a UUID-type of hash and incorporate that in whatever URL locates objects with that identity. It works, but it's awkward, obscure, and long.

Another approach is just to accept that a WFS service is not necessarily the authoritative identifier for a feature / feature collection / feature type. If there is, for example, a globally canonical URL for a feature collection which serves as its URI, the redirection to a specific WFS or other access point will have to be outside of that service. Working in the other direction, it would be useful to support global / authoritative URI's as standard (queryable) attributes (GML_ID or other) for resources of a particular WFS instance that are not necessarily the same as the access URL's for the service such as "https://wfs_service/collections/collection_name". Then one wouldn't necessarily get into recursive tangles of re-encoding URL paths with underscores and inserting them into -- URL paths.

It could well be a good practice, say under /themes, to replicate the path of the authoritative URI for a feature (collection) as part of the access URL. Then the feature with URI "https://authoritativeDN/usgs/hydro/huc8/catchment/520348" could be accessed as "https://wfs_service/themes/usgs/hydro/huc8/catchment/520348" providing a useful semantic hint to its identity. An id attribute of this feature would still include the former URI, however, for corroboration of the authoritative identity. The feature would also always be available under /collections in any way that is practically unique within the /collections domain, e.g. "collections/catchment/520348" or even "collections/usgs_hydro_huc8_catchment/520348" without requiring that any more globally unique identity be recorded within the URL.

I wouldn't say that the issues of identity vs access have been solved but these are a couple of ways that a WFS can at least be part of a larger solution.

[dr-shorthair]

Arriving late in this conversation.

A URI style issue: why plural 'collections' and not singular 'collection'? While it maybe makes sense for the initial request, for which the result is a list|set of collections, a longer URI with 'collections' in the path reads a bit strange. Suggest dropping the 's'.

[cportele]

15-APR-2019 Teleconference: Keep the simple, reliable /collections/{collectionId} path structure. This should always be available. In addition, extensions may specify deeper, alternate collection hierarchies (see the /themes discussion or the discussion in Testbed-14 ER, http://docs.opengeospatial.org/per/18-045.html#hierarchical_paths_extension, as examples). Clemens will review the wording that there is no contradiction and then close the issue.

[cportele]

resolved by #208