What happened with the service description metadata?

[joanma747]

Service discovery has been a common issue. Common approach is to provide some basic metadata about the service (title, abstracts, organization, keywords ...). We have this for the individual collection but I do not see any "path" to get or change this metadata.

Can we have a /info to describe the server a bit using ISO 19115 or Dublin core...

Equivalment to this one: https://github.com/opengeospatial/WFS_FES/issues/246

[joanma747]

The section info in the OpenAPI can be seen here: https://swagger.io/docs/specification/api-general-info/. Compared to: https://www.dublincore.org/specifications/dublin-core/dces/ the only thing missing is "date" and "language". "keywords" was a common thing to have but... Are those important?. Do we need some extent (bbox and time) for the service? They could be extract from the individual collections.

[cmheazel]

Consensus:

1) Information which is essential to discover and use the API shall be in the landing page. 2) Additional metadata (ex. 19115, Dublin Core, DCAT) belongs as a link from the landing page 3) Add an examples of what it would look like (HTML and JSON) 4) Goal is to encourage, not mandate, use of metadata. 5) Make sure it can be extended with community-specific elements.

Add a permission to create a link and use the describedby relationship as used in Features.

References: Dublin Core Schema.org

Check on the use of describedby in tiles API.

[ghobona]

2020-09-29 OGC API Sprint

We could use the 'service-meta' relation type from IANA for the service.

[cmheazel]

Added data-meta relation type for links to external metadata documentation. Added use of the data-meta relation type to the example landing page. Added example of the use of extension metadata in the OpenAPI "info" element. Added explicit permission for the implementer to add additional relation types. Stipulate that they should be from the IANA or OGC registers and that they cannot miss-use a relation type which is already used in this Standard for another purpose.

[cmheazel]

Service-meta can point to a disembodied OpenAPI Info element containing title, description, version, contact, etc. See WMS 1.3 page 60. Capture as a recommendation. Disembodied Info element will comply with the OpenAPI JSON schema for an Info element. Agreed - API-Common meeting of November 16, 2020.

[cmheazel]

Created a recommendation that OWS-Common Service Metadata (Service Identification and Service Provider sections) also be provided by OGC Web APIs. This metadata should be encoded in an OpenAPI Info object. Created a JSON schema for this object and provided a populated example. Added a section to Conventions section to discuss this recommendation.

[joanma747]

Action for the group: review the way this is done and close it if no objections are found: This is the the JSON schema to use: https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/oasInfo.json https://github.com/opengeospatial/ogcapi-common/blob/master/core/recommendations/oas30/REC_service-metadata.adoc

[joanma747]

Change the text in the recommendation: "In order to maintain commonality between OGC Web Services and OGC Web APIs, an OGC Web API should expose the Service Metadata defined in OWS-Common."

Move to a NOTE saying: "Information in sections Service Identification and Service Provided on the OGC Web Services was useful to easily identify the provider and have an overview of the data exposed by the API. This recommendation provides a way to include this information in the OGC Web APIs"

Replace recommendation to permission (in core and oas30)

The "pemsision" should be simplified to avoid references to OWS Common in the text.

[cmheazel]

Remove OWS Common from normative references.

[cportele]

See the 2nd bullet in my comment in another thread:

"In order to maintain commonality between OGC Web Services and OGC Web APIs, an OGC Web API should expose the Service Metadata defined in OWS-Common"

I understand that we want to link to service metadata in a consistent way, but to recommend that the service metadata should be the old OWS Common service metadata aka capabilities? I don't think core should recommend any particular service metadata standard. That should be left to separate requirements classes and it would probably be best to specify this outside of part 1.

The current draft also does not yet implement what has been documented above. For example, OWS Common is still used in normative statements.

[cmheazel]

January 25 SWG meeting - consider moving to the guide - don't "recommend" use of the elements from the capabilities document. Remove referenced to OWS Common from the standard. Remove "core" label once changes have been made.

[cmheazel]

Striped rows C and D out of the recommendation Added a referral and link to the users guide Removed mention of Web Services Removed references to OWS common from OAS recommendation. Added link to "info" object encoding as an example. Updated the OAS example to remove references to OWS.

[cmheazel]

February 1 - Recommendation 8 - Server should support service metadata and the landing page should have a service-meta association to the service metadata.

"Current text "The server SHOULD support the HTTP GET operation on all links from the landing page which have the relation type service-meta."

[cmheazel]

Modified Recommendation 8

[jerstlouis]

The published Part 1 mentions service-meta, but only in the Link Relations section.

Should an additional recommendation be added?

The Recommendation 8 mentioned above does not seem related.