Map Markup Language

This specification describes Map Markup Language (MapML), which is an extended subset of HTML, for maps. MapML extends the semantics of several [[[HTML]]] elements, and specifies a small set of new, mapping-specific elements, in the HTML namespace ("http://www.w3.org/1999/xhtml").

MapML is designed to specify a declarative markup vocabulary that specifies some of the capabilities laid out by the [[[UCR-Web-Maps]]] specification. As capabilities are identified, they will be discussed in issues until they can be recognized as requirements, designed and subsequently specified through evolution of this document.

Implementation Experience

MapML is 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.

Prototype Map Markup Language services are provided by Natural Resources Canada as part of the Canadian Geospatial Data Infrastructure.

The reader is requested to contact the editor with any other known implementations of Map Markup Language or other implemented support for this proposal.

The customized built-in HTML <map> element and <mapml-viewer> autonomous custom element were built, and are maintained by the Maps for HTML Community Group. [[Web-Map-Custom-Element]]

MapML services are supported by the GeoServer MapML Extension [[GeoServer-MapML]].

MapML is being integrated into MapServer [[MapServer-MapML]].

MapML can be created with the open source Geospatial Data Abstraction Library [[GDAL-MapML]].

Changes

Substantial changes to this specification
  1. : Update schema, such as it is (needs more than a schema language can provide e.g. schematron or something like HTML has).
  2. : Deprecate input@type xmin, ymin, xmax, ymax, projection.
  3. : Remove input@type=search for now (not implemented, nor yet discussed).
  4. : Add input@units gcrs keyword.
  5. : Extend input@type=position keyword list to be based on CSS object-position property value domain.
  6. : Add input@axis latitude, longitude keywords.
  7. : Remove reference to link@rel=search, which is not supported.
  8. : Update Abstract, status, intent, implementation experience, feedback and Changes sections.
  9. : Add link@tcrs attribute.
  10. : Add link@rel=style link relation.
  11. : Add select element.
  12. : Add label element.
  13. : Rename link@tcrs to link@projection.
  14. : Add "features" link relation.
  15. : Changes in input@units descriptions about WGS84.
  16. : Added an equirectangular tiling schema for WGS84.
  17. : Added a table of the different Coordinate System used.
  18. : Better connecting TCRS table with input@units values.
  19. : Align prose for allowed link@href context with schema.
  20. : Fix issue with description of multi-geometries as being 'two or more', replace with 'One or more'.
  21. : Fix issue with CamelCase of geometry types, replace with lowercase.
  22. : Fix issue with inconsistency with GeoJSON multipoint coordinate encoding.
  23. : Fix the order of parameters to the LatLng(lat,lng) pseudofunction in the definition of WGS84.
  24. : Merge The HTML <map> element proposal into this specification.
  25. : Remove rel=search value.
  26. : Remove feature type property from IDL.
  27. : Add feature element's zoom attribute.
  28. : Update feature element's content model to reflect implementation.
  29. : Add controlslist attribute to the map element.
  30. : Update abstract to describe where MapML syntax and semantics fit into HTML.
  31. : Update Implementation Experience.
  32. : Remove MicroXML references, update introduction to id MapML as an extension to HTML.
  33. : Add featurecaption element.
  34. : Add required text for text/mapml MIME media type registration with IANA.
  35. : Remove the line and marker values of the shape attribute.
  36. : Update Categories, Content model and Content attributes of various elements.
  37. : Remove HTMLExtentControlsCollection attribute, per #212
  38. : Remove undefined and unresolved LinkStyle interface reference, per #212
  39. : Remove legendLinks attribute and interface definition and reference, per #212
  40. : Remove datalist element and associated input shard and list attributes.
  41. : Add layer.zoomTo() method.
  42. : Remove nopan from controlslist attribute. Add label, , and checked attributes to extent element
  43. : Remove map and area element discussion, to focus on mapml-viewer.
  44. : Add map-caption element. Add static attribute to mapml-viewer element. Add noscale, geolocation to controlslist values. Add HTMLMapmlViewerElement methods forward(), back(), reload(), geojson2mapml to WebIDL interface. General edits up to line 928.
  45. : Remove discussion of WGS84 from projection attribute definition.
  46. : Add initial draft spec for mapml2geojson().
  47. : Add initial draft WebIDL for geojson2mapml(). Add prose for back, forward, reload.
  48. : Add HTMLGeometryChildElement abstract interface
  49. : Update Authoring section. Include definitions of local and remote content.
  50. : Correct error in contexts in which extent is found. Add opacity attribute to layer. Update editors. Add WebIDL for layer opacity; Add or update extent attributes for label, checked, hidden, opacity and disabled. Update extent content model to add allowed metadata content for zoom and extent.

Introduction

Map Markup Language is a text-based format which allows map authors to encode map information as hypertext documents exchanged over HTTP [[rfc2616]]. The format is defined using some characteristics of [[[HTML]]], [[[rfc7946]]], [[[WMS]]], [[[WMTS]]], and other standards as noted. [[HTML]] [[rfc7946]] [[WMS]] [[WMTS]] Currently, there is only an XHTML syntax of MapML, that relies on custom elements' standard syntax. In the future, the intention is to extend the HTML parser to include the definitions of the new elements, and thereby enable an HTML syntax of MapML, one that is compatible with existing browsers' HTML parser modes.

