OGC Testbed-13: MapML ER

Publication Date: 2018-01-11

Approval Date: 2017-12-07

Posted Date: 2017-11-14

Reference number of this document: OGC 17-019

Reference URL for this document: http://www.opengis.net/doc/PER/t13-NR002

Category: Public Engineering Report

Editor: Joan Maso

Title: OGC Testbed-13: MapML ER

OGC Engineering Report

COPYRIGHT

WARNING

This document is not an OGC Standard. This document is an OGC Public Engineering Report created as a deliverable in an OGC Interoperability Initiative and is not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, any OGC Engineering Report should not be referenced as required or mandatory technology in procurements. However, the discussions in this document could very well lead to the definition of an OGC Standard.

LICENSE AGREEMENT

Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications.

This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.

Table of Contents

1. Summary
2. References
3. Terms and definitions
4. Abbreviated terms
5. Overview
6. MapML encoding
7. MapML versus other formats
- 7.1. OWS Context
- 7.2. KML
8. MapML services and navigation modes
9. TileMatrixSet specification
Appendix A: Change Requests to MapML
Appendix B: Revision History
Appendix C: Bibliography

1. Summary

This Engineering Report discusses the approach of Map Markup Language (MapML) and Map for HyperText Markup Language (Map4HTML) described in: https://github.com/Maps4HTML and supported by the community in https://www.w3.org/community/maps4html/. The objective of MapML is to define a hypermedia type for geospatial maps on the web that can be embedded in HyperText Markup Language (HTML) pages. MapML is needed because while Web browsers implement HTML and Scalable Vector Graphics (SVG), including the <map> element, those implementations do not meet the requirements of the broader Web mapping community. The semantics of the HTML map element are incomplete or insufficient relative to modern Web maps and mapping in general. Currently, robust web maps are implemented by a variety of non-standard technologies. Web maps do not work without script support, making their creation a job beyond the realm of beginners' skill sets. In order to improve collaboration and integration of the mapping and Web communities, it is desirable to enhance or augment the functionality of the <map> element in HTML to include the accessible user interface functions of modern web maps (e.g. panning, zooming, searching for, and zooming to, styling, identifying features’ properties, etc.), while maintaining a simple, declarative, accessible interface for HTML authors.

The objective of this Engineering Report is to explore how MapML can be harmonized with the OGC standards mainstream and contribute to the progress of the specification avoiding unnecessary duplication. In particular, the ER proposes Web Map Service (WMS) or Web Map Tile Service (WMTS) as services that can be used to deliver MapML documents with small modifications.

Another consideration on the ER is the inclusion of the time dimension and directions operation in MapML.

1.1. Requirements

The following requirements are being addressed by the MapML Engineering Report:

Specify how the media type "text/mapml" (pending Internet Assigned Numbers Authority, IANA, registration) can interoperate and encapsulate the semantics of maps to support the stateless client-server requirements of Web browsers. Specific configurations wrapping existing OGC services (WMS, Web Feature Service (WFS), WMTS, etc)
Collect OGC community feedback about:
- TileMatrixSet (also called in the CFP Tiled Coordinate Reference System (TCRS)) definitions
- Image georeferencing markup
- TCRS/projection negotiation
- Language negotiation
- Security considerations
- Hyperlinking within and between map services
- Accessibility considerations for map feature markup
- Microdata / microformat semantic markup recommendations
- Caching discussion
- Feature styling with Cascading Style Sheets

1.2. Prior-After Comparison

OGC has not explored an approach like this before. This could bring the maps closer to the W3C community.

1.3. What does this ER mean for the Working Group and OGC in general

This work is relevant to the OWS Context standards Working Group. Both OWS Context and MapML share the objective of being able to distribute collections of geospatial resources mainly in the web. An OWS Context file could be the seed for a HTML page that contains a map representing the information in an OWS Context document in the form of MapML documents.

1.4. Document contributor contact points

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

Table 1. Contacts
Name	Organization
Joan Masó	UAB-CREAF

1.5. Future Work

This document contains several recommendations for future testbeds, OGC standards and MapML. A future version of the MapML language needs to be harmonized with OGC language and should use the OGC concepts extracted from WMTS. A future version of MapML should consider changing the encoding for features into a pure HTML encoding complemented by schema.org semantics. The WMTS standard needs to be divided into two documents, one more abstract describing the tiled reference systems, and another one describing the WMTS service. A future WMS or a WMTS extension with a new operation that is able to produce MapML documents could also be produced.

1.6. Foreword

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.

1.7. Use of notes in this document

The use of notes in this document is used to emphasize some paragraphs targeting different kind of readers. It follows the following criteria bellow:

Caution

This is a note indicating that there is a problem with the aspect discussed that needs attention. E.g. a part of the MapML current document that has not been implemented and that can be deprecated in the next version.

