OGC Testbed-13: Executable Test Suites and Reference Implementations for NSG WMTS 1.0 and WFS 2.0 Profiles with Extension

The requirements addressed by this ER are the implementation of the NSG WFS 2.0 profile and NSG WMTS 1.0 profiles in the latest GeoServer version, as of October 2017, and the validation of the implementation with the corresponding CITE tests.

Before testbed 13 there were no implementations of NSG WFS 2.0 and NSG WMTS 1.0 profiles. GeoServer compliance status regarding the base standards WFS 2.0 and WMTS 1.0 was unknown. CITE tests for the NSG profiles didn’t exist and the existing tests for the base standards had to be extended.

After Testbed 13 completion the profiles tests were completed and available in the OGC validation web sites and GeoServer was compliant with the NSG profiles mandatory requirements, including the base standards that the profiles were based on.

The implementation of the NSG WFS 2.0 and NSG WMTS 1.0 profiles will help advance the architecture of profiles and architecture of conformance classes of OGC standards. The lessons learned on the development of the NSG profiles will help clarify aspects of new versions of WFS 2.0 and WMTS 1.0.

The NSG WFS profile is built on top of the DGIWG Web Feature Service 2.0 profile which is based on the WFS 2.0 standard. In light of current OGC efforts leading to more modular specifications, the ability to build composite compliance tests is a key capability. The experience with WFS will be valuable information for the Architecture SWG in particular.

GeoServer is an open source project with a diverse and vibrant community that has been involved in this work. The interaction with this community helped the development of this document and should provide a positive outcome for the OGC involved standards.

At last, having CITE tests suites that allow to test the compliance of the involved OGC standards will help other organizations in adopting them.

All questions regarding this document should be directed to the editor or the contributors:

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

GeoServer [1] is a free open source project designed for geospatial data interoperability and is an implementation of a number of open standards such as WFS, Web Map Service (WMS) and Web Coverage Service (WCS).

CITE tests suites are part of the GeoServer development process, relevant CITE tests suites are run automatically each day against the supported series. If a test fails it is considered to be a release blocker. This ensures that compliance with the different specifications is not broken.

This is the first time GeoServer compliance against WFS version 2.0 and WMTS versions 1.0 were tested within OGC programs. In a preliminary analysis several issues were found, mainly related to the WFS 2.0 specification, that needed to be addressed.

CITE tests suites relevant for these profiles are implemented in TestNG and CTL, TestNG is being used for developing new tests suites. CITE tests are run using TEAM Engine Validator. OGC Validation tools are free, open source and available from GitHub.

NSG WFS 2.0 CITE tests depend on WFS 2.0 CITE tests, running NSG WFS 2.0 CITE tests will also run the WFS 2.0 CITE tests. NSG WMTS 1.0 CITE tests will only implement the requirements that come directly from the NSG WMTS profile. WMTS 1.0 CITE tests will need to be run separately.

The main objective of this work was to implement the NSG profiles in GeoServer and the necessary CITE test suites to validate the implementation.

A secondary objective is to make GeoServer compliant with WFS 2.0 and WMTS 1.0 and to introduce the correspondent CITE tests suites as part of the daily checks.

From the profile implementor point of view, profiles make a good job in making clear which requirements from the sub profiles or standards are restricted or made mandatory. The summary table of the NSG WMTS profile is a significant help during implementation.

Something that could be improved in the profiles is the connection between concepts, i.e. when two concepts are connected or when a concept depends on another one. For example, the PageResults operation descriptions would benefit in having an explicit link to the index result type description. The same is valid for feature versioning and resource identifiers.

A profile always has one or more dependencies that must be heeded when developing an implementation or a conformance test suite. For example, a test suite for any WMS profile will include tests covering one or more conformance classes in the OGC WMS conformance test suite. The DGIWG profile requires conformance at the "Queryable WMS" level. The associated test suite also includes tests that cover the specific requirements of that profile.

A test suite for a profile generally selects one or more conformance classes (or levels) from the relevant set of base specifications. These tests then implicitly become part of the dependent test suite. The base tests are invoked in the course of running the profile-specific tests.

The source code can be included directly. The way in which the code is included depends on how a test suite was implemented (TestNG or CTL). The type of the base test suite determines the type of the profile test suite. If the base test suite is implemented in TestNG, the profile test suite must also be implemented in TestNG. The same applies to CTL.

