Map Markup Language

This version:
https://github.com/Maps4HTML/MapML/tree/8d27cd82346661bcc0927bba73a3997a0b0bdbb0
Latest version:
https://maps4html.github.io/MapML/spec/
Previous version:
https://github.com/Maps4HTML/MapML/tree/7d3d39449412678e316d89bc9af159fbedc39c6c
Editors:
Peter Rushforth, Natural Resources Canada
Authors:
Maps for HTML Community Group.

Abstract

Map Markup Language is a text format for encoding map information for the World Wide Web.

The objective of MapML is to allow Web-based user agent software (browsers and others) to display and edit maps and map data without necessary customization.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

Although W3C has provided the template for this document for community use, the document is not affiliated with W3C in any way, and is not endorsed or approved by W3C.

This document is a draft of this specification, produced by an independent party. It is inappropriate to cite this specification as as a publication of the World Wide Web Consortium (W3C), or anything other than a work in progress by an independent entity.

In particular, certain aspects of this document are yet to be defined. Feedback from the community is solicited for accessibility and DOM APIs.

Intent of this Specification

MapML is needed because while Web browsers implement HTML and SVG, including the <map> element, those implementations do not meet the requirements of the broader Web mapping community. On the one hand, the semantics of maps are quite different from those of Scalable Vector Graphics, while on the other hand, the semantics of the HTML map element are incomplete or insufficient relative to modern Web maps and mapping in general. 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, while making them potentially inaccessible due to developer inattention. 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> (or a similar <new>) 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 feature properties, etc.), while maintaining a simple, declarative, accessible interface for HTML authors. At the same time, the DOM interface to the new or improved elements should provide low-level programmable mapping hooks in the style of the Web.

To achieve this it is necessary to define a new hypertext format (MapML) and media type which encodes map semantics.

This document is an evolving proposal to the Web and Mapping communities. Collaborators and implementation experience is requested. The intention is to define a new hypertext format (MapML) which encodes map layer semantics directly, but which leverages existing standards where possible and desirable, such as Cascading Style Sheets and OGC Simple Features, for example. MapML will provide an essential part of the contract between Web user agents and Web servers when map features are exchanged, in a manner based on the architectural style of the Web, in a similar way to how HTML provides (part of) the contract for documents.

Implementation Experience

MapML has been implemented using custom elements by Natural Resources Canada, which participates in the W3C Maps for HTML Community Group, as well as the Open Geospatial Consortium. It is hoped that other organizations will also implement MapML and contribute their experience back to the community via the Community Group and Github.

Changes Since the Previous Draft

Update schema, such as it is (needs more than a schema language can provide e.g. schematron or something like HTML has)

Deprecate input@type= xmin,ymin,xmax,ymax,projection.

Remove input@type=search for now (not implemented, nor yet discussed).

Add input@units=gcrs keyword.

Extend input@type=position keyword list to be based on CSS object-position property value domain

Add input@axis= latitude,longitude keywords

Remove reference to link@rel=search, which is not supported.

Add Figure 1 in examples. Change URLs to example services.

Update Abstract, stauts, intent, implementation experience,feedback and Change sections

Add link@tcrs attribute

Add link@rel=style link relation

Level of Endorsement by the Community

Please contact the W3C Maps for HTML Community Group if you would like to participate in the development and implementation of this specification.

You can also star us on Github

Patent Information

Development of this specification together with implementations is done under the terms of the W3C Software Notice and License, in accordance with the rules of the W3C Community Groups program.

How to provide feedback

Please send comments on this specification to public-maps4html@w3.org or open an issue.


Contents

  1. 1. Introduction
  2. 2. Conformance
  3. 3. Use Cases and Requirements
  4. 4. Semantics and Structure of MapML Documents
  5. 5. Examples
  6. 6. Security Considerations
  7. 7. Glossary of Terms and Datatypes
  8. 8. Schema
  9. 9. References
  10. 10. Acknowledgments

1. Introduction

This section is informative.

Map Markup Language is a text-based format which is allows map authors to encode map information as hypertext documents exchanged over the Uniform Interface of the Web. The format is defined using some characteristics of HTML, MicroXML, GeoJSON and other standards.

2. Conformance

This section is normative.

Conforming documents are documents that comply with all the conformance criteria for MapML documents. For readability, some of these conformance requirements are phrased as conformance requirements on authors; such requirements are implicitly requirements on documents: by definition, all documents are assumed to have had an author. (In some cases, that author may itself be a user agent — such user agents are subject to additional rules, as explained below.)

User agents fall into several (overlapping) categories with different conformance requirements.

Web browsers and other interactive user agents

Web browsers are one of the primary client technologies anticipated for MapML, however other categories of interactive client could also be developed, for example as extensions to / plugins for traditional Geographic Information Systems software.

Non-interactive presentation user agents

User agents that process MapML documents purely to render non-interactive versions of them must comply to the same conformance criteria as map browsers, except that they are exempt from requirements regarding user interaction.

While MapML documents are thought to describe map semantics in a standard way, the scope of this specification is intended to not overlap that of HTML documents themselves. As such, this conformance class may not be relevant, except when consuming MapML within the context of an HTML instance's user agent. For example, the legend and other supporting map related information is out of scope for MapML, whereas it is conceivably in-scope for HTML documents.

Typical examples of non-interactive presentation user agents are printers.

User agents with no scripting support

Scripting can form an integral part of a Web application. User agents that do not support scripting, or that have scripting disabled, however should still be able to display and enable map-user interaction via the affordances described in this document.

Conformance checkers