Note	A note. If the note starts with Recommendation to new testbeds: this means that Testbed 14 sponsors (or other Interoperability experiments) can find aspects of MapML that can be part of a more careful examination and experimentation.

Important

An important aspect to be considered in a standards. It will start with the text Recommendation to xxxx: where xxxx is the name of the standard affected.

2. References

The following normative documents are referenced in this document.

MicroXML
The <web-map> HTML Element proposal
Map Markup Language
IETF RFC 3875, The Common Gateway Interface (CGI) Version 1.1
W3C HTML 4.01 Specification 17 Forms
OGC 17-083, OGC Tile Matrix Set Standard (draft) (at requires membership (observer is enough) to WMS.SWG to get access to the document)

3. Terms and definitions

For the purposes of this report, the definitions specified in Clause 4 of the OWS Common Implementation Standard OGC 06-121r9 and the future OGC 17-083 shall apply. In addition, the following terms and definitions apply.

3.1. coordinate system

set of mathematical rules for specifying how coordinates are to be assigned to points (WMTS 1.0)

3.2. extent

the bounding box of the view in the screen

3.3. map

portrayal of geographic information as a digital image file suitable for display on a computer screen (OGC 06-042: WMS 1.3)

3.4. tile

a rectangular pictorial representation of geographic data, often part of a set of such elements, covering a spatially contiguous extent and sharing similar information content and graphical styling covering a cell of the grid defined by a tile matrix on top of a denser raster grid.

3.5. tile coordinates

a discrete coordinate system where a position is uniquely defined by a pair of integer indices for the column and row in the tile matrix, a pair of integer indices inside the tile, a long with an identifier for the tile matrix.

3.6. tile matrix

a regular grid defined on top of a more detailed raster regular grid that groups matrices of cells into tiles. Also, all tiles corresponding to a fixed scale.

3.7. tile matrix coordinates

a discrete coordinate system where a position is uniquely defined by a pair of integer indices in the denser raster grid where the tile matrix is defined (starting in the top left corner) a long with an identifier for the tile matrix.

3.8. tile matrix set

a collection of tile matrices defined at different scales

4. Abbreviated terms

API Application Programming Interface
ER Engineering Report
HTML HyperText Markup Language
HTTP HyperText Transport Protocol
KVP Key and Value Pair
Map4HTML Map for HyperText Markup Language
MapML Map Markup Language
OWS OGC Web Services
SVG Scalable Vector Graphics
TCRS Tiled Coordinate Reference System
WFS Web Feature Service
WMS Web Map Service
WMTS Web Map Tile Service
XML Extendable Markup Language

5. Overview

We can classify the standards depending on the level of complexity the developer needs to face. In the modern era of Internet distributed applications, developers tend to prefer standards that hide the complexities of the protocols involved that allow them to concentrate on user interaction. This results in a proliferation of Application Programming Interfaces. But there is still another level of simplification where you can concentrate in describing and tagging the content and assume a default user interaction. This has been the strategy and the success of HTML. In summary, depending on the level of complexity they expose, we can separate standards in three groups:

OGC Web Services
- They describe how clients and services exchange messages (and information) based on a distributed architecture and a protocol.
- e.g. Web Map Tile Service
Application Programming Interface (API)
- Describes a set of operations or functions that allow encoding functionality on top of a programming language and programming libraries. APIs hide the protocol and focus on facilitating tools for encoding user interfaces.
- e.g. Google Maps API
Document standards
- Describe a data encoding including raw information and some clues about the preferred styling for presentation. Presenting the information to the user implies that there should be an engine that is able to parse the document and take specific and appropriate actions to build the user interface. The developer can concentrate on the content and assume default behaviors of common user interfaces.
- e.g. KML, MapML

Traditionally, the OGC has concentrated its efforts on standards that deal with OGC Web services (1st level) and on document standards (3rd level), while companies are offering API solutions (2nd level) that, at the moment, are mainly not interoperable. This Engineering Report focuses on the document level (3rd level) for map visualization. Its objective is to examine the MapML approach as a new MIME type to distribute maps over the Internet that can be embedded in web pages without any immediate need for JavaScript code, provided that web browsers implement support for this document type. It should be mentioned that elimination of JavaScript from mapping is a non-objective. In the short to medium term, JavaScript will be necessary to 'simulate' native support for extended map semantics, through the Custom Elements candidate standard.

5.1. MapML use cases

Hyperlinks between and within services: MapML should allow service-level links such that service providers can link together / federate to provide apparently seamless spatial coverage.

Feature identification: If a MapML document includes features, the MapML author should be able to markup any or all of those features in a way which lends itself to feature identification and property display.

Attribution: MapML documents encode citation information on a per-request basis, making it available as markup in the response.