A test suite that covers the requirements of an application profile is accessed and executed just like any other test suite. It appears in the listing of available suites, and it can be selected and run in the same manner.

The main goal of this profile is to promote interoperability within the GEOINT communities (defense agencies, NATO, coalition partners, etc.) This profile is built on top of DGIWG Web Feature Service 2.0 profile and its base specification is WFS 2.0. This profile has also a strong dependency on these standards: GML 3.2.1 [OGC 07-036], Filter 2.0.2 [OGC 09-026r2] and WSC 1.1 [OGC 06-121r3].

As stated on the profile, the extensions and restrictions introduced are designed to achieve the following:

The following operations are supported in the profile:

The mandatory service bindings for these operations are HTTP GET / POST, and SOAP is optional. The only mandatory features encoding is GML 3.2. Service exception reports should use the defined exception codes and correctly identify operations. The profile also introduces a mandatory response timeout functionality, which will be extensively discussed in the implementation chapter.

Capabilities documents should clearly identify in the service identification metadata section which profile is being used, the predefined statement should be used. Specific metadata related with access constraints and service constraints need also to be added.

Feature versioning support is mandatory and must be based on date and time. It must also be compatible with the filter encoding standard, allowing queries to filter the features based on their version.

The new PageResults operation introduces a better support for pagination by allowing random access of the paginated results. This operation depends on the new introduced index result type.

The base specification of this profile is WMTS 1.0 whose base operations are:

This profile requires that a REST interface must be exposed, HTTP GET /POST methods are also mandatory and SOAP support is optional. Any possible order of the variables and values in the URL template is valid but a specific order is recommended.

Coordinate systems CRS:84 WGS84 and EPSG:4326 WGS84 must be supported, as well as projections EPSG:3395, EPSG:5041 and EPSG:5042. Scales for World Mercator EPSG:3395 defined in Annex B of the profile must also be supported.

Regarding responses MIME types, image formats image/png, image/jpeg and image/gif must be supported and GetFeatureInfo request must support text/xml, text/html and application/gml+xml; version=3.2 as output formats.

Caching information (expiration data) for the data must be provided using HTTP control headers.

Some specific meta-data and keywords as defined in the profile must also to be provided through the capabilities document.

Versioning of data is a vast subject with a great number of techniques and algorithms. The NSG WFS profile makes it easier by focusing only on time versioning and by providing a definition of a resource identifier compatible with this versioning technique.

For each feature, the system should keep information about when the feature was first created and for each subsequent modification. It should also be possible to identify each feature uniquely and the entity represented by each feature. An entity may be represented by multiple features in different versions.

In practice, this means that the server internally needs to associate each feature with a timestamp and an entity identifier. An important question arises related to how that association should be stored by the server: Should the data schema already support this information as two attributes (e.g. columns in a relational database) or should they be stored separately?

The main drawback of storing that extra data separately is that it makes the system more complex, requiring a join of the different elements at runtime and making the management of the data more difficult. If a relational database is used as storage, the service implementation would need permissions to create a new table or the database administrator would need to create it explicitly.

If the data schema already accounts for these two attributes, then the administrator has to specify which attribute should be used for the timestamp and which one identifies the entity represented by a certain feature. This approach was chosen in the GeoServer implementation, the choice of the attributes is proposed on the administration UI during the layer configuration.

The WFS NSG profile versioning requirement is built on top of a very specific use case: a data set can be continuously updated while clients retrieve the data that was updated since their last check. The OGC WFS 2.0 standard is not explicit about the semantics of the create, update and delete operations. The NSG profile already provides several details which are absent from the OGC WFS 2.0 standard, it may be worth also clarifying the semantics of these operations. Taking into account the context of the requirement, the following semantics were assumed:

By requesting the delta between the last check and the current time, the client will be able to understand which features have been updated but not which ones have been deleted.

Detecting which features have been deleted since the last check can be done by performing two requests with consequent time envelopes and then comparing the results to detect the deleted features. This solution is impracticable with big data sets, because in practice the whole data set will need to be requested each time we want to detect deleted features.