Conformance checkers must verify that a document conforms to the applicable conformance criteria described in this specification.

The term "MapML validator" can be used to refer to a conformance checker that conforms to the applicable requirements of this specification.

Schemas cannot express all the conformance requirements of this specification. Therefore, a validating XML processor and a DTD cannot constitute a conformance checker.

To put it another way, there are three types of conformance criteria:

  1. Criteria that can be expressed in a schema (RelaxNG, XML Schema etc).
  2. Criteria that cannot be expressed by a DTD, but can still be checked by a machine.
  3. Criteria that can only be checked by a human.

A conformance checker must check for the first two. A simple RelaxNG-based validator only checks for the first class of errors and is therefore not a conforming conformance checker according to this specification.

Data mining tools

Applications and tools that process HTML and MapML documents for reasons other than to either render the documents or check them for conformance should act in accordance with the semantics of the documents that they process.

Authoring tools and markup generators

Authoring tools and markup generators must generate conforming documents. Conformance criteria that apply to authors also apply to authoring tools, where appropriate.

For example, a markup generator must ensure that polygons have three or more vertices, the first and last of which have the same location.

In terms of conformance checking, an editor has to output documents that conform to the same extent that a conformance checker will verify.

When an authoring tool is used to edit a non-conforming document, it may preserve the conformance errors in sections of the document that were not edited during the editing session (i.e. an editing tool is allowed to round-trip erroneous content). However, an authoring tool must not claim that the output is conformant if errors have been so preserved.

Authoring tools are expected to come in two broad varieties: tools that work from structured databases, and tools that work on an interactive What-You-See-Is-What-You-Get media-specific editing basis (WYSIWYG).

All authoring tools, whether WYSIWYG or not, should make a best effort attempt at enabling users to create accessible, well-structured, and efficient content.

This document contains explicit conformance criteria that overlap with some RNG definitions in requirements. If there is any conflict between the two, the explicit conformance criteria are the definitive reference.

Within this specification, the key words "MUST, "MUST NOT", "REQUIRED, "SHALL, "SHALL NOT, "SHOULD, "SHOULD NOT", "RECOMMENDED, "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [RFC2119]. However, for readability, these words do not necessarily appear in uppercase in this specification.

3. Use Cases and Requirements

This section is informative.

3.1. Use Cases

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

Tiled maps: Modern map services are dominantly created by composing adjacent map 'tiles' (often bitmapped images) into a coherent and unified image of a map.

Image-based maps: Web services typically produce a single geo-referenced image which constitutes a map. MapML encodes URL references to such images, together with appropriate georeferencing metadata.

Vector-based maps: Geospatial databases, for example PostGIS, are able to serve and manipulate vector representations of features which can be symbolized according to their properties.

Multi-layer maps: Maps are often required to overlay information in such a way as to enable both visual and automatated spatial relationship processing. MapML will support the layering of information using the 'painters model', wherein elements are drawn in document order overtop of earlier elements, together with CSS styling (transparency) techniques.

Use CSS for map styles: MapML elements should be style-able with CSS rules supplied by the MapML author. For example, the MapML author should be able to link to a stylesheet from a MapML document.

Location search: A MapML service might want to allow service consumers to search within the contents of a service for a place name or an address, over which the map is repositioned when a selection is made. MapML should provide (markup) facilities to enable such searches without forcing the client download large amounts of geospatial data.

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.

3.2. Requirements

Uniform interface: No URL recipes should be required to be supported by clients - support for simple opaque URLs and standardized media types should be all that is required clients. Application state / state transitions should be conveyed in markup.

Implementation commitments: Simple, lightweight server software should be available to allow authors to serve spatial resources as MapML.

One or more accessibile Custom Element clients should be available to demonstrate client functionality.

Ease of authoring: A range of authoring situations should be supported, from simple single file services to robust MapML services over large volumes of framework data

4. Semantics and structure of MapML documents

This section is normative.

4.1. Semantics

4.1.1 Tiled Coordinate Reference Systems

A key factor which enables map "mashups" is the shared common coordinate systems and projections of the data used in the integration. On the modern Web, such interoperability is often achieved by using or assuming the use of de facto standard coordinate systems. Either the data being integrated already shares a common coordinate system, or it must be transformed into a common coordinate system prior to being integrated. This approach often works, within the limits of the assumptions. MapML documents are similar to other spatial information with regard to definition of projection and coordinate system requirements. However, MapML defines a system of communicating coordinate system information across the uniform interface of HTTP in order to eliminate assumptions in shared coordinate systems: the coordinate systems requested by the client and available from the server are represented as simple defined string identifiers defined in the table below, and exchanged in markup defined by this specification.

Tiled Coordinate Reference Systems

