Skip to content

Commit

Permalink
WIP Simplify explainer. Add inine-remote-map-content image. Get rid of
Browse files Browse the repository at this point in the history 
high-level-api.md, use web-map-doc in preference.
  • Loading branch information
@prushforth
prushforth committed Jun 14, 2024
1 parent 60e0e15 commit 09b9e9b
Show file tree
Hide file tree
Showing 3 changed files with 133 additions and 316 deletions.
221 changes: 133 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,126 +1,172 @@
<h1>The MapML (Map Markup Language) explainer</h1>

Specification: https://maps4html.org/MapML/spec/
Draft spec: https://maps4html.org/MapML/spec/

<h2>Author</h2>
<h2>Author(s)</h2>

Peter Rushforth
Peter Rushforth, Natural Resources Canada
Aliyan Haq, Natural Resources Canada

<h2>Participate</h2>

The W3C [Maps for HTML Community Group](https://www.w3.org/community/maps4html/)
is iterating on the problem space.
You can contribute to the on-going discussion and documentation of
[Use Cases and Requirements for Standardizing Web Maps](https://maps4html.org/HTML-Map-Element-UseCases-Requirements/).
Alternatively, if your organization is a member of the
[Web Platform Incubator Community Group](https://www.w3.org/community/WICG/) (WICG)
and you are able to contribute there but not elsewhere,
please consider contributing through the [WICG forum on Web mapping](https://discourse.wicg.io/c/web-mapping/22).
We would love to hear from you.

[Issue tracker for this explainer](https://github.com/Maps4HTML/MapML-Proposal/issues)

<h2 id="introduction">Introduction</h2>

Web maps are a well-established class of Web application, and there exist popular,
mature open- and closed-source JavaScript frameworks to create and manage Web maps.
Web maps, considered from the perspective of the Extensible Web Manifesto, represent
a “high-level API”. The many low-level browser APIs already used by the popular
JavaScript mapping frameworks demonstrate that Web maps may be a good fit for
inclusion into the Web platform standards at this time.
We propose to extend the Web platform with HTML primitives that implement map and
location semantics. We call the proposed HTML extension "MapML".

MapML is the declarative API that results from our community’s effort to abstract
and polyfill Web mapping requirements as custom elements, using one of the mature
open source Web mapping frameworks so as to not have to start “from scratch”.
The process of polyfilling Web maps as MapML has also identified missing low-level
platform APIs that will be essential to complete the implementation of Web maps
as a standard platform feature.
The core idea is to easily enable web developers to create map viewports on a web
page that are georeferenced, and into which HTML map content may be added in
declarative fashion, and manipulated or accessed using the DOM.

The map viewport is a rectangular window in a web page in which "real-world"
coordinate reference systems are used, and viewport-to-real-world scales may be
used for positioning and styling of HTML map content. The geometric or mathematical
relationship between the viewport and the "real world" is provided and managed by
the browser, especially by the browser rendering engine.

MapML Polyfill

We have developed a polyfill for MapML, using custom elements,
in which we've tried to follow platform advice. The user documentation for the
polyfill is [available online here](https://maps4html.org/web-map-doc/).

In some cases, existing HTML elements have a required common function, so we have
proposed to extend those elements with new attributes, properties, events and
behavior.

In other cases, there is a need for an entirely new element or element group,
e.g. <map-extent>

The polyfill is implemented especially using autonomous custom elements.
Many of our polyfill's custom elements use the 'map-' namespace prefix. In all
cases where we propose to extend a current native HTML element, we have created
an autonomous custom element named 'map-'whatever e.g. <map-link> We were forced
to do this because of the lack of interoperability of customized built-in elements.

<h2>Contents</h2>

- [The Problem](#the-problem)
- [Introduction](#introduction)
- [Motivation](#motivation)
- [The Proposal](#the-proposal)
- [Goals](#goals)
- [Use Cases and Requirements](#use-cases-and-requirements)
- [Key Scenarios](#key-scenarios)
- [Detailed design discussion](#detailed-design-discussion)
- [Considered Alternative Designs of MapML](#considered-alternative-designs-of-mapml)
- [Stakeholder Feedback / Opposition](#stakeholder-feedback--opposition)
- [Stakeholder Feedback](#stakeholder-feedback)
- [References and Acknowledgements](#references-and-acknowledgements)

<h2 id="the-problem">The Problem</h2>

Web maps are <span style="text-decoration:underline;">not interoperable</span>.
For example, users cannot “mash up” a Leaflet map and an OpenLayers map, two of
the most popular open source Web mapping frameworks, even if they show the same
exact data source in the exact same location. (The situation is even more
non-interoperable between open map data and privately managed map databases,
where the sole client may be that provided by the owner of the map data. The
lack of legal interoperability of map data is outside the scope of standardization.)

The lack of Web map interoperability affects developers. The skill set and
vocabulary required to create a robust map is different from one mapping framework
to the next. They can be complex to <span style="text-decoration:underline;">create</span>,
with visual styling of map information being a discipline that is generally
outside the realm of Web technology, and different from one mapping framework to
the next.

Web maps are [typically not accessible](https://github.com/Malvoz/web-maps-wcag-evaluation/blob/master/README.md).
The knowledge required to <span style="text-decoration:underline;">use</span> Web
<h2 id="motivation">Motivation</h2>

Web maps are a widespread and important, not to say essential, feature of the modern
web. Maps occur on 16% of web pages, and 22% of web maps contain interactive
representations of places (aka "features"). The number of maps on web pages exceeds
that of other media types, including \<video> and YouTube embeds [1](#references-and-acknowledgements).

Web maps are <span style="text-decoration:underline;">not interoperable</span>.
Maps from one provider cannot be readily combined with maps from another provider,
and even when such mashups are technically feasible due to adherence of the provider
to server interoperability standards, such as the widely implemented OGC web
service standards, barriers on the client will often prevent information re-use.

In many cases, client barriers exist because the map information is represented
as (JavaScript) code, providing a noteworthy exemplar of the rationale behind the Rule
of Least Power [2](#references-and-acknowledgements). For example, users cannot
“mash up” a Leaflet map and an OpenLayers map, two of the most popular open source
Web mapping frameworks, even if they show the exact same data source in the exact
same location.

The situation becomes even less interoperable between open map data and privately
managed map databases, where the sole client (also in JavaScript) may be that provided
by the owner of the map data. Although the lack of legal interoperability of map
data is outside the scope of standardization, it should be technically feasible
to create a client Web map interoperability standard that lowers or eliminates
the technical barriers for map developers who wish to have and to provide choices to
their users based on standards. If a web standard for maps existed, it might reduce
the financial incentives to create proprietary barriers to map re-use in the same
way that publishing textual information on the Web has reduced the incentive to
create proprietary document management and publishing technology.

The representation of maps-as-code also leads to a problem of resource discovery.
The location of information is often relevant for search results, demonstrated by
the fact that many web search engines expose (virtual) map tab in which to visualize
search results on a map. If the location of web page information was organically
exposed as declarative standard markup (and not as code), it would (in principle)
be possible for any web crawler to create location-enabled full text indexes of
the web, which might reasonably be useful for search relevance ranking and improved,
or at least, more open resource discovery.

The lack of Web map interoperability also affects web developers. The skill set
required to create a robust map is different from one mapping framework to the
next, especially with regard to feature styling. Maps can be complex to
<span style="text-decoration:underline;">create</span>, with visual styling of map
information being a discipline that today is generally outside the scope of Web
technology (CSS can't be applied), and is different from one mapping framework
to the next. Ideally, it would be possible for developers to apply their existing
knowledge of CSS, HTML and SVG to maps and location information problems.

Web maps are [often inaccessible](https://github.com/Malvoz/web-maps-wcag-evaluation/blob/master/README.md).
For users, the skills required to <span style="text-decoration:underline;">use</span> Web
maps is different for each framework, with resulting accessibility challenges
arising from inconsistencies in user experience across frameworks.

Location information is <span style="text-decoration:underline;">not searchable</span>,
except through specialized portals. Web maps are not crawlable; even if the JavaScript
that creates a Web map is executed by a crawler, the resulting DOM requires a
sighted user to interpret it, because it only has visual semantics. The DOM created
also varies from framework to framework. As a result, users cannot search for
location information, embedded as it is in program code, except in specialized
mapping portals. Location search may be even more important for non-visual users
especially in a mobile context, but it is impossible because of today’s Web mapping
frameworks.
arising from inconsistencies in user experience across frameworks. Users have
no standardized ability to express accessibility preferences that relate to
map content or controls.

<h2 id="the-proposal">The Proposal</h2>

The proposal is to create accessible, searchable and usable Web maps, by integrating
mapping elements into HTML supported by the CSS and DOM standards.
Please review the [user documentation](https://maps4html.org/web-map-doc/docs/)
for the polyfill declarative syntax and semantics, with examples.

This extension to HTML would create a `&lt;map>/&lt;mapmlviewer>*` viewer widget
that contains default controls in a user agent shadow root, (similar to `&lt;video>`
today), with child `&lt;layer>` elements which are light DOM, which may either
refer to remote map source or contain map-related markup (the vocabulary of which
is also part of this proposal):
This extension to HTML would create a map viewer widget similar to `&lt;video>`,
with child `&lt;layer->` elements in light DOM. Layers either
refer to remote map data source or contain map-related markup inline / in the
element's content:

```html
<mapmlviewer zoom="11" lat="48.8566" lon="2.3522" controls controlslist="nolayer noreload" projection="OSMTILE">
<layer src="https://example.com/mapml/osm/" checked crossorigin></layer>
<!-- more layers as required -->
</mapmlviewer>
<mapml-viewer zoom="11" lat="48.8566" lon="2.3522" controls controlslist="noreload geolocation" projection="OSMTILE">
<!-- remote content layer -->
<!-- xhtml syntax and namespace only (currently) for remote content, root element='mapml-' (no doctype yet) -->
<layer- src="https://example.com/mapml/openstreetmap/tiles" checked hidden crossorigin></layer->
<!-- local content layer / content 'inline' -->
<layer- checked label="Places of Interest">
<!-- html or xhtml syntax for inline content -->
<map-extent projection="OSMTILE" checked hidden>
<map-input type=zoom min=0 max=18>
<map-input type=location name=xmin position=top-left min=... max=... axis=easting></map-input>
<map-input type=location name=ymax position=top-left min=... max=... axis=northing></map-input>
<map-input type=location name=xmax position=bottom-right min=... max=... axis=easting></map-input>
<map-input type=location name=ymin position=bottom-right min=... max=... axis=northing></map-input>
<map-input type=width name=w min=1 max=4096></map-input>
<map-input type=height name=h min=1 max=4096></map-input>
<map-link rel=features media=... tref=/geoserver/wms/?request=GetMap&bbox={xmin},{ymin},{xmax},{ymax}&width={w}&height={h}&format=text/mapml&format_options=mapmlfeatures:true...></map-link>
</map-extent>
</layer->
<!-- more / different layers as required, add or remove via DOM node interface -->
</mapml-viewer>
```

Please review the [user documentation](https://maps4html.org/web-map-doc/docs/)
for the proposed declarative syntax and semantics, with examples.

\* The name of the eventual root map widget element will be determined in consultation
with browser teams. “&lt;map>” is used by an existing element, and it may be
impossible or undesirable to overload the behavior of that element.

<h3 id="goals">Goals</h3>

* Allow authors to create dynamic, usable and accessible Web maps about as easily
as they can embed an image, a video or a podcast today, using markup, especially links.
* Allow authors to create mapping mashups using markup. Use of markup doesn’t
* Allow authors to create accessible mapping mashups using markup. Use of markup doesn’t
necessarily require scripting development skills, or detailed map server technology
knowledge i.e. a mashup can be accomplished about as easily as linking to images
or videos..
* Embed semantics of map feature and location information into HTML and browsers
* Define semantics of map feature and location information in HTML and browsers
for use by screen readers and other assistive technologies.
* Simplify the use of public or private [spatial data infrastructures](https://en.wikipedia.org/wiki/Spatial_data_infrastructure)
(SDI), such as [OpenStreetMap](https://wiki.openstreetmap.org/wiki/Main_Page)
and national and international SDIs, by designing the integration of those services
into the proposed Web platform mapping standards.
* Leverage existing spatial (map) content management systems, APIs and Web Services,
so that map content is immediately available.
so that map content is immediately available when this proposal is implemented.

<h3 id="use-cases-and-requirements">Use Cases and Requirements</h3>

Expand All @@ -129,25 +175,20 @@ and our polyfill for review by the W3C community.

<h3 id="key-scenarios">Key Scenarios</h3>

See the Use Cases document for a comprehensive list of scenarios. A few of the more important scenarios include:
See the Use Cases document for a comprehensive list of scenarios. A few of the
more important scenarios include:

* Simple, accessible, user-controllable mashups
* Allow layers to be turned on/off by user
* Allow layers to be turned on/off by keyboard / mouse user
* Accessible location information, styled using CSS
* Accessible pan and zoom
* Show the user’s location on a map
* Accessible / meaningful pan and zoom
* Allow user to register map content preferences via user agent settings
* Show the user’s location on a map, and / or use map bounds for responsive content display
* Web search for location information
* Accessible display of routes between locations
* Leverage existing geospatial content
* APIs to support more performant, complex mapping applications

<h3 id="detailed-design-discussion">Detailed design discussion</h3>

_See the [High-Level API explainer](https://github.com/Maps4HTML/MapML-Proposal/blob/main/high-level-api.md) for design details on proposed elements._

_See the polyfill [user documentation](https://maps4html.org/web-map-doc/docs/elements/mapml-viewer/)._


<h2 id="considered-alternative-designs-of-mapml">Considered alternative designs of MapML</h2>

Elements of MapML could be improved through discussion and further research,
Expand All @@ -166,7 +207,7 @@ understanding of not only Web architecture, technology and standards, but also W
accessibility. To succeed, this project requires a narrow collaboration between
these stakeholder groups.

<h2 id="stakeholder-feedback-opposition">Stakeholder Feedback / Opposition</h2>
<h2 id="stakeholder-feedback">Stakeholder Feedback</h2>

Natural Resources Canada hosted the 2020
[W3C/OGC Joint Workshop Series on Maps for the Web](https://www.w3.org/2020/maps/)
Expand All @@ -181,7 +222,7 @@ In 2022, [Bocoup](https://www.w3.org/community/maps4html/participants?search=boc
conducted HTTP Archive and Web developer research on the subject of Web platform maps,
which revealed that there is strong support among developers for simple, accessible
Web platform maps. Their research also revealed that maps exist on about **16%**
of the pages included in the HTTP Archive.
of the pages included in the HTTP Archive [1].

Bocoup also received the feedback from browser developers that support from map
framework developers would be important in any browser team’s decision to implement
Expand All @@ -191,10 +232,14 @@ evaluate the proposal.

<h2 id="references-and-acknowledgements">References and Acknowledgements</h2>

[1] [Web Maps Research Summary](https://docs.google.com/document/d/e/2PACX-1vRXTxEOqP6xmdgPEmqir8r-kDvwVfA8oTC4vvv_XhoRk9mClLtzMx0BdoMaPIctwftkWI3U7yTS3Bkq/pub)
[2] [The Rule of Least Power](https://www.w3.org/2001/tag/doc/leastPower.html)


Contributions, advice and support from the following people are gratefully acknowledged:

Robert Linder, Simon Pieters, Anssi Kostiainen, Amelia Bellamy-Royds, Doug Schepers,
Brian Kardell, Boaz Sender, Ahmad Ayubi, Anshpreet Sandhu, Ben Lu, Aliyan Haq,
Michael<sup>tm</sup> Smith, Benoît Chagnon, Joan Masó, Keith Pomakis, Gil Heo,
Jérôme St-Louis, Nic Chan, Nick Fitzsimmons, Tom Kralidis, Daniel Morissette,
Chris Hodgson, Bennett Feely
Chris Hodgson, Bennett Feely, the GeoServer project
Loading

0 comments on commit 09b9e9b

Please sign in to comment.