A sensible approach to this problem would be the possibility of the client to know which operation (e.g. create, update or delete) led to the status of a particular feature or the ability to filter features by the operation that changed their status (e.g. give me all the features that where created or deleted in the last hour).

Random pagination is the ability to perform a request to the server and index the result allowing clients to request parts of that result in any order. A common doubt when implementing pagination is how to deal with concurrent changes, i.e. changes to the data that occur after the initial pagination request.

Consider the following data:

A client makes a pagination request to the server asking for all the persons that are older than 18 years sorted by their age. Then the client starts viewing the results starting in index zero with a pagination of two:

Now consider that the user is currently viewing the first page and that in the meantime Robert is removed from the dataset. Then the user wants to see page two, so the client requests that page. Depending on the pagination algorithm the client can see these two different results:

The first result corresponds to algorithms that are capable of identifying the dataset elements that remain unchanged since the initial pagination request hit the server. These types of algorithms are quite complex and only possible to implement with the help of the data store and only work for very specific use cases.

Implementing this type of algorithms for a generic dataset would require the capability of storing the result set that corresponds to an initial pagination request and then iterate over that result set. Pagination is only really needed when requests return long results. Storing those request results, even in a compact format, means replicating significant portions of the original dataset in the server. This will allow clients to take down a server with a few requests.

The second result corresponds to algorithms that don’t store the initial pagination request result set but instead store the original pagination request. When a client requests a certain page starting at a certain index, the server executes the pagination request using the provided limits, i.e. start index a page size. The issue with this type of algorithms is that like in the example the user may miss some elements, or get the same element twice.

It should also be considered that algorithms of the first type may show invalid results. Let’s assume removing Charles instead of Robert. When the client requests the second page, depending on the pagination algorithm the client receives one of the two different results:

Algorithms of the first type will still show Charles even if that user was already removed, but algorithms of the second type will correctly not show that person.

Let’s say the perfect pagination algorithm is implemented, that would basically require a versioning mechanism keeping track of all the data changes and be able to return the correct portion of the data that corresponds to a certain page.

When missing a result is not that acceptable, there are several interesting approaches mixing algorithms of the second type and user experience patterns.

A common and simple approach is to tell the user that the page he is viewing has been updated and to update that page content, then the user will not miss an existing element or see outdated ones. This approach is common in certain mail clients, for example. The simplest way for a client to detect that the page content show to the user is outdated is to request the same page a check for differences.

Independently of the followed approach, both store some content on the server (either the full result set, or the definition of the original query and its timestamp). The profile doesn’t provide or define any mechanism to discover when that content is not needed anymore and can be removed. The implementation should implement a configurable mechanism cleaning any information related with a paginated request that has not been used since a certain amount of time.

The WMTS service capabilities documents contains several XML elements allowing web clients to invoke the WMTS RESTful API. Three types of resources can be retrieved using the RESTful API:

The end-point that can be used to retrieve the capabilities document is static for each GeoServer instance and looks as follows:

The retrieved capabilities document needs to contain the top-level element (direct child of the root element) ​ <ServiceMetadataURL> that tells clients what is the WMTS capabilities document resource URI, it shall look like this:

Each WMTS published layer needs to have several <ResourceURL> elements that define the resources associated to that layer that can be retrieved through the RESTful API. The available resources can be divided into two categories: tiles (GetTile) and feature info (GetFeatureInfo).

The tile resources <ResourceURL> elements shall look as follows, note that the ​ <ResourceURL> element needs to be repeated for each supported image format of the layer:

The layer dimensions (time, elevation, etc.) support is a bit tricky, since it is not possible to predict the dimensions a layer will have and which ones the client will like to use. So the resource template should make available all the layers dimensions as query parameters and is up to the client to set the values for the dimensions he wants to use.

Consider a layer named ​ temperature. It has two dimensions: ​ time and ​ elevation. It supports PNG and JPEG image formats. It has several styles and tile matrix sets. The <Layer> element corresponding to the ​ temperature layer in the capabilities document shall then contain these two <ResourceURL> children:

The requests sent by clients may look as follows:

Note, that only the format query parameter is mandatory. The client may choose to not use the dimensions query parameters.

The feature info resources <ResourceURL> element shall look like this, note that the <ResourceURL> element shall be repeated for each supported feature info format of the layer:

Feature info <ResourceURL> elements are very similar to the tile resources ones. Layer dimensions are handled in the same way dimensions are handled for tile resources.

Consider a layer named temperature. It has two dimensions: time and elevation. It supports HTML and XML feature info formats. It has several styles and tile matrix sets. The <Layer> element corresponding to the temperature layer in the capabilities document shall then contain these two <ResourceURL> children:

The requests sent by clients may look as follows:

Note that, as similar as requesting tiles resources, only the format query parameter is mandatory, the client may choose to not use the dimensions query parameters.

The NSG WMTS profile suggests to use the following order for template variables:

The template variables order used by the implementation is different:

The implementation provides the format and dimensions as query parameters. GeoServer allows users to associate a layer with a time dimension, elevation dimension or a custom dimension. It is not possible to predict how each value of a dimension will be represented, hence encoding the dimension values using the profile suggested order makes the handling difficult to implement on the server side, and prone to interpretation errors in the URL.

Consider a layer having a time dimension. Instead of querying a specific time, GeoServer supports the common use case of requesting a time range. Also, the data can have features that have an interval of validity instead of a single point in it. An interval is expressed as follows:

If using the templates variables suggested order, the following requests would be valid for a layer with an elevation and time dimensions:

It will be very difficult to implement a URL matching pattern on the server side that would be generic enough to handle all the possible time dimension request combinations. It will not cover all the possible use cases. A human being looking at the URL would also be rather confused about the meaning of the URL.

The WMTS standard is not clear if or when a client can ignore a template variable. The standard only says that the client should substitute any template variable with the correct value. In some situations, an empty value can be considered a correct value. A possible approach is to make template variables that belong to the base path mandatory and query parameters optional.

As already discussed before, the RESTful API template mechanism allows a decoupling between the implementation and the RESTful API definition which gives a welcomed flexibility to implementors. The main drawback of this mechanism is that it adds an extra complexity to clients. Clients need to parse the capabilities documents and build resources URI using the templates.

Another issue is that since the resource format is not a valid template variable, a new resource element needs to be added to the capabilities document for each format supported by a certain resource. For example, GeoServer supports several tile formats so for each layer the following XML elements will be added:

Since the available formats are published in the capabilities document, the format could become a template variable allowing to reduce the impact of the RESTful API in the capabilities document.

The NSG WFS profile introduces the timeout parameter that can be used to control the maximum time spent by WFS to process a request. If the timeout period expires, the server should cancel the request and send an exception report to the client with the appropriate code.

This implies that the timeout parameter only controls the time the server spends producing the result but not the time the server spends sending the result to the client. Once the server starts sending the results to the client it is not possible to cancel the request and send an exception report, canceling at this stage would give the client an incomplete/corrupt document but no exception code.

GeoServer typically follows a lazy approach when processing data. The data is only retrieved when needed and if possible (when the output format allows it) the result is built and streamed to the client in parallel. This gives a significant performance boost in terms of response time and decreases the server resources usage. It is a common pattern in server implementations.

For example, let’s consider a client that executed a WFS GetFeature operation requesting as output a GeoPackage file. GeoServer parses the WFS request, creates a SQLite database on the file system, starts reading from the source and in parallel writes the elements in the GeoPackage. Once the GeoPackage file is ready GeoServer sends it to the client. In this case the timeout parameter will control a significant portion of the execution because the result is completely created on the server side and then send to the client.

Let’s suppose a GML document was requested instead. In this case GeoServer starts reading from the source and in parallel encode the elements in GML and stream them to the client. This means that the execution of the query (in a relational database for example) and the streaming of the result to the client happen in parallel. The consequence of this is that the timeout parameter only controls a very small portion of the request execution.

The alternatives allowing cancellation for this last use case are:

Another issue with the WFS timeout parameter is that there is no reliable way to test this capability, i.e. the tests have no reliable way of forcing an operation to execute for longer than the configured timeout.

The implementation and testing of the profiles raised the following recommendations. The implementation section provides a more detailed description of the recommendations:

Understanding standards and translating them to a concrete implementation is a challenging task. Interpretation doubts and ambiguous definitions need to be discussed and analyzed with the involved groups (e.g. editors of the standard, working groups, and test developers) as soon as possible.

The implicit modularity of profiles should be matched by the implementation, allowing general servers to add profile support via pluggable modules.