This specification describes a proposed syntax and behavior for a new HTML mapping widget element, the standard name of which is left undefined at this time. The tag name of the polyfill custom element of the widget is <mapml-viewer>, so that it is not confused with the existing HTML map element. This naming follows the recommendation of the W3C Technical Architecture Group [[design-principles]] by using the custom elements 'namespace' mechanism (hyphenated element names) to ensure that the existence of the polyfill will not impede the rollout of a new platform feature. [[polyfills]]

Use Cases and Requirements

This document is guided by, and should be evaluated against the [[[UCR-Web-Maps]]].

The polyfill documentation pages for MapML elements contains an evaluation of the element and the polyfill compared with the documented requirements that the particular feature relates to.

Web Maps

A Web map is an embedded interactive content widget defined by the mapml-viewer element, in conjunction with any map-caption and layer element descendants. A Web map normally represents a region of the earth's surface in two dimensions, and enables dynamic cartographic Web applications in [[HTML]] documents.

Web mapping elements and API

The <mapml-viewer> element

Categories:
Flow content.
Phrasing content.
Palpable content.
Embedded content.
Interactive content.
Contexts in which this element can be used:
In local HTML content, where embedded content is expected.
Content model:
Zero or more layer elements, preceded or followed by zero or one map-caption elements.
Content attributes:
Global attributes.
zoom — A non-negative integer zoom value.
lat — A decimal degrees latitude value for the map center.
lon — A decimal degrees longitude value for the map center.
projection — A case-sensitive string identifier of the MapML coordinate reference system used by the map. The default if not present is OSMTILE.
controls — Show user agent controls.
controlslist — Show/hide specific user agent controls.
width — Horizontal dimension in pixels.
height — Vertical dimension in pixels.
static — Disable map interactivity.
Tag omission in text/html:
Neither tag is omissible.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
role=map

role: application

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

For implementers
DOM interface:
          [Exposed=Window]
          interface HTMLMapmlViewerElement : HTMLElement {
            [HTMLConstructor] constructor();
            
            [CEReactions] attribute unsigned short zoom;
            [CEReactions] attribute double lat;
            [CEReactions] attribute double lon;
            [CEReactions] attribute DOMString projection;
            [CEReactions] attribute boolean controls;
            [SameObject, PutForwards=value] readonly attribute 
                              DOMTokenList controlsList;
            [CEReactions] attribute unsigned long width;
            [CEReactions] attribute unsigned long height;
            [CEReactions] attribute boolean _static; 
            undefined zoomTo( double latitude, double longitude, 
                              optional unsigned short zoom);
            undefined back();
            undefined forward();
            undefined reload();
            [NewObject] HTMLLayerElement geojson2mapml( object json, 
                              optional MapMLGenerationOptions options = {} );
          }; 
          dictionary MapMLGenerationOptions {
                            DOMString label = "json.title | json.name | 'Layer'";
                            FeatureCaptionOptionInterface caption;
                            FeaturePropertiesOptionInterface properties;
                            FeatureGeometryOptionInterface geometryFunction;
          };
          callback CaptionCallback = DOMString (object geojsonFeature);
          callback PropertiesCallback = HTMLElement ( object geojsonFeature );
          callback GeometryCallback = HTMLGeometryChildElement ( 
                                          HTMLGeometryChildElement element, 
                                          object geojsonFeature );
          [Exposed=caption]
          interface FeatureCaptionOptionInterface {
                    stringifier;
                    attribute DOMString CaptionCallback;
          };
          [Exposed=properties]
          interface FeaturePropertiesOptionInterface {
                    attribute HTMLElement PropertiesCallback;
          };
          [Exposed=geometryFunction]
          interface FeatureGeometryOptionInterface {
                    attribute HTMLGeometryChildElement GeometryCallback;
          };
          

The mapml-viewer element, in conjunction with child map-caption and layer elements, defines a map media element.

The zoom content attribute indirectly identifies an initial scale of the map.

The zoom IDL attribute must reflect the content attribute of the same name.

The lat and lon content attributes locate the initial center of the map.

The lat and lon IDL attributes must reflect the content attribute of the same name.

The lat, lon and zoom attributes have no dynamic effect (they only control the default initial state of the element).

The location and zoom level of the map created with the mapml-viewer element can be dynamically changed via the zoomTo() API method, which will also change the zoom, lat and lon attributes.

The controls attribute is a boolean attribute. If present, it indicates that the author has not provided scripted controls and would like the user agent to provide its own set of controls.

If the attribute is present, or if scripting is disabled for the media element, then the user agent should expose a user interface to the user. This user interface should include features to zoom in, zoom out, toggle the "on/off" status of layers, and show the media content in manners more suitable to the user (e.g. fullscreen map or in an independent resizable window). Other controls may also be made available.

The controls IDL attribute must reflect the content attribute of the same name.

The controlslist attribute, when specified, helps the user agent select what controls to show on the media element whenever the user agent shows its own set of controls. Its value must be an unordered set of unique space-separated tokens that are ASCII case-insensitive.

The controlsList IDL attribute must reflect the value of the controlslist content attribute.

The supported tokens for controlsList's DOMTokenList are the allowed values of the controlslist attribute and supported by the user agent. The allowed values are nofullscreen, nolayer, noreload, nozoom, noscale, and geolocation.

The nofullscreen keyword hints that the fullscreen mode control should be hidden when using the user agent's own set of controls for the media element.

The nolayer keyword hints that the layer control should be hidden when using the user agent's own set of controls for the media element.

The noreload keyword hints that the reload control should be hidden when using the user agent's own set of controls for the media element.

The nozoom keyword hints that the zoom controls should be hidden when using the user agent's own set of controls for the media element.

The noscale keyword hints that the scalebar control should be hidden when using the user agent's own set of controls for the media element.