TCRS identifier Description Base CRS / Projection system Axis mappings Origin (x,y) Tile row/column size (px) Projected Bounds / LatLng Bounds Zoom level Resolution
OSMTILE Web Mercator-based tiled coordinate reference system. Applied by many global map applications, for areas excluding polar latitudes. EPSG::3857 / Spherical Mercator Easting → x, Northing → y -20037508.342787, 20037508.342787 256/256 LatLng(-85.0511287798,-180), LatLng(85.0511287798,180) 0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
156543.0339
78271.51695
39135.758475
19567.8792375
9783.93961875
4891.969809375
2445.9849046875
1222.9924523438
611.49622617188
305.74811308594
152.87405654297
76.437028271484
38.218514135742
19.109257067871
9.5546285339355
4.7773142669678
2.3886571334839
1.1943285667419
0.59716428337097
CBMTILE Lambert Conformal Conic-based tiled coordinate reference system for Canada. EPSG::3978 / Lambert Conformal Conic Easting → x, Northing → y -34655800, 39310000 256/256 -7786476.885838887, -5153821.09213678, 7148753.233541353, 7928343.534071138 0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
38364.660062653464
22489.62831258996
13229.193125052918
7937.5158750317505
4630.2175937685215
2645.8386250105837
1587.5031750063501
926.0435187537042
529.1677250021168
317.50063500127004
185.20870375074085
111.12522225044451
66.1459656252646
38.36466006265346
22.48962831258996
13.229193125052918
7.9375158750317505
4.6302175937685215
2.6458386250105836
1.5875031750063502
0.92604351875370428
0.52916772500211673
0.31750063500127002
0.18520870375074083
0.11112522225044451
0.066145965625264591
APSTILE Alaska Polar Stereographic-based tiled coordinate reference system for the Arctic region. EPSG::5936 / Polar Stereographic Easting → x, Northing → y -28567784.109255, 32567784.109255 256/256 -28567784.109254867, -28567784.109254755, 32567784.109255023, 32567784.10925506 0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
238810.813354
119405.406677
59702.7033384999
29851.3516692501
14925.675834625
7462.83791731252
3731.41895865639
1865.70947932806
932.854739664032
466.427369832148
233.213684916074
116.606842458037
58.3034212288862
29.1517106145754
14.5758553072877
7.28792765351156
3.64396382688807
1.82198191331174
0.910990956788164
0.45549547826179
WGS84 World Geodetic System 1984. EPSG::4326 Longitude → x, Latitude → y n/a n/a n/a 0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
n/a

All coordinate reference systems' coordinate pairs, where not explicitly marked up or identified by axis (for example, in the <coordinates> element) are defined by this specification to be in TCRS "x,y" axis order as specified in the column "Axis mappings" above. Where an external conflict of definition exists, this specification MUST be taken to be correct for MapML only. In other words, this specification overrides externally defined axis order for coordinates marked up in Map Markup Language. For coordinate reference systems where an axis might not be readily identifiable as "x" or "y" (for example, axes named "Easting" and "Northing"), this specification defines the mapping to the TCRS x (horizontal) and y (vertical) axes.

OSMTILE

This specification defines the string "OSMTILE" to be the identifier of a tiled coordinate reference system projected (in the Web Mercator system) and scaled into 19 zoom levels (0-18) at defined resolutions. The mapping of EPSG::3857 axes to MapML axes is: Easting → x, Northing → y. The origin of the OSMTILE coordinate system and tile grid is located at (x = -20037508.342787, y = 20037508.342787) in the Web Mercator projected coordinate system. The tiles are 256px X 256px in size. The OSMTILE coordinate reference system has become a de facto interoperable standard for 'slippy' Web maps, and is not redefined, merely described herein. The OSMTILE coordinate reference system is suitable for small scale mapping of the Earth, exclusive of north and south polar latitudes, where distortion is extreme.

Some of the major defining characteristics of the OSMTILE coordinate reference system include the fact that a large portion of the surface of the earth is represented by a single 256px by 256px tile (image) at zoom level 0, with successive zoom levels' tiles dividing the area represented by the parent tile into four equal quadrants, and 'nesting' perfectly within the parent tile such that each sucessive level of tiles contains 2zoom individual tiles. The geo-registration of tiles at all zoom levels is defined by the coordinate system definition, and they can thus be 'mashed up' with other spatial data in a defined manner.

CBMTILE

This specification defines the string "CBMTILE" to be the identifier of a tiled coordinate reference system projected in the Lambert Conformal Conic (LCC) system (EPSG::3978), and scaled into 18 zoom levels (0-17) at defined resolutions. The mapping of EPSG::3978 axes to MapML axes is: Easting → x, Northing → y. The origin of the CBMTILE coordinate system and tile grid is located at (x = -34655800, y = 39310000) in the LCC projected coordinate system. The tiles are 256px X 256px in size. The CBMTILE tiled coordinate reference system is suitable for small to medium scale mapping of Canada.

APSTILE

The APSTILE tiled coordinate reference system is based on the Stereographic family of map projections, with the North polar aspect, per the EPSG::5936 coordinate reference system. This projection system is suitable for displaying areas in (north) polar latitudes.

WGS84

This specification defines the string "WGS84" to be the identifier of a coordinate reference system defined by the EPSG::4326 geodetic coordinate reference system, with the mandatory provision that the mapping of EPSG::4326 axes to MapML axes is: Longitude → x, Latitude → y.. This constraint follows the definition of the default coordinate system defintion for the GeoJSON format. This is believed to enhance interoperability, not only with the GeoJSON format, but on the Web.

Despite having no associated tiling system or zoom level resolutions, WGS84 is discussed in this specification as a "tiled coordinate reference system" identifier because of the related nature of its use. It is recommended that despite having no defined zoom level resolutions, that map documents ensure that the resolution of feature data served in the WGS84 coordinate reference system is appropriate to the zoom level i.e. the inter-vertex distance should not be less than a single pixel size at a particular zoom level when mashed up with layers in other TCRS.

Other coordinate reference systems

Many other projection systems exist, and could in principle be used by map clients and servers. As such projections and associated defined tiled coordinate reference systems come into common usage, it is expected that their definitions for use in MapML and on the Web will be imported here. The contents of this document constitutes a registry of such projections.

4.1.2 Scale / Zoom levels

