Metadata to the root of the service.

[joanma747]

I'm not an expert in OpenAPI but it seems that OpenAPI lacks the capacity to describe the service provider, and some parts of the service identification. Service provides and Service Identification were 2 essential parts of the ServiceMetadata (OWS Common).

Could we add a \metadata URI to the root to provide metadata about the service in whatever format including the old OWS common fragments mentioned before or a full XML ISO 19115-1 metadata record for services?

[cmheazel]

The /info element serves this purpose. And we can extend it if necessary. Two key points: 1) An API is not a service. Not all of the info in a capabilities document makes sense in an OAS document. 2) OAS is intended for machine processing. The driving use case is to process the OAS document into client code. Also, take a look at the discussion of OpenAPI vs. Capabilities in the guide. I attempted to cover this issue there. I'm sure it could use some improvement.

[cportele]

I do not see a need for /metadata in the Core. In my experience, most of the provider information in capabilities today is very often incorrect, incomplete or inconsistent with the information in the metadata record in a geoportal anyhow. I think /info includes the essential information and is in most cases sufficient.

And for sure I would not want to confuse anyone with 19115-1 metadata...

[pvgenuchten]

I'm in favour to introduce a number of metadata items on / and /collections. It makes sense from proper identification perspective, also from discoverability on search engines.

Things like provider information, keywords, language (the typical html-headers), temporal and spatial coverage, license/usage constraints, etc.

I am aware of the current common inconsistenties between capabilities metadata and catalog metadata (which is also a thing catalogs should be more strict on). But it's not a reason to just leave it out. Many clients will not be capable to follow links from capabilities to metadata and rely on the capabilities metadata only.

[cmheazel]

@pvgenuchten A valid point. I've mapped capabilities to OpenAPI, I can do the same for catalog metadata. A discussion of now a catalog would harvest an API would also be useful. Which catalog metadata model would you suggest we use.

[rcoup]

(Because I had to go look it up, the info: block comes from OpenAPI (spec))

Many clients will not be capable to follow links from capabilities to metadata and rely on the capabilities metadata only.

"not be capable" or "not be bothered implementing"? If they want more detailed metadata that badly surely they can implement?

And for sure I would not want to confuse anyone with 19115-1 metadata...

Agree 100% — by all means link to it, but it's not usable as-is for anything really. If we want to pick a metadata standard to expand info with, Dublin Core is much more realistic/pragmatic.

[cmheazel]

@rcoup The /info construct in OpenAPI is easy to extend. I'm not sure that all of the Dublin Core elements are appropriate, but we could standardize on a subset. If we come to agreement, support for these elements can be added to WFS 3.0 and OAPI Common.

[cportele]

There should be nothing in the Core that goes beyond the standard OpenAPI scope as any extensions will most likely not be supported in the OpenAPI tooling etc. Communities or maybe additional parts could make use of the OpenAPI extension capabilities, but not the Core.

[cportele]

06-MAY-2019 Conference call: This is out-of-scope for the Core and the current level of metadata seems appropriate. Links can be added already now for those that need / want to reference additional metadata. And communities can add their own specifications that specify a content model for metadata. Properly written clients will simply ignore elements they do not understand.

[heidivanparys]

The /info element serves this purpose. And we can extend it if necessary.

I don't know OpenAPI, but when looking at https://swagger.io/specification/#schema, I noticed that there is also an "externalDocs" field. Could externalDocs be used as a proper place to include a link to external service metadata, without having to extend /info?

[cmheazel]

@heidivanparys That's one way. But extensibility is not the problem. First we need figure out what metadata we need and why (there is more than one answer).