The geolocation keyword hints that a control to allow the user to enable client-side representation of the user agent's location should be presented. Triggering the control should invoke an interaction to obtain a time-limited express permission [[permissions]] to display the user agent's location on the viewer.

Hiding these aspects of the user agent's own controls does not necessarily disable the related functionality. For example, the user agent might present the same functionality through a context menu or keyboard shortcut.

A user agent MAY ignore the author's preference when it makes sense.

A user agent might ignore the nofullscreen keyword if the content area containing the map is small, such as on a mobile device.

The projection attribute value identifies the tiled coordinate reference system for the mapml-viewer and the fallback tiled coordinate reference system for its content layer elements. Layers share the projection declared by their parent mapml-viewer either by using the fallback projection value from the parent, or via an optional child meta element specifying the projection via that element's name and content attribute values. The default value of the projection, if the content attribute is not present, is OSMTILE. The complete set of defined tiled coordinate reference systems can be found in the Tiled Coordinate Reference Systems table.

The mapml-viewer element supports the width and height dimension attributes. [[HTML]]

The default object size is a width of 300 CSS pixels and a height of 150 CSS pixels. [[css-images-3]]

The back, forward and reload operations allow the manipulation of the mapml-viewer's viewport history stack. Each time the mapml-viewer's viewport comes to rest, its location (center coordinates and zoom level) is pushed onto the viewport history stack. The back operation will go back (down the stack) one increment in the viewport history stack. The forward operation will go forward (up the stack) by one increment, if there are more recent viewport locations on the stack. The viewport history content is erased, having all its entries deleted, through the reload operation. The state of the viewport history stack is reflected by the interactive or disabled state of the Forward, Back and Reload viewer context menu items, as well as by the interactive state of the viewer reload control button.

The geojson2mapml operation transcribes a GeoJSON [[rfc7946]] FeatureCollection or Feature object into a layer element. geojson2mapml accepts two arguments: the required JSON object, conforming to a GeoJSON [[rfc7946]] FeatureCollection or Feature, and an optional dictionary object of options. geojson2mapml creates and adds a layer element as the last child of the mapml-viewer element on which it is invoked. The created layer element contains one feature element for each GeoJSON [[rfc7946]] Feature from the input JSON object.

mapml2geojson options

The label option specifies the title of the output layer element. The default used will be, in order of preference, the name foreign member value, the title foreign member value of the FeatureCollection or Feature object, or the fixed 'Layer' DOMString value.

The caption option specifies the source of the output featurecaption value for each output feature. If caption is set to a DOMString value, that value will be sought as the name of a properties member, the value of which property will be used as the output featurecaption. If no such properties member exists, the fixed DOMString value itself will be used as the output featurecaption value. If caption is set to a function value matching CaptionCallback, that function will be called for each output feature, and its return DOMString value will be used as the features' featurecaption value. If no caption value is provided, the default source of featurecaption in output feature elements will be, in order of preference, the Feature object's id member, it's name foreign member value, or its title foreign member value.

The properties option specifies how GeoJSON [[rfc7946]] Features' properties members are mapped to the properties element content. It accepts a callback function value. The default function, if no properties option is set, maps input Feature member properties members to a two-column HTML table element, corresponding to the following Relax NG compact syntax grammar:

default namespace = "http://www.w3.org/1999/xhtml"
namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
start =
  element table {
    element thead {
      element tr {
        element th {
          attribute role {
            ## The value of the role attribute is set to "columnheader", 
            ## designating the meaning of contained cell text ("Property name") 
            ## as a column header value
            text
          },
          attribute scope {
            ## The value of the scope attribute is set to "col",
            ## designating that what is contained in corresponding table cells 
            ## as a column value of the "Property name" column. 
            text
          },
          ## The en value of this th is set to "Property name". 
          ## This string shall be localized to the locale of the user agent.
          text
        },
        element th {
          attribute role {
            ## The value of the role attribute is set to "columnheader", 
            ## designating the meaning of contained table text 
            ## as a column header value
            text
          },
          attribute scope {
            ## The value of the scope attribute is set to "col", 
            ## designating that what is contained is a column value. 
            text
          },
          ## The en value of this th is set to "Property value". 
          ## This string shall be localized to the locale of the user agent.
          text
        }
      }
    },
    element tbody {
      element tr {
        element th {
          attribute scope {
            ## The value of the scope attribute is set to "row", 
            ## designating this as a table data row
            text
          },
          ## The text value of this cell is set to the properties' 
          ## property member name from the input Feature
          text
        },
        element td {
          attribute itemprop {
            ## The text value of the itemprop attribute is set to the 
            ## properties' property member name from the input Feature
            text
          },
          ## The text value of this cell is set to the value of the GeoJSON 
          ## properties' property member from the input Feature
          text
        }
      }
    }
  }
          

The geometryFunction option allows control over the output geometry element content. The default function transcribes the GeoJSON [[rfc7946]] Feature member's geometry value to the corresponding geometry child element. The function receives two arguments: the default geometry child element calculated that represents the input GeoJSON [[rfc7946]] Feature's geometry member value, and the input GeoJSON Feature object. The function returns a geometry child element.

The <map-caption> element

Categories:
None.
Contexts in which this element can be used:
In local HTML content, as the first or last child of a mapml-viewer element.
Content model:
Phrasing content.
Content attributes:
Global attributes.
Tag omission in text/html:
Neither tag is omissible.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
Uses HTMLElement.