Scale is an essential characteristic of all geospatial information. The scale at which information is used dictates the model used for its representation. Geospatial information cannot be meaningfully combined without consideration given to its scale. Entire cities are represented on 'small scale' maps as dots, whereas on another large scale map, a single city could have many thousands of individual features in its depiction.

Not only is scale important in the portrayal of maps, it is also essential when defining the model of underlying feature data.

Map projections distort the surface of the earth in ways which suit the objectives of the projection definition. As a result of that distortion, the scale of maps in that projection varies as a function of location. "Zoom" levels are integer values chosen to be a simple numeric proxy for a scale at a defined location. For example, the OSMTILE TCRS, being based internally on the Spherical Web Mercator projection (EPSG::3857), allows us to portray a large portion of the Earth's surface, requiring relatively simple and fast math to convert to and from WGS84. Additionally, it enables the simple tiling system that has become a de facto standard. As such, it was deemed to have the properties for a globally useful projection on the Web.

Map documents encoded in MapML have a defined scale, indirectly identified by zoom level and extent. Thus, two MapML documents in the same TCRS and zoom level should be interoperable to the degree that they can be automatically and visually related. The zoom level of a MapML document is often identified as the value of the value attribute of the input[@type=zoom]. In any case, the zoom level of any MapML document SHOULD be present in document metadata as a meta element e.g. <meta name="zoom" content="0"/>. In the case where a MapML document contains an extent element, an input@type=zoom MUST be present which controls how the zoom is transmitted from client to server. Where that input has a non-empty input@value attribute, in case of discrepancy between the meta[@name=zoom]/@content and the input[@type=zoom]/@value, the latter zoom value SHALL be taken to be correct, EXCEPT in the case where there may exist more than one input[@type=zoom] and their value attributes do not agree, in which case the value of meta[@name=zoom]/@content shall be taken to be correct.

4.1.3 Extents

A MapML document is a representation of a defined portion of a two dimensional map area. In MapML, this is called an 'extent' (see below), the dimensions of which can be described by the bounding axis minimum and maximum values of the specified TCRS, or in one of its associated coordinate reference systems (PCRS,GCRS,Tilematrix,etc.). The bounds of an extent SHOULD be specified in a MapML document, by the use of coordinates and/or coordinate axes whose coordinate reference system is identified or implied by the extent/@units value. If no extent/@units element or attribute is present, the meta[@name=tcrs] element MAY describe or identify the TCRS of the MapML document. The extent/@units value SHALL be taken to be the authoritative declaration of TCRS for a MapML document.

4.1.4 Fragment identifiers

TBD

4.2 Structure

This section is normative.

4.2.1 Elements

A MapML document is a [MicroXML] document. As such, it MUST have a single root element named <mapml>. It MUST NOT have a DOCTYPE declaration; attributes named 'xmlns' and names containing a colon character ':' (U+003A) are not permitted. Other restrictions relative to XML syntax are enumerated in [MicroXML].

4.2.1 The Document object

4.2.2The <mapml> element
Categories:
n/a
Contexts in which this element can be used:
The root of a MapML document
Content model:
One <head> element, followed by one <body> element
Content attributes:
lang — the language of the document, expressed as a BCP 47 language tag.[BCP47]
DOM interface:
interface MAPMLMapMLElement : MAPMLElement {
};

The <mapml> element is the the root element of a MapML document, and must contain one <head> element followed by one <body> element.

The <mapml> element may carry a lang attribute, as defined by [HTML].

4.2.3The <head> element
Categories:
Metadata content
Contexts in which this element can be used:
As the first child element of the <mapml> element.
Content model:
One or more elements of metadata content, of which exactly one is a title element and no more than one is a base element.
Content attributes:
DOM interface:
interface MAPMLHeadElement : MAPMLElement {
};

The <head> element is for MapML document metadata content. The content may include: one <title> element, one <base> element, zero or more <link> elements, and zero or more <meta> elements.

4.2.4 The <title> element
Categories:
Metadata content
Contexts in which this element can be used:
As a child of the <head> element.
Content model:
Text
Content attributes:
DOM interface:
interface MAPMLTitleElement : MAPMLElement {
};

The <title> element should exist as the one and only <title> element in the <head> element. Its content should be a text string describing the document. It is conceivably used as a bookmark title.

4.2.5 The <base> element
Categories:
Metadata content
Contexts in which this element can be used:
As a child element of the <head> element.
Content model:
Empty
Content attributes:
href — the absolute URL to be used to resolve relative URLs in the document.
DOM interface:
interface MAPMLBaseElement : MAPMLElement {
};

The <base> element is used to identify a URL to be used to act as a base URL in order to resolve relative URLs later in the document.

There must be only one <base> element in a MapML document, and it must be in the content of the <head> element, before any MapML elements which potentially carry a URL for resolution, notably the <link> element.

4.2.6 The <meta> element
Categories:
Metadata content
Contexts in which this element can be used:
In the <head> element.
Content model:
Empty.
Content attributes:
name — Metadata name
http-equiv — Pragma directive
content — Value of the element
DOM interface:
interface MAPMLMetaElement : MAPMLElement {
           attribute DOMString name;
           attribute DOMString httpEquiv;
           attribute DOMString content;
};
Categories:
Metadata content
Contexts in which this element can be used:
If the element represents a hyperlink (has a href attribute): as a child of the head element.
If the element represents a link template (has a tref attribute): as a child of the extent element.
Content model:
Empty.
Content attributes:
href — Address of the hyperlink
tref — URL Template
rel — Relationship between the document containing the element and the destination resource
tcrs — The TCRS of the linked resource.
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
title — Title of the link
DOM interface:
interface MAPMLLinkElement : MAPMLElement {
           attribute DOMString href;
           attribute DOMString tref;
           attribute DOMString rel;
           attribute DOMString tcrs;
           attribute DOMString hreflang;
           attribute DOMString type;
           attribute DOMString title;
};
MAPMLLinkElement implements LinkStyle;