The following usage scenarios illustrate some of the ways in which Map Markup Language might be used for various applications.

5.1.1. Embedding a map in a web page

A map can currently be embedded in a web page by means of the HTML <map> element. However, such a map is essentially static: it allows the HTML author to draw hyperlinks over shapes on a static image. Maps should allow us to interact with map content in a way that is more interesting. To be able to do this, a new child element is introduced to the <map> element in the form of the <layer> element. A <layer> element allows to point to a MapML document describing content of a map layer. Multiple layers can be included in a single map, each by means of its own URL. A similar construct is used for the HTML <video> element, which can have one or more source files included as child <source> elements. (Of course, with a video, the most appropriate source file is chosen from the child <source> elements. In contrast, a <map> element’s child <layer> elements are stacked and overlayed together as a group.)

5.1.2. Story maps and story telling

MapML could be used as a story maps mechanism where the user navigates progressively through the content and learns by reading a combination of text and map scenes. In story maps the narrative flow is linear but the user can play with the maps presented and verify the textual description that accompanies the map. Commonly, the story is presented as a single page that can be scrolled up and down with maps that are controlled by the text shown or text fragments each one accompanied by its respective map. To make story telling possible, more than one map needs to be supported in a single page.

An example of story maps can be shown here: https://grid-arendal.maps.arcgis.com/apps/Cascade/index.html?appid=54b862ef079445d9a99b8f6249249e4d

$images\storymap1$

Figure 1. Scene 1 of the ECOPotential Protecting Marine Mammals in Crowded Waters Storymap

$images\storymap2$

Figure 2. Scene 2 of the ECOPotential Protecting Marine Mammals in Crowded Waters Storymap

$images\storymap3$

Figure 3. Scene 3 of the ECOPotential Protecting Marine Mammals in Crowded Waters Storymap

5.2. MapML data model

A MapML document is similar to an HTML document in that it consists of 2 main blocks: the <head> and <body> elements. Within the <body>, there are four spatial content types: the extent form, tiles or images, and features.

Extent defines the area the MapML layer shows and the area it eventually can cover. It also contains a mechanism to describe the action needed to send to the server to get a new MapML in response to a user action.
Tile describes the tiles (rendered raster fragments) necessary to cover the area that extent defines.
Image describes the location and orientation of the upper left corner of a geo-referenced image.
Feature describes a collection of features (vector) that cover the area that extent defines.

The following UML diagram describes the structure of a MapML document in the left-hand side. The right-hand side describes how to include a MapML document in an HTML file, and will be explained below.

$images\HTMLMapMLFormatUML$

Figure 4. HTML and MapML data model UML class diagram

In order for a map to be 'dynamic', it requires a server that creates MapML documents in response to the user actions such as panning, zooming or textual searches. This MapML server is typically implemented as a facade to OGC and non-OGC services (see MapML services and navigation modes in this document for more details). This way MapML hides the complexity of the underlying implementations and translates their content to a set of elements that the web browser client can easily draw and presents them to the user.

The next clause MapML encoding presents the details of the elements of MapML, how it is composed, and discusses possible alternatives and improvements. MapML services and navigation modes presents the particularities of MapML services. TileMatrixSet specification clause presents a summary of a new standard candidate (OGC 17-083) that was extracted from WMTS 1.0. This document describes TileMatrixSets and that can be used as the bases for other standards such as GeoPackage, WMTS and MapML.

5.3. MapML in practice

MapML is a document type for HTML ingestion of maps. This means that a MapML document has to be included in a HTML page in order to be visualized.

5.3.1. Including a MapML in a HTML page

This standard starts by proposing an extension to the old <map> element that represented a map browser that starts in a lat,lon position in a projection (that is actually a tiled CRS: a tile matrix set) at a given zoom level. Apart from the old area elements for descended compatibility to old browsers, it has a new element type that is called layer that references one or more MapML files.

<!DOCTYPE html>
   <head>
     <title>Web Map Template - default style</title>
     <script src="http://geogratis.gc.ca/mapml/client/bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
     <link rel="import" href="http://geogratis.gc.ca/mapml/client/bower_components/web-map/web-map.html">
   </head>
   <body>
      <map is="web-map" projection="OSMTILE" zoom="3" lat="60.5005254" lon="-98.2617190" width="900" height="400" controls>
          <layer- label="Canada Base Map - Transportation (CBMT)" src="http://geogratis.gc.ca/mapml/en/osmtile/cbmt/" checked />
      </map>
   </body>
</html>

The source of the example can be found here: http://geogratis.gc.ca/mapml/en/osmtile/cbmt/

This is all you have to do as a web designer to include a map in your web page.

5.3.2. A MapML file example

Behind an easy to do link "http://geogratis.gc.ca/mapml/en/osmtile/cbmt/" in the previous example there is the hidden complexity of the MapML implementation.