The map-caption element allows the HTML author to assign an accessible name to a map viewer. If the viewer is part of a generic mapping application that allows the user to navigate any location in the world, a location-specific map-caption may not be appropriate, and a more generic caption may be necessary.

In other situations, the map-caption element allows the author to describe the central reason for the map. Often that reason is a combination of a location and a theme.

The <layer> element

Categories:
None.
Contexts in which this element can be used:
In local HTML content, as a child of the mapml-viewer element.
Content model:
If the src attribute is present: Nothing. If no src attribute is present: Metadata content describing nested Map Markup Language content.
Content attributes:
Global attributes.
src — The URL of the layer resource.
label — A label for the layer in the layer control, if the layer is not hidden. The map author's title element takes precedence over label, if available.
checked — Turn the layer on/off dynamically on the map.
hidden — Visibility status of the layer in the layer control. Does not affect visibility of the layer on the map.
opacity — An initial opacity value which is reflected to the exposed user interface in the layer control for opacity. Opacity values have a decimal range from 0 (transparent) to 1.0 (opaque)
referrerpolicyReferrer policy for fetches initiated by the element.
crossorigin — A CORS settings attribute, specifies how the element handles crossorigin requests.
Tag omission in text/html:
Neither tag is omissible.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
          [Exposed=Window]
          interface HTMLLayerElement : HTMLElement {
            [HTMLConstructor] constructor();
            
                     attribute DOMString src;
                     attribute DOMString label;
                     attribute boolean checked;
            readonly attribute boolean disabled;
                     attribute boolean hidden;
                     attribute double opacity;
                     attribute DOMString referrerPolicy;
                     attribute DOMString? crossOrigin;
                               undefined zoomTo();
            object? mapml2geojson(optional GeoJSONGenerationOptions options = {}); 
          };
          dictionary GeoJSONGenerationOptions {
                    object propertyFunction;
                    boolean transform = true;
          };
          callback propertyFunction =  object ( HTMLPropertiesElement properties); 
          

The mapml-viewer element displays its child layer elements similarly to (partially) transparent "acetate" layers on a (paper) map. The layers follow the painters model, whereby layer elements are displayed on top of previous siblings according to their document order. layer transparency is controlled by the opacity attribute.

In contrast to the HTML media elements' source child element where a single source element is selected by the user agent for play, the mapml-viewer element's child layer elements are visually combined with sibling layer elements and presented by the parent mapml-viewer element as a pan-able, zoom-able two-dimensional image. The display state (on / off) of the content represented by the layer element is controlled by the checked boolean attribute and corresponding property. If checked, the layer is drawn on the map in the sequence it is found in the parent element; if not checked the layer is not drawn but should remain visible in the mapml-viewer element's representation of controls in an "unchecked" state.

The src attribute value is the URL of a web resource encoded in Map Markup Language.

The hidden boolean attribute can be set to remove the layer from the map layer control, but it will remain displayed on the map. In order to remove the layer from the map display, it can have its checked property toggled, or be removed from the DOM.

The label attribute sets a fallback value for the accessible name [[accname-1.1]] of the layer as represented in the user agent's representation of map viewer controls. The fallback label value is used as the accessible name [[accname-1.1]] of the layer if the map document author has not supplied a non-empty title element value in the layer content. The label IDL attribute must reflect the label content attribute.

The disabled property is a read-only boolean indicator of the visibility of the layer on the map. If the layer is not visible due to errors, including projection, zoom or extent mismatch, the property will be true and if the layer is present in the layer control (i.e. hidden is false), it will be disabled in that control i.e. not checkable.

The location and zoom level of the map can be changed via the layer.zoomTo() API method.

A layer's features may be converted to a GeoJSON-encoded feature collection [[rfc7946]] with the mapml2geojson method. The method accepts parameters via the dictionary-valued options parameter. Options include a callback function, passed as the value of the propertyFunction option, which accepts a single properties element argument. The propertyFunction will be invoked once for each feature in the layer, and the value of the argument passed to it will be the properties element child of the currently-processing feature element. If no propertyFunction option is supplied, a default mapping of properties content to the GeoJSON "properties" member will be attempted, which may produce imperfect output, depending on the structure of the properties element that is passed. The default propertyFunction attempts to reverse an HTML table that would be generated by the geojson2mapml function. If the input properties element does not conform to that structure, incorrect output MAY result.

The transform option, allows the author to prevent or trigger the reverse projection transformation of the coordinates of feature geometries when converting to the GeoJSON [[rfc7946]] format.

coordinates element contents are encoded according to the coordinate system specified by the geometry element cs attribute, or the relevant document context fallback coordinate system.

If the input feature geometry element's coordinates elements are in a non-gcrs coordinate system, if the transform option value supplied is true (the default), the coordinates content will be transformed via a reverse projection transformation to longitude and latitude position arrays according to the GeoJSON format requirements. If the transform option value is false, coordinates values will be encoded as GeoJSON position arrays without transformation, regardless of their input coordinate system.

Note that because GeoJSON recommends that coordinates be encoded as WGS84 (CRS84), and because it is not possible to perform datum transformations in this specification, the output GeoJSON coordinates from mapml2geojson MAY NOT be WGS84-compliant, regardless of input projection or coordinate system.

Authoring

A Web map is a rectangular viewport on a page, established in HTML by the mapml-viewer element, with an optional accessible name for the rendered map, which is assigned by a child map-caption element.

A map's initial location is defined by the mapml-viewer lat and lon attributes. A map's initial display scale is approximately defined by the mapml-viewer's zoom attribute, while the spatial extent of a map is defined by its lat, lon and zoom attributes, and its rendered viewport size in defined in CSS pixels.