The link element allows authors to link their document to other resources.

The destination of the link(s) is given by the href attribute, which must be present and must contain a valid non-empty URL potentially surrounded by spaces. If the href attribute is absent, then the element does not define a link.

A link element must have a rel attribute. If the rel attribute is absent, then the element does not define a link.

The types of link are given by the value of the rel attribute, which generally has a value that is a single token, except in the case of the link@rel='self style' value described below. The allowed keywords and their meanings are defined below. If the rel attribute is absent, has no keywords, or if none of the keywords used are allowed according to the definitions in this specification, then the element does not create any links.

The tcrs attribute value identifies the TCRS of the linked resource, with a value from the defined set of TCRS identifiers. When rel=alternate is used together with the tcrs attribute, clients may be able to perform agent-driven content negotiation to provide a better user experience. For example, if an HTML author mistakenly enters the URL of an OSMTILE resource in their HTML layer@src attribute, but the map in which the layer takes part is declared to be CBMTILE, the MapML author can ease the potential for resultant confusion by providing appropriate rel=alternate links to equivalent MapML resources in other projections.

The link/@title value can be used in conjunction with link[@rel=license] as a string description of the link to the terms under which the MapML content is made available, while the link/@href value is used to link to an HTML document of the license terms. Note that there may be more than a single contributor to the information presented in a single extent, and it is therefore possible to have several licenses terms for a single extent, each of which will have its own <link> element in a single MapML document.

The link@rel='self style' rel value can be used to designate one of a set of alternative named style links as being the style of the current document. As such, the value of the link@title attribute will be used by the user agent to label the current style from among the list of alternate styles.

The link[@tref] element represents a URL template for a resource (e.g. tiles) which can be used by the client make requests for resources to fill its extent at zoom levels and bounds indicated by sibling input[/@type=location] elements' min and max attributes, or to (partially) identify URL targets suitable to enable query of server resources. The rel attribute contains a keyword string which identifies the role of the resource(s) for which the tref attribute value represents a URL template, which may contain zero or more input/@name variable references. Such variable references must be a case-insensitive match of sibling input elements' name attribute.

Use of the link element with the rel attribute in the "tile" or "image" state is an alternative to extent (form) submission to the extent@action URL, in that the client is responsible to calculate what tiles must be requested to cover its extent ("tile" state), or how paint an image to cover the map extent ("image" state).

The content represented by link[@tref] elements should be painted in document order of the appearance of the link[@tref] elements.

@rel values

Link type Brief description
alternate Gives alternate representations of the current document.
author Gives a link to the author of the current document.
bookmark Gives the permalink for the current extent.
license Indicates that some or all of the content of the current document is covered by the copyright license described by the referenced document.
next Indicates that the current document is a part of a series of documents which represent the extent, and that the next document in the series is the referenced document.
search Gives a link to a resource that can be used to search through the current map document and its related pages.
stylesheet Imports a stylesheet.
style Indicates a map resource that is equivalent to the current resource, in the same TCRS but with a different map style.
self Indicates that the linked resource is the current resource. When used in combination with the style rel value, indicates that the linked resource is the current selected style from a group of alternative styles for the current layer. There should only be one such link that has both rel values 'self' and 'style' in a document.
west Indicates a resource that may be used to the west of the maximum extent of the current resource, at the current zoom level.
southwest Indicates a resource that may be used to the southwest of the maximum extent of the current resource, at the current zoom level.
south Indicates a resource that may be used to the south of the maximum extent of the current resource, at the current zoom level.
southeast Indicates a resource that may be used to the southeast of the maximum extent of the current resource, at the current zoom level.
east Indicates a resource that may be used to the east of the maximum extent of the current resource, at the current zoom level.
northeast Indicates a resource that may be used to the northeast of the maximum extent of the current resource, at the current zoom level.
north Indicates a resource that may be used to the north of the maximum extent of the current resource, at the current zoom level.
northwest Indicates a resource that may be used to the northwest of the maximum extent of the current resource, at the current zoom level.
zoomin Indicates a resource that may be used at a zoom level greater than the maximum zoom of the current extent.
zoomout Indicates a resource that may be used at a zoom level less than the minimum zoom of the current extent.
panto Indicates a resource that may be used to the pan at the current zoom level.
tile The templated resource reference identifies a tile
image The templated resource reference identifies an image that covers the map extent
query The templated resource reference identifies a query resource at a location
4.2.8 The <body> element
Categories:
n/a
Contexts in which this element can be used:
As the second child of the <mapml> element.
Content model:
Features and metadata
Content attributes:
n/a
DOM interface:
interface MAPMLBodyElement : MAPMLElement {
};

The <body> element represents the content of the document.

4.2.9 The <extent> element
Categories:
Metadata content
Contexts in which this element can be used:
Required to be the first child of the <body> element.
Content model:
If the action attribute exists: A set of multiple input and zero or one link element with its rel attribute in the "query" state.
If no action attribute exists: A set of multiple input and one or more link elements with their rel attribute in either the "tile" or "image" state, and zero or one link element with its rel attribute in the "query" state.
Content attributes:
action - URL to use for form (extent) submission
enctype - Extent form data set encoding type to use for extent form submission
method - HTTP method to use for form submission
units - The name of the coordinate reference system whose measurement units are to be used by values submitted by child input elements
DOM interface:
interface MAPMLExtentElement : MAPMLElement {
           attribute DOMString action;
           attribute DOMString enctype;
           attribute DOMString method;
           attribute DOMString units;

