OGC Testbed-14: MapML Engineering Report

This ER is required to capture all of the results of the MapML task in OGC Testbed-14. In particular, it is required to collect use cases, implementations, best practices, experiences and results.

This ER makes particular emphasis on a MapML Extension Study that is the result of extensive discussion in the group.

This document is required to specify and suggest adaptations or integration of OGC Web Services (OWS) (e.g. Web Map Service (WMS), Web Feature Service (WFS), Web Map Tile Service (WMTS)) serving MapML.

From the set of topics suggested at the beginning of the testbed, the participants have addressed the following:

The following topics initially suggested at the beginning of the Testbed have not been addressed and might be included in future testbeds:

This ER also collects experiences through the Browser Extension implementation of the HTML <map> element Application Programming Interface (API) and event model, to make programming maps on the Web an exercise in the application of browser-supported standards. This ER also collects experiences through the implementation of a Cloud-based Proxy for MapML.

During OGC Testbed-14, some suggested changes got into a new version of the MapML specification (https://maps4html.github.io/MapML/spec/) including clarifications on the coordinate systems (that completely aligns it to the WMTS concepts), the inclusion of tile support for the World Geodetic System 1984 (WGS84), the use of selects as an extra parameter in extent (such as elevation, time or band names), the use of alternative styles and the possibility to use external features-based linking to files (or WFS request URLs) instead of having to embed the features directly in the main MapML.

The support for tiles and images in the specification is now consolidated, but more work needs to be done in implementing the vector part. In particular, we need to clarify the attribute encoding, the CRS used and the eventual relation with vector tiles.

Another recommendation is to explore how MapML should be integrated in social media as a media type (formerly referred to as a MIME type). In social media there is neither editable HTML nor a <map> section but just the inclusion of a MapML file in a message. This message, could say something about a position ("I’m here" or "please go to this restaurant") but also discuss about more general topics ("this is the impact of Climate Change in global temperature"). The suggested approach of having extra parameters in a MapML URL could be considered to make it possible to recycle and exchange MapML files, while pointing to a restricted area of time in them. For example, the extent of a MapML file could be changed with Bounding Box (BBOX) parameters after the name of the MapML file, as explained in the corresponding section.

The new MapML specifications define how to use WMS and WMTS services in URL templates to dynamically serve tiles or images linked to the MapML file. More work needs to be done on the integration of OGC services as a source for recovering MapML files. In contrast, WMS and WMTS are potential standards for this but none of them are currently able to create MapML files. The former is not aware of TCRSs (tile matrix sets in the OGC vocabulary) and it is not in a good position to understand the zoom level concept. The latter is not able to return a MapML document that includes more than one tile because the purpose of GetTile is the generation of only one tile. There have been some proposals in previous testbeds to have a WMTS GetTiles operation and some drafts developed in the WMS group. Unfortunately, there has not yet been a demonstration of the real performance of such operations in practice, so the proposals have thus far not been accepted as a WMTS extension.

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

Contacts

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.

MapML is unique relative to other encodings but there is some level of duplication. What makes MapML unique is that it takes Spatial Data on the Web Best Practices [3] and applies them directly to HTML users instead of favoring the web developers.

The requirements for MapML were originally published on the Web here: http://maps4html.github.io/HTML-Map-Element-UseCases-Requirements. MapML is an extension to HTML, which if implemented, implies that the browser understands map/layer semantics (however those elements are eventually named), as well as feature, property, or geometry semantics. MapML is intended to be user-oriented. It aims at enabling users to create Web pages in all manner of styles, but having the common denominator being HTML and CSS, as well as JavaScript for progressive enhancement. Today, there is no built-in map/layer behavior in web browsers, much less feature/property/geometry semantics in such browsers. MapML provides the ability to encode map/layer and feature/property/geometry semantics in one (simple) format that will be read and interpreted by web browsers directly. MapML brings geographic knowledge to the web browser, thereby making the web browser the user agent.

There is no other encoding or service that attempts to do what MapML does. GeoJSON, Geography Markup Language (GML), or KML require JavaScript interpretation and are not native on the web browsers. MapML should not be constrained by other encodings should the need for user-oriented features arise (e.g. markup in coordinate strings and possibly other requirements). A major objective of MapML is to make the browser understand not only where the user is (that is already standardized by the GeoLocation API, https://www.w3schools.com/html/html5_geolocation.asp), but also to understand where features are in relation to the user.

A MapML document is a new media type for maps on the web. It looks very similar to and it is inspired by HTML, but it is not HTML. Even if it could look like HTML, it is actually written under the rules of MicroXML.

This document uses text/mapml as the media type for MapML documents.

A MapML document can be included in an HTML document in two ways:

There is a fundamental difference between the first and the second approach. If the MapML document is linked to the HTML page, the MapML becomes opaque to the HTML page. In practice this means that the internal content of a MapML document is not part of the Document Object Model (DOM) structure of the HTML and it will not be accessible for scripting (e.g. it will not be accessible to the JavaScript code associated with the HTML page). When the MapML encoding is embedded in the HTML page, it is part of the HTML DOM and it can be read and altered by scripts.

The fact that linked MapML documents are opaque to the scripts suggests the need to have events associated with MapML linked documents, in order to notify scripts about some changes in the map produced by user interactions. This will be discussed later in this document.

The MapML specification defines 6 possible CRS types as possible values for "input@units". The following possible values are defined in the version of the MapML specification that was available for OGC Testbed-14 (September 7, 2018):

MapML is dependent on the concepts of raster tiles and two-dimensional (2D) map projections. Projected CRS are commonly expressed in 'meters' with a few exceptions (such as the equirectangular plate carréer). Traditionally we refer to these coordinates as (x, y). Projected spaces are expressed in floating point numbers and can be as precise as the technology is to store coordinates. Many of them are defined to cover large portions of the Earth.

To define raster tiles, we superimpose cells (pixels) to a region of the projected coordinates. The region will start at the so called top-left corner and will be covered by tiles to the right and downwards. To do that, we need to define 3 pairs of regular index axes (for each zoom level) that are parallel to the projected coordinates and quantizes the space in pieces. The first one divides the space in cells (often referred to as pixels). Cell space starts at the top-left corner of the tiled space, and cells (pixels) are counted with integer numbers that increase to the right and downwards. The OGC draft specification for Tile Matrix Sets refers to these coordinates as (i',j'). The second index axis appears when the cells are grouped into tiles. The tiles are numbered from the top-left corner of the tiled space and count (with integer numbers) increases to the right and downwards. WMTS refers to these coordinates as (TileCol,TileRow). There is also an internal double index inside each tile to point to a cell in a given tile. In WMTS these coordinates are referred to as (i,j).

The authors of this ER proposed the following changes and clarifications in the "input@units" table to align the concepts (not necessarily the names of the concepts) with WMTS. To do that, there was agreement on introducing a new TCRS in the MapML table that would define an equirectangular plate carréer. This TCRS has Base CRS / Projection system=CRS:84, Origin (easting,northing)=-180,90, Tile row/column size=265, Projected Bounds / LatLng Bounds=LatLng(-180,-90), LatLng(180,90) and has the following zoom level values:

Then, this ER proposes to change the table of values for input@units in the following direction:

An approach for documenting alternative CRS has been proposed, during OGC Testbed-14, consisting of the combined use of "meta" and similar capabilities. If for some reason a TCRS different for the current one is needed, the map browser can simply replace the current MapML document by an alternate one that has the same information in the desired projection.

Apart from documenting the current and alternative projections in the MapML document, it would be good to define a parameter in the headers of the GET request to be able to specify the current accepted or supported projections by the web browser in the same way that accept-language works today (see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).

which means: "I prefer OSMTILE, but might accept WGS84".

This subsection includes some features in MapML that were included in the candidate standard during this Testbed.

The current proposed encoding is a direct translation of the GeoJSON Encoding into a MicroXML. The following code is an example of how a MultiPolygon looks like in the current MapML encoding.

This subsection discusses the encoding of geometrical characteristics of a feature.

After examining the geometrical part of the features, this ER now concentrates on the attribute part. There is some consensus on the convenience of using HTML to express attributes ready to visualize. This has the issue of machine readability of the information contained in the HTML fragment. The suggestion is to use schema.org encodings to enable that.

Recently, some vendors (such as Mapbox, Google, etc) have produced encodings for vector tiles. There is no consensus of a transversal or interoperable encoding yet, what currently makes vector tiles an 'unknown media type' as far as the browser is concerned. As such, they are handled by the JavaScript layer (e.g. a leaflet plug-in), not by the web browser engine, except e.g. for the canvas API calls that might be done by the JavaScript library. In this respect, vector tiles are even less portable than PNG tiles, since for the latter the web browser engine 'understands' how to layout and paint picture formats. The main advantage of vector tiles is bandwidth conservation, which is important, but it is not the first main goal in standardization of geospatial concepts in the web browser.

MapML does not overlap or duplicate the role of vector or raster tiles. However, a MapML client engine, whether it was implemented in JavaScript or Web Assembly, or preferably by the web browser, could use vector data, (instead of, or in addition to raster tiles) to paint a map layer. To adopt vector tiles, the main barrier is the standardization of the vector tile format to the point where it is widely understood and implemented as a PNG. Finally, despite the canvas element, vector tiles styling is done by scripting, because vector tiles are not included in the DOM, hence they are not susceptible to styling via CSS.

The more direct way to apply CCS symbolization is to do it in-line by using a style attribute in the same way that it can be done in other HTML tags.

Another direct way to set styles is to use a class or and element identifier attribute to assign a CSS ruleset by its name.

Things start to be more interesting when we use a characteristic in CSS that allows for selecting elements to be symbolized depending on the values of some attributes of the element.

CSS has selectors that can be used to select element tag names, class attributes or elements id’s. An interesting capability is that selectors can be used to select whatever element name that has an attribute (using the '*' character).

As suggested by https://www.brmwebdev.com/dev/css/schema-based-styling, this can be used for semantic tagging in schema.org microdata to define the symbolization of elements that has a particular semantic annotation. This means it can be used to select features that have a particular property. In practice, if features are tagged with microdata, then elements of a particular itemtype can be selected. Going further in this approach, itemtype’s that are in a particular scope can be selected. The authors of this ER have not been able to find anyone suggesting that, but it is what you should do if you want to be precise in your selectors. This approach was already mentioned in OGC 16-053r1 [4].

Exploring all these possible combinations together, and analyzing what is possible in CSS, some important limitations in CSS were found that prevent developers from doing things that are common in GIS such us conditioning the style of a geometry to some values of the properties or specifying a style declaration value as a function of a property value.

In the experimentation done to apply CCS to features with properties and geometry, the following limitations were detected:

Some experts suggest that the limitations in the selectors syntax were imposed on purpose to limit complexity of the parses and to allow a faster parsing of the HTML-CSS styler.

One of the extensions needed the capability to apply a selector based on some properties values to the geometry. The authors of this ER propose to incorporate condition1 attribute to point another selector that will add extra conditions based on elements that are not directly the ones to symbolize. Both the selector and the condition1 should be of the same father.

A suggested possibility is:

Another extension could be to condition a declaration value (e.g. width) to a property value (e.g. lanes). This could be achieved by using a selector as a value of a symbol declaration:

This subsection assumes that CSS rule-sets are provided in an independent CSS file and linked from the MapML page.

There are two practical ways that emerged from the experiments done during OGC Testbed-14, which support a use case giving the opportunity to the user to select among a list of styles for the "same" map content.

One approach is to use the link rel approach to indicate that there are other alternative styles related to the same map available. This can be done by using the link/@rel=style to indicate alternative styles that will have a title and an href to another MapML document. The style currently in use can be tagged as "self style".

In a client, alternative styles can be expected to result in alternative presentations available in the legend (e.g. as a drop-down selector or a group of radio buttons)

With the recent introduction of selectors and URL templates in MapML, there might be other ways of achieving the exact same functionality. Actually, there are 2 similar ways of implementing a selector.

The first one involves considering the style name as a parameter in the URL template and using a select instead of an input.

The second one involves considering the style name as a parameter in the URL template and using a datalist as a selector.

In this section, the common situation of an HTML page that links to MapML documents using <layer src=""> is considered. Previously this ER discussed about the convenience that MapML documents are only read and interpreted by the web browser (and not by scripts) to avoid Cross-Origin Resource Sharing (CORS) problems. Still, it is important that the web browser supports scripts that some user actions had appended or are going to happen immediately after the event and report on the consequences on the map visualization. Events will make it possible for the script to trigger some actions on the information shown in the rest of the page that will provide some level of synchronization with what is happening in the map.

Currently, MapML is implemented by a custom element. Actually, custom elements do emit events, as described in web-map.html elaborated, to support MapML. For the moment, not much has been done with them but in some cases the latitude and longitude of the point related to a mouse action is added. This is the list of events that are mentioned in the custom element file:

It is the opinion of the authors of this ER that this long list might not be necessary. It might be better to simplify them to a few events that communicate all actions of the user. The authors of this ER propose a minimum set of events, in-line with how the form input controls works in HTML. For example, listening to a single event, the browser would be able to know about the new position and zoom level of an action of the user (whatever the origin of it) instead of having to listen to specific events of the mouse and keyboard. The following changes could be considered.

In geospatial information, the capacity of being able to overlay maps coming from different sources is a basic feature allowed by the co-registration of the positions in a common coordinate reference system (or coordinate reference systems that can be mathematically mapped).

In web browsers, due to security reasons, there is a restriction that prevents content from different domain servers from being mixed in a single page by default. This is known as CORS and means that, by default, a JavaScript programmer cannot access content coming from another server (different that the one that loaded the page). The web browser is allowed to do that in some cases: for example, the browser can render PNG files coming from different domains in the same page with no problem. The same with HTML: the browser is allowed to render HTML in an iframe even if it is not from the same server. Again, JavaScript code cannot access this iframe content by default. It is possible that a server authorizes CORS by adding some lines in the headers but this requires active collaboration of all servers involved and that is not easy to achieve.

This opens up an interesting discussion: MapML is an new media type. The whole purpose of MapML is to empower browsers with geospatial map capabilities. When MapML is adopted by web browsers directly and browsers do all the rendering, then rendering a MapML document can be considered to be equivalent to rendering a PNG. A programmer can be sure that the browser is not going to "mix" content (only overlay it) so there should not be any need for extra CORS protection. When MapML is adopted by web browsers directly such documents will be rendered without any script intervention. If MapML documents are able to escape CORS security protection that will allow overlays of n MapML documents coming from different servers to be considered a case similar to having n images (included in <img src="">) and should be shown together if there is no script intervention. Indeed, MapML files will be opaque to the script and there will be no risk of mixing content coming from different servers or executing unknown scripts. However, the programmer will not have access to the content of any MapML DOM document outside its server by default.

This is extremely important because the current situation with JavaScript map technologies (e.g. Leaflet) is very limiting. By default, you cannot render a GeoJSON file that you found elsewhere on top of your data because of CORS. WMS is the exception of this if you only deal with GetMap and images, but as soon as you try to read a capabilities document, or use GetMap for retrieving vector data you encounter the CORS restriction. If MapML documents can be shown together, ignoring CORS security, it will provide a competitive advantage of MapML to other map technologies in the web that have to face CORS security protection in other more unconventional ways.

Even if the web browser allows for showing MapML files from different sources, there is a ramification of CORS that should not be ignored. If an HTML page includes a MapML file in another domain that has a URL template that will result in including feature information that comes from a 3rd server, then the result is more unpredictable. Currently a similar situation occurs when an HTML page loads an SVG that has links to other files (e.g. an SVG describing an icon). In SVG this is not allowed if the three files come from different services. If this is going to be the final implementation decision, this would limit what MapML will be able to do anyway.

Maps4HTML can take advantage of the language negotiation already implemented in the HTTP protocol (see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). By implementing language negotiation, when an HTML page is requested by the client, the headers include a line with a list of languages that the user can understand and has specified in the browser options by preference order. The server tries to accommodate the needs of the user depending on the languages available in the server side. This can also be used in HTML documents containing maps.

MapML could also use a meta tag to mark the language of the map as well as a link rel to suggest alternative languages.

The capability of adding <select> elements in the <extent> allows for implementing support for selecting time and other dimensions in URI templates

This section describes an implementation of a CubeWerx-delivered cloud-based MapML service to proxy (or cascade) existing Canadian Geospatial Data Infrastructure (CGDI) OWS content services as MapML hosted at https://tb14.cubewerx.com/cubewerx/cubeserv/mapML/wmts.

This section describes the creation by George Mason University (GMU) of the ServerWorker proxy for MapML that uses existing CGDI OWS content services [http://www.nrcan.gc.ca/earth-sciences/geomatics/canadas-spatial-data-infrastructure/19359] as MapML, potentially hosted at https://maps4html.org/cgdi/. The proxy supports vector tiles in the client HTML <map> element and ‘offline’ MapML maps, using the ServiceWorker browser API (https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) together with the OGC GeoPackage (https://en.wikipedia.org/wiki/GeoPackage) MapML extension. The application takes a MapML document and injects the web components library call and the web-map.html call in the MapML documents. This gives automatic support to MapML documents for web browsers that do not support MapML natively (all web browsers fall in this category at the time to write this document).

To be able to exchange maps, they should exist in some form that can be saved, attached, copied and pasted. Google Maps provides a mechanism to share maps by including a short URL to the Google Maps web page with some parameters to indicate, among others, the zoom level and pan, and being able to reproduce the shared view. This URL can be pasted anywhere to exchange the map view.

The main limitation of the Google Maps approach is that it allows only map content already prepared by Google to be shared, restricting users to a nice orthophotography or a road map.

To be able to exchange maps as easy as if they were images, what is needed is to make creation easy as well as provision of a way to embed the maps on social media messages.

Imagine that a user is looking at the following forest fire map and the user would like to share it with people that might live in the area at risk:

The URL to the MapML file is this: https://geogratis.gc.ca/mapml/en/cbmtile/fdi?alt=xml

It could be good to be able to add to the URL the current view configuration. One possible way to do that is to add this to the MapML URL directly using the parameters of the extent. The following listing shows how the MapML document looks like internally.

If the extent is added into the map, the result URL will look like this: https://geogratis.gc.ca/mapml/en/cbmtile/fdi?alt=xml&txmin=-2143734.9&tymin=-1330081.2&txmax=-111730.9&tymax=701922.8 This URL needs to be interpreted by the browser that has to produce a map with the required data.

It could also be possible to consider the exchange of MapML files directly (instead of links). Internet users seem to be used to uploading files in some cases (e.g. JPEG images). There are some reasons for not considering this as a possibility: First, MapML needs to be interpreted by web browsers and no other type of client applications (that can open MapML files) are foreseen so far. Secondly, most MapML fields contain links to external content (e.g. a tile server); meaning that even if you save them in your hard drive, they cannot be used off-line in the same way that you save a JPEG file. Actually, having more tools to create and exchange MapML files should be a priority to make MapML files presence ubiquitous but it is assumed that data producers should be the ones that create them. The production of more MapML documents was one of the objectives in the current Testbed.

The current implementation of the NRCan MapML reader has the advantage of the drag and drop functionality to allow adding a map to another map and showing both simultaneously. The action is extremely easy. A user just has to drag a link from a list of possible Canadian maps and drop it on another map that the user pre-opened in another window.

Unfortunately, drag and drop is not possible on tablets and mobile phones. The action of copying a URL and pasting it in another page does not work on current Android devices. There is a workaround that involves copying the URL and pasting it in the "add MapML URL" box that is just below the map. This has the same effect that drag and drop but it is not so elegant.

Sharing maps in an Android phone is possible and elegant. A long press on a link results in a menu that has an option "share link" that opens a list of possible apps. Selecting Twitter will result in a tweet message with the URL already in it. A user only needs to complete the text and send it. If a user is already on the page, looking at the map, the 3 vertical dots icon (the so called "hamburger") offers a "share…" option that results in the same list of apps for sharing information.

OGC is proposing a new architecture for services based on Web APIs and supporting tools such as OpenAPI. The WFS Standards Working Group (SWG) has already released a draft for WFS that will include an OpenAPI description document for a service. The OpenAPI document will identify two types of resources (collections and items) that can be served as URLs using the following two URL templates:

OpenAPI allows us to define both "path" and "query" parameters. WFS has also defined a query parameter for a BBOX applicable to the first of the two URI templates.

Following the same pattern, a service is possible that is able to retrieve a collection as a portrayal. This portrayal could be retrieved as a complete representation or as a fragment. Two types of fragments can be offered: maps or tiles. Due to the nature of tiles, they could be recovered one by one or as a set of adjacent tiles. The following are the proposed URI templates that could be used to retrieve the map or the tiles.

/collections/{collectionId}/{styleId}/map/{crsId} will be the equivalent of a GetMap in WMS.

/collections/{collectionId}/{styleId}/tile/{tileMatrixSetId}/{tileMatrixId}/{tilerow}/{tilecol}.png will be the equivalent of a GetTile in WMTS.

/collections/{collectionId}/{styleId}/tiles/{tileMatrixSetId} will be the equivalent of GetTiles (a draft operation proposed in a past testbed that never became official) that is able to retrieve several tiles for a BBOX at several zoom levels in a zip file of a similar multi-part document.

/collections/{collectionId}/{styleId}/tiles/{tileMatrixSetId}/{tileMatrixId} will be almost identical to the previous one, but restricted to a single zoom level (tileMatrixId). This URI template is the perfect operation for returning a MapML file. Since it receives a BBOX as a query parameter and a zoom level (tileMatrixId) as a path parameter, it is able to return a MapML file. In the process of creating the MapML, the service that would be able to pass the parameters of the current extent and zoom level of the map. Since the service is aware of the URI templates for a single tile, it could include the URI template to retrieve individual templates directly in the MapML file.

An additional parameter is needed to know if the URLs of each tile covering the map extent needed to be explicitly included in a MapML file or a generic URI template for the tiles is desired. A third alternative could be to provide an image (or an image URI template) instead of a tile. Other parameters could limit the extent of the MapML or the zoom levels to a subset of the original available. The MapML could contain TileMatrixSet and style negotiation using the conventions that have been described in this document.

In the 'Appendix A' includes the complete YAML description of the proposed service. Here, the ER provides the fragment of the document that describes the operation that creates MapML documents.

In the previous example can be seen the MapML media type as part of the possible outputs of an HTTP 200 response.