In addition to map-caption, a mapml-viewer also contains a set of zero or more layer elements. Map layers are drawn in document order of the layer elements, following the SVG painters model. If the author enables more than one layer, via the layers' checked attribute, all the checked layers will be rendered, in document order.

A mapml-viewer optionally displays a set of user controls, based on the viewer's controls and controlslist attributes. User controls may include a dialog for controlling the appearance and order of map layers. The appearance of each map layer in the layer control dialog includes the accessible name of the layer, which is set by the map author.

The set of map viewer controls is under control of the HTML author. The arrangement, appearance and accessibility of the controls is managed by the user agent. While it is possible to replace or augment the set of controls and their arrangement, it is not recommended to do so, since such changes will necessarily change the accessibility and usability of the map for users.

Local and remote content

Map layers are created and managed with the layer element. The layer element represents map content by one of two mechanisms. The first mechanism is as the child or descendant content of the layer element directly. This configuration of content is called local content throughout this specification. The second mechanism for representing map content is by URL reference; this content configuration is called remote content, and the content is referenced via the layer src attribute. layer element content may be local or remote, but a layer element MUST NOT have both local content and remote content; if a layer element has both local content and a src attribute (remote content), the local content will be ignored. In the element descriptions of this document, each contains a "Contexts in which this element can be used" section. The terms "local content" and "remote content" in that section is intended to describe the appropriate authoring context of the element according to the above definition of local and remote content. Local and remote content serve different use cases: local content can be interactive, and DOM-accessible, while remote content is rendered, but not interactive, nor accessible to JavaScript or CSS.

Examples

The example maps are polyfilled using the <mapml-viewer> custom element. [[Web-Map-Custom-Element]]

Local content

Remote content

Semantics, Structure and Styling of MapML Documents

Semantics

Coordinate Systems

In this document, all Coordinate Systems (CS) are 2D. A 2D CS has two axes, one horizontal (commonly related to west-east direction), and one vertical (commonly related to north-south direction; do not confuse it with "elevation"). This document defines the axis order of coordinate pairs serialized in MapML documents which the axis-specific values are not distinguished by markup, such as within the coordinates element. In documents conforming to this specification, we override any externally defined axis order. Coordinates are serialized as horizontal axis followed by vertical axis, separated by whitespace. Where applicable, coordinate pairs are separated by whitespace. The axis names of a coordinate system are identified by this document.

Coordinate Reference Systems

A Coordinate Reference System (CRS) is a Coordinate System that is referenced to locations on the Earth. Maps are graphics which follow mathematical rules (called projections) established to transform locations on Earth to locations on a plane (formerly paper, more recently a device screen). Projections are mathematical equations designed to conserve particular properties of the source location, and often have parameters that can be used to induce desired properties for particular locations.

To facilitate the sharing of CRS definitions, the International Association of Oil ans Gas Producers (IOGP) (formerly known as the European Petroleum Survey Group (EPSG)) mantains a list of CRS definitions and codes in their [[[EPSG-REGISTRY]]]. Some EPSG codes are used in the following table. In an effort to bring some clarity about the axis order for the longitude-latitude based CRSs, the OGC defined some "CRS codes". CRS:83 is defined equivalent to EPSG:4269 but with horizontal-then-vertical axis order, and CRS:84 is defined equivalent to EPSG:4326 except in its axes order. [[EPSG-REGISTRY]]

Tiled Coordinate Reference Systems

A Tiled Coordinate Reference System is a set of Coordinate Reference Systems, which share a common origin in space, but which differ by the size of their smallest unit at defined locations, e.g. meters/pixel along the equator.

This document defines the following coordinate reference system types:

Coordinate Reference System type codes and descriptions

Code Name Description
tcrs The root coordinate system(s) in a Tiled CRS A set of CRS that, for each of a member of a set of resolutions, associates pixel coordinates with an origin at the upper left corner of the pixel space with axis values increasing right (x, horizontal) and downwards (y, vertical). The pixel size in the associated PCRS units is a function of the associated resolution value.
gcrs Geodetic CRS A CRS that models the Earth as an ellipsoid or a sphere and expresses locations in longitude and latitude. The origin is at the intersection point of the prime meridian of Greenwich (longitude, horizontal axis) and the equator (latitude, vertical axis).
pcrs Projected CRS A CRS that transforms the GCRS space into a planar system using a projection method, and expresses locations in Easting (horizontal) and Northing (vertical) coordinates. The PCRS is generated on top of a GCRS and both together are commonly identified with a CRS code (EPSG codes being the most common codes).
tilematrix Tile matrix CRS In a TCRS, for each resolution, a tilematrix coordinate system groups underlying TCRS pixels into square tiles and counts tiles with the origin at the upper left corner of the tiled space and increasing right (column axis, horizontal) and downwards (row axis, vertical) respectively.
tile Tile CRS A CRS associated to each tile in a tilematrix, measured in pixels with the origin at the upper left corner of the tile and increasing right (i axis, horizontal) and downwards (j axis, vertical), respectively.
map Map CRS A CRS that is associated to the state of the map (the actual view port in the computer screen) measured in pixels, with the origin at the upper left corner of the map and increasing (i axis, horizontal) and downwards (j axis, vertical), respectively.

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 PCRS GCRS* Projection 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 / WGS 84 - Pseudo-Mercator CRS:84 Spherical Mercator -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 / NAD83 - Canada Atlas Lambert CRS:83 Lambert Conic Conformal (2SP) -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 / WGS 84 - EPSG Alaska Polar Stereographic CRS:84 Polar Stereographic (variant A) -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. CRS:84 CRS:84 Pseudo Plate carrée LatLng(90,-180) 256/256 LatLng(-90,-180), LatLng(90,180) 0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
0.703125000000000
0.351562500000000
0.175781250000000
8.78906250000000 10^-2
4.39453125000000 10^-2
2.19726562500000 10^-2
1.09863281250000 10^-2
5.49316406250000 10^-3
2.74658203125000 10^-3
1.37329101562500 10^-3
6.86645507812500 10^-4
3.43322753906250 10^-4
1.71661376953125 10^-4
8.58306884765625 10^-5
4.29153442382812 10^-5
2.14576721191406 10^-5
1.07288360595703 10^-5
5.36441802978516 10^-6