  readonly attribute MAPMLExtentControlsCollection elements;
  readonly attribute long length;
  getter Element (unsigned long index);
  getter (RadioNodeList or Element) (DOMString name);

  void submit();
  void checkValidity();
};

The extent element represents a collection of extent-associated elements, some of which can represent editable values that can be submitted to a server for processing. When no extent is specified by a request, that is, the zoom and extent maxima (xmin, ymin, xmax, ymax) are not specified, the extent element must represent the overall extent of the entire map resource that is available.

The action, enctype, and method attributes are attributes for form submission. The units attribute is informative.

extent . elements

Returns a MAPMLCollection of the extent controls in the extent form

extent . length

Returns the number of form controls in the form (excluding image buttons for historical reasons).

extent[index]

Returns the indexth element in the extent form.

extent[name]

Returns the extent form control (or, if there are several, a RadioNodeList of the extent form controls) in the extent form with the given ID or name.

Once an element has been referenced using a particular name, that name will continue being available as a way to reference that element in this method, even if the element's actual ID or name changes, for as long as the element remains in the Document.

If there are multiple matching items, then a RadioNodeList object containing all those elements is returned.

extent . submit()

Submits the extent form.

extent . checkValidity()

Returns true if the extent's controls are all valid; otherwise, returns false.

4.2.10 The <input> element
Categories:
n/a
Contexts in which this element can be used:
Required to be a child of the <extent> element.
Content model:
Empty.
Content attributes:
type - enumerated keyword string identifies the type of input
name - the token to be used as a variable name in form serialization.
value - the current or default value of the name/value pair represented by the input
shard - a boolean attribute indicating associated datalist values be used to shard map tile requests across subdomains (the values)
list - the id of an associated datalist element to supply values for the input. Useful only with shard at this time.
min - the minimum value for the extent parameter acceptable by the server
max - the maximum value for the extent parameter acceptable by the server
step - the increment by which a value may vary between the min and max values
units - when type attribute is location, enumerated keyword string identifies the associated coordinate system for this input
axis - when type attribute is location, enumerated keyword string identifies the axis of the associated OR related coordinate system from the units attribute, for which an associated axis value will be returned. The min and max attribute values, if present, will be interpreted in the defined units of this axis.
rel - when type attribute is location, tile or image (the default if not specified) identifies the relation of this location to either a tile or an image corresponding to the map extent in which the location is found. Establishes the meaning of the position attribute to identify the location relative to the tile in question or to the map extent (the default).
position - when type attribute is location, enumerated keyword string identifies the relative position of a location
DOM interface:
interface MAPMLInputElement : MAPMLElement {
           attribute DOMString type;
           attribute DOMString name;
           attribute boolean shard;
           readonly attribute MAPMLElement? list;
           attribute DOMString min;
           attribute DOMString max;
           attribute DOMString step;
           attribute DOMString units;
           attribute DOMString axis;
           attribute DOMString rel;
           attribute DOMString position;
           attribute DOMString value;

};

The input element represents a typed data field, associated with a map extent form, to allow the user agent to request documents for a specific map area. There must be at least four input element children of the extent element, including only one of each of the following type inputs: xmin, ymin,xmax and ymax.

The type attribute controls the data type (and associated control) of the element. It is an enumerated attribute. The following table lists the keywords and states for the attribute — the keywords in the left column map to the states in the cell in the second column on the same row as the keyword.

input@type values

Keyword State Data type Control type
zoom zoom An integer value A derived property of a displayed map
location location A string value with no line breaks A location, the units and axis of which are specified by sibling attributes.
width width of the extent A string value with no line breaks .
height height of the extent A string value with no line breaks .
hidden hidden An arbitrary string n/a
xmin Minimum value of the map X axis A numerical value A derived property of a displayed map
ymin Minimum value of the map Y axis A numerical value A derived property of a displayed map
xmax Maximum value of the map X axis A numerical value A derived property of a displayed map
ymax Maximum value of the map Y axis A numerical value A derived property of a displayed map
projection projection A string value with no line breaks The tiled coordinate system name of a displayed map.

When the type attribute is in the "location" state, the input may have three associated attributes: units, axis and position. units identifies the associated coordinate system that the location is referred to. Each Tiled Coordinate Reference System (TCRS) instance may have one or more associated coordinate systems that are coordinate reference system by virtue of their defined association to the TCRS. For instance, the OSMTILE TCRS is associated to the underlying coordinate reference system known commonly as Web Mercator, by virtue of an origin location, defined in meters in the EPSG:3857 CRS plus a set of zoom level resolutions, and a transformation.

input@units values

Keyword State
tcrs The location should be serialized in units associated to the TCRS instance, i.e. pixels or in the case of WGS84, decimal degrees
pcrs The location should be serialized in units associated to the projected coordinate system associated to the TCRS instance, e.g. meters for OSMTILE, which has an associated projected coordinate reference system of EPSG:3857.
gcrs The location should be serialized in units associated to the geodetic coordinate system associated to the TCRS instance, e.g. decimal degrees for the OSMTILE TCRS, which has an underlying geodetic coordinate reference system of EPSG:4326. In the case of a TCRS such as WGS84, the gcrs and tcrs location are the same.
map The location should be serialized in units associated to the map coordinate system defined by the extent, i.e. in pixels with the origin at the upper left corner of the extent, with coordinate axes' increasing right and downwards, respectively.
tilematrix The location should be serialized in units associated to the tilematrix at the zoom level of the extent.