Let us start to say that in the previous layer section there is a src link to the http://geogratis.gc.ca/mapml/en/osmtile/cbmt/ URL that is actually a MapML MIME type (text/mapml) that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<mapml>
  <head>
    <title>Canada Base Map - Transportation (CBMT)</title>
    <base href="/mapml/en/osmtile/cbmt/"/>
    <link href="https://www.nrcan.gc.ca/earth-sciences/geography/topographic-information/free-data-geogratis/licence/17285" rel="license" title="Canada Base Map - Natural Resources Canada"/>
  </head>
  <body>
    <extent action="/mapml/en/osmtile/cbmt/" enctype="application/x-www-form-urlencoded" method="get" units="OSMTILE">
      <input max="256.0" min="0.0" name="xmin" type="xmin"/>
      <input max="256.0" min="0.0" name="ymin" type="ymin"/>
      <input max="256.0" min="0.0" name="xmax" type="xmax"/>
      <input max="256.0" min="0.0" name="ymax" type="ymax"/>
      <input max="15" min="0" name="zoom" type="zoom" value="0"/>
      <input name="projection" type="projection" value="OSMTILE"/>
    </extent>
  </body>
</mapml>

Once the MapML engine gets a file, it determines the properties of the extent of the layer and the minimum, maximum zoom and the CRS projection. Then it goes back to the <map> section in the HTML page to calculate the real extent (xmin, xmax, ymin, ymax) that corresponds to the zoom="3" lat="60.5005254" lon="-98.2617190" that covers the width="900" and height="400". The result of this calculation is not done in CRS coordinates but in the tilematrix zoom 3 pixel coordinates (the so called "tilematrix" coordinates) that starts at the origin of the time matrix (Top-left corner). It virtually inputs it in the xmin, xmax, ymin, ymax and zoom values and submits the extent in the same way that a form is submitted. Since the method is GET and the enctype is x-www-form-urlencoded, the engine builds a URL with the form element name and values pairs and sends it to the server. In this case the request is: http://geogratis.gc.ca/mapml/en/osmtile/cbmt/?xmin=-104&ymin=389&xmax=1034&ymax=789&zoom=3&projection=OSMTILE

Please note that coordinates provided in the URL and in the responding MapML are also in tile matrix coordinates.

The return of this request contains a list of the URLs of all tiles that need to be requested to compose the map visualization area:

<?xml version="1.0" encoding="UTF-8"?>
<mapml>
  <head>
    <title>Canada Base Map - Transportation (CBMT)</title>
    <base href="/mapml/en/osmtile/cbmt/"/>
    <link href="https://www.nrcan.gc.ca/earth-sciences/geography/topographic-information/free-data-geogratis/licence/17285" rel="license" title="Canada Base Map Â© Natural Resources Canada"/>
  </head>
  <body>
    <extent action="/mapml/en/osmtile/cbmt/" enctype="application/x-www-form-urlencoded" method="get" units="OSMTILE">
      <input max="2048.0" min="0.0" name="xmin" type="xmin" value="-104.0"/>
      <input max="2048.0" min="0.0" name="ymin" type="ymin" value="389.0"/>
      <input max="2048.0" min="0.0" name="xmax" type="xmax" value="1034.0"/>
      <input max="2048.0" min="0.0" name="ymax" type="ymax" value="789.0"/>
      <input max="15" min="0" name="zoom" type="zoom" value="3"/>
      <input name="projection" type="projection" value="OSMTILE"/>
    </extent>
    <tile col="1" row="2" src="https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT_CBCT_GEOM_3857/MapServer/tile/3/2/1?m4h=t"/>
    <tile col="2" row="2" src="https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT_CBCT_GEOM_3857/MapServer/tile/3/2/2?m4h=t"/>
    <tile col="1" row="1" src="https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT_CBCT_GEOM_3857/MapServer/tile/3/1/1?m4h=t"/>
...
    <tile col="4" row="1" src="https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT_TXT_3857/MapServer/tile/3/1/4?m4h=t"/>
    <tile col="4" row="3" src="https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT_TXT_3857/MapServer/tile/3/3/4?m4h=t"/>
  </body>
</mapml>

Figure 5. Visual result of the HTML page with the map

On the server side, there is an application that is producing these MapML responses. The application identifies the CBMT layer and knows about the ArcGIS web tile service that is able to provide the needed tiles. In this case we discover that the layer is actually associated with two datasets in an ArcGIS rest service: CBMT_TXT_3857 and CBMT_CBCT_GEOM_3857 so that, they will be presented as overlayer datasets in the map browser. Two URL examples are: https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT_CBCT_GEOM_3857/MapServer/tile/3/2/2?m4h=t and https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT_TXT_3857/MapServer/tile/3/2/2?m4h=t