* 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 "horizontal axis followed by vertical axis" order. Where axes order is defined differently by external definition, this specification MUST be taken to be correct for MapML documents.

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 OSMTILE coordinate reference system has become a de facto interoperable standard for 'slippy' Web maps. 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 successive level of tiles contains 2 zoom 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

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 tiled coordinate reference system projected in the Equirectangular, or Plate carrée system.

The WGS84 tiled coordinate reference system is suitable for small to medium scale mapping of the entire world. It is also useful for vector data provided that the inter-vertex distance is no less than a single pixel in size at any particular zoom level.

It is believed that the definition of WGS84 according to this document makes it a suitable choice for non-georeferenced mapping applications, such as ultra high resolution graphics and technical drawings are one of the their use cases. The editor of this document requests specific implementations to contribute implementation experience in using this TCRS for technical and other drawings.

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.

Scale / Resolution / 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 and the resolution of maps in that projection vary as a function of location. The resolutions specified by this document are only valid in defined locations. For example, in WGS84 and OSMTILE the defined resolutions are valid only along the equator. "Zoom" levels are integer values corresponding to the index of the resolution value defined above, and represent numeric proxy for a scale, at the defined location(s). For example, the OSMTILE TCRS, being based internally on the Spherical Web Mercator projection (EPSG::3857), allows us to reasonably portray a large portion of the Earth's surface, requiring relatively simple and fast math to convert to and from spherical latitude/longitude coordinates. Additionally, it enables the simple tiling system known as OSMTILE in this specification, that has become a de facto standard. As such, it was deemed to have appropriate properties for a globally useful projection on the Web.

In MapML documents, scale is indirectly represented by zoom level, and varies across any rendered map extent. Two MapML documents in the same TCRS and zoom level should be interoperable to the degree that they can be automatically and visually related (overlayed). The zoom level of a MapML document is often represented by the value of the value attribute of the input[@type=zoom]. By associating a specific zoom value to the input, we are able to compute the spatial bounds of a link template by means of min, max and axis values of other input[@type=location] elements associated to the same link template element with which the input[@type=zoom] is associated. In any case, the zoom level of any MapML document MAY 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.

Extents

A MapML document is a representation of a defined portion of a two dimensional map area. In MapML, this is called an 'extent' (represented by the extent element), the extremes of which can be described in terms of locations coordinates specified in the TCRS (pcrs, gcrs, tilematrix, etc.). The extent/@units value SHALL be taken to be the authoritative declaration of the TCRS for a MapML document.

Fragment identifiers

TBD

Structure

The Document object

A MapML document is an XML document, with all elements assigned to the HTML namespace. As such, a MapML document MUST have a single root element named mapml , generally having a single attribute named "xmlns" with a value which MUST be equal to "http://www.w3.org/1999/xhtml". Assigning elements to namespaces using namepace prefixes is NOT recommended. At this time, there is only an XML syntax variety of MapML document, and documents conforming to this specification MUST NOT have a DOCTYPE declaration.

The <mapml> element
Categories:
None.
Contexts in which this element can be used:
The root of a remote content-MapML document.
Content model:
One head element, followed by one body element.
Content attributes:
Global attributes.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLMapmlElement : HTMLElement {
              [HTMLConstructor] constructor();
            };
            

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]].

The <head> element
Categories:
None.
Contexts in which this element can be used:
In remote content, 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:
Global attributes.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLHeadElement : HTMLElement {
              [HTMLConstructor] constructor();
            };
            

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.

The <title> element
Categories:
Metadata content.
Contexts in which this element can be used:
In remote content, as a child of the head element.
In local content, as a child of the layer element.
Content model:
Text that is not inter-element whitespace.
Content attributes:
Global attributes.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLTitleElement : HTMLElement {
              [HTMLConstructor] constructor();
            };
          

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.

The <base> element
Categories:
Metadata content.
Contexts in which this element can be used:
In remote content, as a child element of the head element.
In local content, as a child of the layer element.
Content model:
Nothing.
Content attributes:
href — The absolute URL to be used to resolve relative URLs in the document.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLBaseElement : HTMLElement {
              [HTMLConstructor] constructor();
            };
            

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.

The <meta> element
Categories:
Metadata content.
Contexts in which this element can be used:
In remote content, as a child element of the head or extent elements.
In local content, as a child of the layer or extent elements.
Content model:
Nothing.
Content attributes:
name — Metadata name.
http-equiv — Pragma directive.
content — Value of the element.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLMetaElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              attribute DOMString name;
              attribute DOMString httpEquiv;
              attribute DOMString content;
            };
            