The meaning of the position attribute value (keyword) depends upon the presence and value of the associated rel attribute. When the rel attribute is not present or has the value image, the position attribute keyword value describes the input location relative to the ancestor extent. When rel=tile (only applicable when the units value equals tilematrix), the position attribute values describe the input location relative to the tile at the location in question.

input@position values

Keyword State
top-left Identifies a location relative to a tile or extent.
top-right Identifies a location relative to a tile or extent.
bottom-left Identifies a location relative to a tile or extent.
bottom-right Identifies a location relative to a tile or extent.
center-left Identifies a location relative to a tile or extent.
center-right Identifies a location relative to a tile or extent.
top-center Identifies a location relative to a tile or extent.
bottom-center Identifies a location relative to a tile or extent.
center Identifies a location relative to a tile or extent.

The axis keyword identifies the axis of the coordinate that the input variable represents. The coordinate system should be identified by the units attribute.

input@axis values

Keyword State
x TCRS x axis.
y TCRS y axis.
row TileMatrix row axis (parallel to y axis of TCRS).
column TileMatrix column axis (parallel to x axis of TCRS).
i Map CS i axis (parallel to x axis of TCRS).
j Map CS j axis (parallel to y axis of TCRS).
easting Projected coordinate reference system axis (parallel to x axis of TCRS).
northing Projected coordinate reference system axis (parallel to y axis of TCRS).
latitude Geodetic coordinate reference system axis (parallel to y axis of TCRS).
longitude Geodetic coordinate reference system axis (parallel to x axis of TCRS).
4.2.11 The <datalist> element
Categories:
n/a
Contexts in which this element can be used:
Required to be a child of the extent element, associated to an input element via that element's list attribute.
Content model:
One or more option elements.
Content attributes:
id - identifies the list within the current document
DOM interface:
interface MAPMLDatalistElement : MAPMLElement {
           attribute DOMString id;


};
4.2.12 The <option> element
Categories:
n/a
Contexts in which this element can be used:
As a child of the datalist element.
Content model:
Nothing
Content attributes:
value - the value to be used in form submission
label - the label to be presented to the user, if applicable
DOM interface:
interface MAPMLOptionElement : MAPMLElement {
           attribute DOMString value;
           attribute DOMString label;


};
4.2.13 The <tile> element
Categories:
Feature data
Contexts in which this element can be used:
Child of the <body> element.
Content model:
Empty.
Content attributes:
row - an integer (a Y axis value / the tile size) in the range of the tile coordinate reference system
col - an integer (a X axis value / the tile size) in the domain of the tile coordinate reference system
src - a URL from which the tile may be obtained
type - a hint about the MIME type of the resource obtainable at the src URL.
DOM interface:
interface MAPMLTileElement : MAPMLElement {
           attribute long row;
           attribute long col;
           attribute DOMString src;
           attribute DOMString type;

};

The tile element is a type of feature which is associated with a tiled coordinate reference system that subdivides or 'tiles' 2D space in a recursively repeating grid pattern, where the origin of both the tiled coordinate reference system and the grid at all zoom levels is defined in coordinates of an underlying projected coordinate reference system.

A defining characteristic of tiled coordinate reference systems is that they rely on integer grid row/col coordinates and zoom values. The use of these values in URLs can yield highly cacheable resources, which can lead to high-performance map services.

The "zoom" value is a global integer property of a MapML document whose coordinate system is defined by this specification. All MapML documents have a defined zoom value. The "zoom" value is equal to the zoom@value child of the extent element. Hence the zoom value is not a direct attribute of the tile element.

The main example of such a tiled coordinate reference system is OSMTILE, although others exist.

4.2.14 The <image> element
Categories:
Feature data
Contexts in which this element can be used:
A child of the <feature> element, which has a sibling bbox element.
Content model:
Empty.
Content attributes:
src — Address of the hyperlink
type — A hint as to the MIME type of the resource
DOM interface:
interface MAPMLImageElement : MAPMLElement {
 
};
4.2.15 The <feature> element
Categories:
Feature data
Contexts in which this element can be used:
Child of the <body> element.
Content model:
An optional bbox element, followed by either an image or geometry element, followed by an optional properties element.
Content attributes:
Global attributes
DOM interface:
interface MAPMLFeatureElement : MAPMLElement {
                  readonly attribute type
};

A feature element represents a geographic feature. A feature element has an optional properties child element, and a required child geometry element.

4.2.16 The <properties> element
Categories:
Feature data
Contexts in which this element can be used:
A child of the <feature> element, containing elements representing the properties of the feature.
Content model:
One or more unknown elements with text values. TODO allow HTML content.
Content attributes:
n/a
DOM interface:
interface MAPMLPropertiesElement : MAPMLElement {
 
};

A feature element can have zero or one properties element, which contains zero or more unknown elements, whose content is text. Note: it would be better to a content model of property child elements whose values could be HTML. TODO.

4.2.17 The <geometry> element
Categories:
Feature data
Contexts in which this element can be used:
Child of the <feature> element.
Content model:
A single geometry value, described in the table below.
Content attributes:
Global attributes
DOM interface:
interface MAPMLGeometryElement : MAPMLElement {
                  readonly attribute type
};

A geometry element has one child element, which can be a Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, or GeometryCollection.

