This page gives practical information on how to make the service metadata (a.k.a capabilities documents) of your OGC Web Services more useful to the users of your services. Our primary motivation for writing this guide is to help spatial web service providers to enrich their capabilities documents in a way that we can show them in the best possible way in our Spatineo Directory. Correct and rich capabilities documents help us
- automatically generate the best possible Spatineo Directory description pages for those services, and
- provide better, more precise search results for the Spatineo Directory users.
Most of this information can be found in the standards documentation provided by the standardization organization responsible for defining standards such as Web Map Service (WMS) and Web Feature Service (WFS), the Open Geospatial Consortium (OGC). For the datasets adhering to the EU INSPIRE Directive requirements, there are additional requirements and recommendations for the service metadata in the INSPIRE Network services Technical Guidance documents. The standards documentation is not always the easiest of reads however, and that’s why we’ve collected some of the most important guidance here.
This document is divided into sections by the standard and further by it’s version, when the requirements for different standard versions differ from each other (as often happens). For each guidance entry we mention the source of information, the rationale for following it, as well as how we use this information in Spatineo Directory.
Web Map Service (WMS), version 1.3
- OpenGIS Web Map Service (WMS) Implementation Specification, version 1.3.0, and
- Technical Guidance for the implementation of INSPIRE View Services, version 3.1.
WMS 1.3, also standardized by the International Organization for Standardization as standard number ISO 19128:2005, is one of the two technical solutions mentioned in the INSPIRE Technical guidance for implementing an INSPIRE View Service. The other one is the OGC Web Map Tile Service (WMTS) version 1.0. Thus the INSPIRE specific WMS requirements and recommendations are limited to this version of WMS only.
Using Names and Titles
The WMS capabilities document contains both names and titles in several places. Always use Name for the machine-readable, unique identifiers and Title for the human-readable, possibly language-specific name intended to be show to the users. Also always provide the title for the whole service as well as for each provided layer, but please keep the titles brief: the longer descriptive text should be given in the Abstract element.
A number of elements have both a <Name> and a <Title>. The Name is a text string used for machine-to-machine communication while the Title is for the benefit of humans. For example, a dataset might have the descriptive Title “Maximum Atmospheric Temperature” and be requested using the abbreviated Name “ATMAX”.
(OpenGIS Web Map Service (WMS) Implementation Specification, version 1.3.0, chapter 7.2.4.2)
The value of the Name element of a WMS service is always fixed to string “WMS” by the specification. This element is used by the client software to distinguish different Web Services. It must not be used for other purposes. The value of the Title element of the service provides a human readable name for the service. Please try to use distinctive and descriptive Titles:
- Good: “Finnish Nature Reserves”
- Bad: “INSPIRE WMS Service”
- Good: “Web Map Service of the Canadian Wildlife Association”
- Bad: “Geoserver WMS”
In the INSPIRE View Service profile of the WMS 1.3 the layer Names and Titles have been “harmonized” between the different data themes. Each of the 34 spatial data themes in INSPIRE have their own set harmonized layer Names and Titles defined in the EU Commission regulation No 1089/2010 on interoperability of spatial data sets and services. This document provides a harmonized Name and Title for each the spatial data object types defined the INSPIRE Data specification for that theme. The idea behind this restriction on the layer names is to make it easy to identify the layers providing visualizations of the same data types between EU member states. If harmonized WMS layer names and titles are defined for your INSPIRE data, you should use only them in the WMS capabilities.
The WMS 1.3 makes it possible to define hierarchical layer structures: each layer may contain zero or more child layers which inherit many, but not all of the layer properties from their ancestors. If the parent layers have the Name elements, they may be used to retrieve all the child with one request. If they only provide Title elements, they are provided for logical grouping and to avoid layer property duplication of the child layers. As different clients may or may not display the Titles of the ancestor layers, it’s better to use layer Titles that make sense even without the context of their parent layer Titles. So if you have parent layer with Title “Yearly average temperatures” with one child for each year, it’s better to Title them “Average temperature for 2012″, “Average temperature for 2011″ than just “2012″ and “2011″ and so on.
Both Title and Name fields of layers and Titles of the services are used for matching against the user search terms by the Spatineo Directory search engine. The Title fields of both services and layers are shown as the title of the search matches. If several layers provided by the same service have the same Title, their layer names are show in the results list instead.
Provide Abstracts
Adding a couple of sentences long description about your WMS service as well as for each of the provided layers makes it much more convenient for the data users to use your services. Try to describe both the underlying data and the applied visualization method in few words. Do not provide very long descriptions here, this is supposed to be abstract as the name of the element indicates. Two to four sentences is probably a good rule-of-thumb. If you want to provide more information considering the underlying data, use the MetadataURL to link to an external metadata record describing the dataset in detail. For details on certain visualization, use the Title and Abstract of specific Style elements.
The Abstracts of both Services and Layers are used by the Spatineo Directory search engine to find matches against the the user-provided search terms. The Abstract of the service is displayed at the beginning of the Spatineo Directory service page, and the layer Abstracts as the main content of the available layers list.
Provide good keywords
Your should always use at least a couple of descriptive keywords for each service and preferably also for each layer of those services. You can do this by adding KeywordList elements with one keyword per contained Keyword element. If the keywords are picked from a known vocabulary (like GEMET):
<wms:KeywordList> <wms:Keyword>Water</wms:Keyword> <wms:Keyword vocabulary="GEMET">Agriculture</wms:Keyword> <wms:Keyword>Pollution</wms:Keyword> </wms:KeywordList>
Localization
You should probably select the language in which the Titles and Abstracts are provided according to the main intended user group of your services. There is no built-in support for language-specific localization if the WMS 1.3 specification. In principle you could always use the Accept-Language and Content-Language HTTP Headers to convey the information about the preferred and selected content languages of the capabilities, but this is not mentioned in the specification.
For the INSPIRE View Services, the WMS 1.3 specification is extended to include both the available content languages in the capabilities document, and the user selection of the preferred language in the service requests. The language support is given as part of the INSPIRE-specific capabilities extension namespace inspire_vs:ExtendedCapabilities:
<inspire_common:SupportedLanguages>
<inspire_common:DefaultLanguage>
<inspire_common:Language>dut</inspire_common:Language>
</inspire_common:DefaultLanguage>
<inspire_common:SupportedLanguage>
<inspire_common:Language>eng</inspire_common:Language>
</inspire_common:SupportedLanguage>
</inspire_common:SupportedLanguages>
<inspire_common:ResponseLanguage>
<inspire_common:Language>dut</inspire_common:Language>
</inspire_common:ResponseLanguage>
Only three-letter language codes based on ISO 639-2/B alpha 3 codes should be here, the list of the EU and EFTA member country language codes can be found in the Table 9 of the Technical Guidance for the implementation of INSPIRE View Services, version 3.1. (on page 54). To request the capabilities document in one of the supported languages, an INSPIRE-specific HTTP request parameter “LANGUAGE” is given with the GetCapabiltities request.