The <link> element
Categories:
Metadata content.
Contexts in which this element can be used:
If the element represents a hyperlink (has a href attribute): In local content, as a child of the layer element; in remote content, as a child of the head or body element.
If the element represents a link template (has a tref attribute): As a child of the extent element.
Content model:
Nothing.
Content attributes:
href — Address of the hyperlink.
tref — URL Template.
rel — Relationship between the document containing the element and the destination resource.
projection — 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.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLLinkElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              attribute DOMString href;
              attribute DOMString tref;
              attribute DOMString rel;
              attribute DOMString projection;
              attribute DOMString hreflang;
              attribute DOMString type;
              attribute DOMString title;
            };
          

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 projection 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 projection 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 mapml-viewer 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.

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
The <body> element
Categories:
Sectioning root.
Contexts in which this element can be used:
In remote content, as the second child of the mapml element.
Content model:
Features and metadata.
Content attributes:
Global attributes.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
role=document

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLBodyElement : HTMLElement {
              [HTMLConstructor] constructor();
            };
            

The body element represents the content of the document.

The <extent> element
Categories:
Metadata content.
Contexts in which this element can be used:
In remote content, as a child of the body element.
In local content, as a child of the layer element.
Content model:
A set of multiple input and one or more link elements with their rel attribute in either the "tile", "image" or "features" state, and zero or one link element with its rel attribute in the "query" state. Optional metadata content describing server-side extent content, in the form of zero or more meta elements with name attribute in the zoom or extent state.
Content attributes:
units — The name of the coordinate reference system whose measurement units are to be used by values supplied by child input elements.
label — A text label to be applied to the user interface for the extent in the layer control. If no label content attribute is supplied, a default internationalized string value will be generated and rendered for non-hidden extents.
opacity — An initial opacity value, that will be applied to the content retrieved by the extent, and which is reflected to the exposed layer control user interface for opacity. Opacity values have a decimal range from 0 (transparent) to 1.0 (opaque).
checked — A boolean attribute that sets the state of the exposed user interface in the layer control. If the attribute is present, the extent content is rendered on the map; if the checked attribute is not present, the extent may be represented in the layer control, but its content will not be rendered.
hidden — Visibility status of the extent in the layer control. Does not affect visibility of the extent on the map.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLExtentElement : HTMLElement {
              [HTMLConstructor] constructor();
              
                     attribute DOMString units;
                     attribute DOMString label;
                     attribute boolean checked;
            readonly attribute boolean disabled;
                     attribute boolean hidden;
                     attribute double opacity;            };
            

The extent element is a map-associated affordance, which contains input and link elements, whose job it is to serialize location event properties that can be submitted to a server for processing. Returned content is rendered on the map in the DOM sequence order of the extent child element among its siblings in the parent element. The extent's content rendered transparency is controlled by the opacity attribute.

The units attribute indicates the parent TCRS that location events shall be generated for, and serialized as requested by the extent's contents.

The label IDL attribute reflects the content attribute, if present. If no content attribute is present, the IDL attribute returns an internationalized string for 'Sub-layer'.

The display state (on / off) of the content represented by the extent element is controlled by the checked boolean attribute. If checked is true, the extent is rendered on the map; if not checked the extent is not rendered but should remain visible in the mapml-viewer element's representation of controls, in an un-checked state.

The hidden boolean attribute can be set to remove the extent from the map layer control, but it will remain displayed on the map. In order to remove the extent content from the map, it can have its checked property toggled, or the element can be removed from the DOM.

The disabled IDL attribute is a read-only boolean representation of the visibility of the extent contents on the map. If the extent is not visible due to errors, including projection, zoom or bounds mismatch, the disabled IDL attribute will return true. If the extent is present in the layer control (i.e. hidden is false), its checked state will be disabled until the error condition is corrected, for example by zooming to the extent's bounds.

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:
Nothing.
Content attributes:
typeEnumerated 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.
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.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
input with type:
  • zoom
  • location
  • width
  • height
  • hidden
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLInputElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              attribute DOMString type;
              attribute DOMString name;
              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.

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

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 OGC equivalent
tcrs For each zoom level, locations are expressed in pixel coordinates with the origin at the top-left corner of the pixel space. OGC Tile Matrix Set "tile matrix (i',j')".
pcrs The location is expressed in projected coordinates. Units are meters except for WGS84 where pcrs AND gcrs coordinates are in longitude-latitude. E.g. meters for OSMTILE, which has an associated projected coordinate reference system of EPSG:3857. Commonly represented as (x,y)
gcrs The location is expressed in the geodetic coordinate system associated to the TCRS, e.g. decimal degrees for the OSMTILE TCRS. Commonly represented as (long,lat)
mapml-viewer The map coordinate system is defined by the state of the map system. At each pan and / or zoom, the map coordinate origin is reset within the Location is expressed in pixel coordinates with the origin starting at the upper left corner of the extent increasing right and downwards, respectively. WMS GetFeatureInfo (i,j)
tilematrix For each zoom level, locations are expressed in tile row and column index (0-based) values, with the origin at the top-left corner of the tiled space, with column index values increasing right and row index values increasing downwards. WMTS GetTile (TileCol, TileRow).
tile For each tile within every zoom level, a location is expressed in pixel coordinates with the origin at the upper left corner of the tile increasing right and downwards, respectively and ending at 256. The combination of tilematrix and tile coordinates yields a location reference with pixel-sized precision. WMTS GetFeatureInfo (i,j)

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 or tile CS i axis (parallel to x axis of TCRS).
j Map or tile 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).
The <select> element
Categories:
N/A.
Contexts in which this element can be used:
As a child of the extent element.
Content model:
One or more option elements.
Content attributes:
id — Identifies the select within the current document.
name — The token to be used as a variable name in form serialization.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLSelectElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              attribute DOMString id;
              attribute DOMString name;
            };
            