geometry value Content model Non-schema constraints
Point A coordinates element containing a single position Axis order - x, y
LineString A coordinates element containing two or more positions Axis order - x, y
Polygon One or more coordinates elements, each containing three or more positions.

Axis order - x, y

The first and last positions in every child coordinates element are equal / at the same position.

The first coordinates element represents the outside of the polygon, and subsequent coordinates elements represent holes.

The "winding order" of positions in child coordinates should depend on the axis orientation of the coordinate reference system in use, and whether the coordinates element represents the exterior of a polygon, or a hole. For WGS84, the exterior should be counterclockwise and holes should be clockwise.

MultiPoint Two or more coordinates elements, each containing a single position Axis order - x, y
MultiLineString Two or more coordinates elements, each containing two or more positions. Axis order - x, y
MultiPolygon Two or more coordinates elements

Axis order - x, y

For each member Polygon, the same non-schema constraints apply to MulitPolygon descendant coordinates elements, as for Polygon coordinates descendant elements.

GeometryCollection One or more Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon elements For each member geometry, the same non-schema constraints apply as to the unique geometry type above.
4.2.18 The <coordinates> element
Categories:
Feature data
Contexts in which this element can be used:
A descendant of the <geometry> element, as the coordinate data which defines a feature geometry.
Content model:
One or more positions in x,y coordinate order, separated by whitespace.
Content attributes:
n/a
DOM interface:
interface MAPMLCoordinatesElement : MAPMLElement {
 
};

In MapML, features have positions in 2D space. A position is sometimes marked up with coordinate data explicitly identified by axis, for example in the tile element, the attributes row and col are used. Equally common is coordinate data which omits explicit markup of positions' axes, for example in the coordinates element. In the coordinates element, positions must be encoded in x,y order, separated by whitespace. The coordinates element is used to model the content of various geometries in MapML. Its content and the meaning of its content it depends on what geometry value it is used in. The context and content of the coordinates element is described in the geometry element table. A RelaxNG schema for MapML is provided below, however schema validation is not able to fully validate the context and content of the coordinates element. Such requirements are listed under the column "Non-schema constraints"

The positions in the coordinates element define the location of the feature. For geometry elements whose value is , LineString, MultiPoint or MultiLineString, this specification neither assigns nor requires special ordering or other constraints, apart from the axis order described above. For geometry> elements whose value is a Polygon or MultiPolygon element, the descendant coordinates elements must follow additional constraints.

4.3 Styling

MapML documents can be styled with Cascading Style Sheets.

5. Examples

This section is informative.

Prototype MapML services are available, representing tiled and vector data.

6. Security Considerations

This section is informative.

TODO Provide security considerations for the implementation and authoring of this technology here.

7. Glossary of Terms and Datatypes

This section is normative.

TODO Provide a glossary of terms and datatypes used in this specification.

8. Schema

A schema is useful for machine processing of documents, be it document creation, transformation, or validation.

8.1. RelaxNG Schema

Map Markup Language provides a schema written in RelaxNG compact syntax [RelaxNG], a namespace-aware schema language that uses the datatypes from XML Schema Part 2 [Schema2].

Unlike a DTD, the schema used for validation is not hardcoded into the document instance. There is no equivalent to the DOCTYPE declaration. Simply point your editor or other validation tool to the IRI of the schema (or your local cached copy, as you prefer).

MapML schema (under development).

9. References

9.1. Normative References

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.
Available at http://tools.ietf.org/html/rfc2119.
[RELAXNG]
Document Schema Definition Languages (DSDL) — Part 2: Regular grammar-based validation — RELAX NG, ISO/IEC FDIS 19757-2:2002(E), J. Clark, 村田 真 (Murata M.), eds. International Organization for Standardization, 12 December 2002.
Available at http://www.y12.doe.gov/sgml/sc34/document/0362_files/relaxng-is.pdf.

9.2. Informative References

[SCHEMA2]
XML Schema Part 2: Datatypes Second Edition. P. Biron, A. Malhotra, eds. World Wide Web Consortium, 28 October 2004. (See also Processing XML 1.1 documents with XML Schema 1.0 processors [XML11-SCHEMA].)
This edition of XML Schema Part 2 is https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.
The latest edition of XML Schema Part 2 is available at https://www.w3.org/TR/xmlschema-2/.
[WebIDL]
WebIDL, C. McCormack, ed. World Wide Web Consortium, work in progress, 19 December 2008.
This edition of WebIDL is https://www.w3.org/TR/2008/WD-WebIDL-20081219/.
The latest edition of WebIDL is available at https://dev.w3.org/2006/webapi/WebIDL/.
[MicroXML]
MicroXML, J. CLark, J. Cowan, eds. World Wide Web Consortium MicroXML Community Group, work in progress, 2012.
[HTML]
HTML5 A vocabulary and associated APIs for HTML and XHTML. I. Hickson, R. Berjon, S. Faulkner, T. Leithead E. Doyle Navara, E. O'Connor, S. Pfeiffer, eds. World Wide Web Consortium, 28 October 2014.
[BCP47]
Tags for Identifying Languages; Matching of Language Tags (URL: http://www.ietf.org/rfc/bcp/bcp47.txt), A. Phillips, M. Davis. IETF.
[GeoJSON]
The GeoJSON Format Specification
[OSMTILE]
Open Street Map Slippy Maps Tilenames Wiki
[EPSG-REGISTRY]
EPSG Geodetic Parameter Registry

10. Acknowledgments

The editors would like to acknowledge and thank the following people for substantive aid with this specification: .