The <option> element
Categories:
N/A.
Contexts in which this element can be used:
As a child of the select 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.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLOptionElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              attribute DOMString value;
              attribute DOMString label;
            };
            
The <tile> element
Categories:
Feature data.
Contexts in which this element can be used:
In remote content, as a child of the body element.
In local content, as a child of the layer element.
Content model:
Nothing.
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.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLTileElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              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.

The <feature> element
Categories:
Feature data.
Interactive content.
Contexts in which this element can be used:
In remote content, as a child of the body element.
In local content, as a child of the layer element.
Content model:
Optional featurecaption element, optional geometry element, optional properties element.
Content attributes:
Global attributes.
zoom — the 'native' zoom level of the feature geometry.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
role=feature

No role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLFeatureElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              attribute DOMString zoom;
            };
            

A feature element represents a map feature.

The <featurecaption> element
Categories:
Feature data.
Contexts in which this element can be used:
As a child of a feature element containing no other featurecaption elements.
Content model:
Text that is not inter-element whitespace.
Content attributes:
Global attributes.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLFeaturecaptionElement : HTMLElement {
              [HTMLConstructor] constructor();
              
            };
            

The featurecaption element represents a caption for the contents of the featurecaption element's parent feature element.

The <properties> element
Categories:
Feature data.
Contexts in which this element can be used:
A child of the feature element.
Content model:
Palpable content
Content attributes:
N/A.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLPropertiesElement : HTMLElement {
              [HTMLConstructor] constructor();
            };
            
The <geometry> element
Categories:
Feature data.
Contexts in which this element can be used:
Child of the feature element.
Content model:
A single geometry child element, described in the table below.
Content attributes:
Global attributes.
cs — The coordinate system, used to interpret coordinates defining the content of the child geometry value.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLGeometryElement : HTMLElement {
              [HTMLConstructor] constructor();
              
              attribute DOMString cs;
            };
            
Geometry Child Elements
Categories:
Feature data.
Contexts in which this element can be used:
Child of the geometry element.
Content model:
Described in the table below.
Content attributes:
Global attributes.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLGeometryChildElement : HTMLElement {
              [HTMLConstructor] constructor();
              
            };
            

A geometry element has one child element, which can be a point, linestring, polygon, multipoint, multilinestring, multipolygon, or geometrycollection.

geometry child element name Content model Non-schema constraints
point A coordinates element containing a single position. Axis order - x followed by y, separated by whitespace.
linestring A coordinates element containing two or more positions. Axis order - x followed by y, separated by whitespace.
polygon One or more coordinates elements, each containing three or more positions.

Axis order - x followed by y, separated by whitespace.

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 One coordinates element, containing one or more positions. Axis order - x followed by y, separated by whitespace.
multilinestring One or more coordinates elements, each containing two or more positions. Axis order - x followed by y, separated by whitespace.
multipolygon One or more polygon elements.

Axis order - x followed by y, separated by whitespace.

For each member polygon, the same non-schema constraints apply to multipolygon 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.
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 followed by y, separated by whitespace, with each position separated from the adjacent position by whitespace.
Content attributes:
N/A.
Accessibility considerations:
For authors
Implicit ARIA semantics ARIA roles, states and properties which MAY be used
No corresponding role

No role or aria-* attributes.

For implementers
DOM interface:
            [Exposed=Window]
            interface HTMLCoordinatesElement : HTMLElement {
              [HTMLConstructor] constructor();
            };
            

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.

Styling

MapML documents can be styled with Cascading Style Sheets.

Privacy & Security Considerations

This technology relies on web resources loaded over the internet, which carries security implications. The architecture is not unlike allowing embedded images encoded in SVG format, and it is thought that similar security considerations apply. The author would be grateful if commenters could highlight such implications, so that they could be explicitly made part or the considerations of this draft.

[[CSP]] [[[CSP]]]
[[secure-contexts]] [[[secure-contexts]]]

IANA Considerations

The following registrations are for community review and will be submitted to the IESG for review, approval, and registration with IANA.

Media Type Registration

This section contains the required text for MIME media type registration with IANA.

The Map Markup Language MIME type is text/mapml.

If the protocol over which the MapML document is transferred supports the [[MIME-TYPES]] specification (e.g. HTTP), it is RECOMMENDED that the MapML document be labeled with the Map Markup Language MIME type.

Type name:
text
Subtype name:
mapml
Required parameters:
N/A
Optional parameters:
charset
The charset parameter may be provided to definitively specify the document's character encoding, overriding any character encoding declarations in the document. The parameter's value must be one of the labels of the character encoding used to serialize the file.
Encoding considerations:
Same as for text/html
Privacy and security considerations:
See Privacy & Security Considerations
Applications that use this MIME type:
Web browsers
Additional information:
Magic number(s):
N/A
File extension(s):
.mapml
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
The Maps for HTML Community Group can be contacted at public-maps4html@w3.org.
Intended usage:
COMMON
Restrictions on usage:
None
Author:
W3C's Maps for HTML Community Group
Change controller:
W3C

Conforming documents

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.

Schema

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

RelaxNG Schema

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

Further map document validation can be done with Schematron. Please see the MapML schema directory for further information. [[MAPML-SCHEMA]]

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 tools to the URL of the schema (or your local cached copy, as you prefer).

MapML schema (under development).

Contributors

Thanks to all our contributors: Robert Linder, Joan Masó and elf Pavlik