maps4html / mapml-proposal Goto Github PK

<feature> modeled on GeoJSON “feature” objects, including geometry property, fit for use as anchors, CSS selector targets.

This is to partly address one of the concerns with this explainer in #17:

and we will enable standardized Web map accessibility through addition of maps to HTML.

How will accessibility be addressed?

Most map libraries today largely or entirely neglect screen reader users and keyboard users.

Accessible map navigation is an area that needs more user research (some can be found in Maps4HTML/chat#13). There has to be a plan to make pan & zoom and feature navigation (map content navigation as a whole) intuitive and accessible. This should probably have a section under Key Scenarios.

In Maps4HTML/Web-Map-Custom-Element#396 we're exploring how to make map content navigation accessible in the polyfill <mapml-viewer>, which may inform a standard interaction model for maps.

(The CSSWG proposal for standardizing pan & zoom is relevant, we should reference it.)

In https://github.com/Maps4HTML/MapML-Proposal#use-cases-and-requirements:

Use Cases and Requirements

This proposal is being evaluated [...]

The link destination for "evaluated" is out of date since these issues were transferred and should now exist or be raised here: https://github.com/Maps4HTML/UCR-MapML-Matrix/issues.

We should either remove this link or update it to point to the correct repo (in which case we need to create a new label in UCR-MapML-Matrix, e.g. requirements evaluation, and add it to that one existing issue).

Any change should be reflect on the same link in https://maps4html.org/MapML/spec/#use-cases-and-requirements.

The map-element.png (currently used in high-level-api.md#the-map-element) uses the term closed shadow root, it should say user agent shadow root.

Replacement image: https://user-images.githubusercontent.com/26493779/122376594-934e6600-cf64-11eb-8d20-870e38b59d76.png

This issue will be the parent of issues which are identified as "high-level features" of the Web, which are or could be implemented and added to this proposal. This will serve as an inventory of features we are asking to be developed and standardized in the Web platform.

Many areas of HTML prohibit nesting interactive content, for example the content model of the <a> element is:

Transparent, but there must be no interactive content descendant, a element descendant, or descendant with the tabindex attribute specified.

It's common to have content within maps overlapping. This is probably impossible to avoid with multiple layer sources, and even a single layer source can produce nested interactive elements (<map-a>).

I think it's important that this proposal talks about this. Supposedly in Key Scenarios.

Nested/overlapping interactive content is problematic for users with a pointing device or touch-enabled devices. One way to solve interacting with nested and/or overlapping content is a Feature Index.

@zcorpan:

If getting maps a first-class feature in the web platform is a goal, the process is imperative to its success.

This issue is created for discussion of the process per Simon's comments regarding importance of the process to achieve the goals of the community.

I've reviewed the explainer yesterday and today. I haven't yet reviewed other MapML material, so take this as my raw first reaction to reading this explainer.

At a high level, this explainer doesn't help me understand the problem very well. I see a series of claims that I don't understand how they follow from one to the other. Different concerns are not separated; the proposal is mixed with the problem statement.

I have concerns about the extensions of existing HTML elements being risky for web compatibility.

Accessibility, security and privacy are mentioned in passing but not really addressed.

I think the explainer should be rewritten to more clearly explain the high-level problems (based on the Use Cases and Requirements doc), explain the proposal (for a web developer audience; no need to cover all aspects of the proposal), alternatives, how those proposals address those problems.

The explainer is also too long; too much detail of the proposal.

More details inline:

(Note: I found the bold formatting makes this harder for me to read. I've removed bolding here.)

(Edit by @Malvoz: Bold formatting removed in f886640.)

Introduction

Web maps are a well-established domain of Web design, and there exist popular, mature open and closed source JavaScript libraries to create and manage Web maps. JavaScript web maps are often containers for publicly available and funded open geospatial and statistical data. Yet despite established JavaScript libraries and server-side API standards, Web maps remain a complex Web niche that is difficult to learn, due to their extensive prerequisite knowledge requirements. As a result, there exists a community of Web map developers which contributes very little to the Web platform and which may possess little understanding that the Web exists as a distinct and standards-based platform. Similarly, the Web platform seems mostly oblivious to Web maps and their requirements, and provides no direct support for maps. In other words, Web maps existence in the Web platform depends on intermediaries which “abstract away” the Web platform.

The goal of this proposal is to bridge the gap between the two communities in a way that may have positive benefits for both sides.

I can follow perfectly this far. 🙂

On the one hand, the Web mapping community is burdened by intermediaries and the consequent barriers to widespread creation and use of maps and public map information.

It would be good to provide evidence of this (not necessarily in the introduction).

On the other hand, the Web platform, especially the mobile Web, needs more and better high-level features and less JavaScript.

Why does the web platform, especially the mobile web, need that?

Simple yet extensible Web maps in HTML, that equally leverage the other platform standards, is the feature that both communities need to come together to improve usability and accessibility for users.

The Problem

Web maps today are created using a wide range of technology stacks on both the client and server, some standard, some open, and some proprietary.

Obligatory XKCD: https://xkcd.com/927/

The complexity of choices and the wide variety of technologies required to create Web maps results in maps of highly variable usability and accessibility.

I don't really follow this. Usability and accessibility are used but without substance.

(Edit by @Malvoz: Adressed by linking to the Web map tools WCAG 2.1 evaluation, in edf64d6.)

This has in turn led to the creation of centralized mapping services, that may or may not be implemented using Web technology;

Any citation for this cause and effect claim?

in some cases, mapping services which work well on desktop Web browsers mostly bypass the mobile Web through creation of mobile platform mapping apps, where the ‘rules of the Web platform’ (such as device permissions) do not apply.

How is this a problem?

Is the device permissions model for native mobile apps here still accurate?

Some centralized mapping services, both on the Web but especially on mobile technology platforms, are constructed for the purpose of tracking the user’s location and their locations of (search) interest, and using that private location information to market and re-sell highly targeted advertising.

Is the tracking and ads problem solved by this proposal?

Is the existance of centralized mapping services a problem?

So, What Is The Problem to Solve?

How is this section different from the previous one? (Should this be "The Proposal"?)

(Edit by @Malvoz: Changed the section heading to "The Proposal" in 9183add.)

The problem to be solved, therefore, is to reduce the threshold complexity of creating accessible and usable Web maps, and to enable full use of Web platform standards such as HTML, URL, SVG, CSS and JavaScript in map creation, styling, presentation and interaction.

The claim is to reduce complexity. But the proposal has considerable complexity. It's not clear that the existing stuff will go away once this exists. So it's not reassuring that complexity will be reduced for anyone.

To solve the problem, our approach is to identify the Web map processing that is currently performed by JavaScript libraries which should instead be defined as elements and attributes supported by CSS, while at the same time, we identify the Web map processing that should remain in the JavaScript domain as a standardized DOM API. By building the core behaviour of maps and layers into HTML, Web authors who want to build simple maps into their pages can easily do so, supported by core platform technologies, with the power of JavaScript available to enhance the core map and layer behaviour.

This is briefly discussing the method and also a solution.

By lowering the barriers for Web map authors in this way, we will improve the usability,

How? Usability for whom?

and standardize the accessibility of Web maps.

How?

Through making map creation a matter of applying appropriately crafted Web platform standards, we will create the conditions to multiply the choices of mapping services offered to authors and users of the Web.

How?

In improving the choices among mapping services available through the Web platform, we will enable the growth of services that offer alternate means of paying for maps other than in exchange for the user’s personal private information,

What do tracking-free mapping services need?

and we will enable standardized Web map accessibility through addition of maps to HTML.

How will accessibility be addressed?

Finally, by making it cheaper to create Web maps than to build mobile apps, we will improve the business rationale for choosing the mobile Web as a development platform, and in doing so we hope the (mobile) Web will benefit from increased ‘success’, or network effects.

How will it be cheaper?

Goals

• Follow the HTML Design Principles to create HTML elements and attributes that

This is part of the proposal and doesn't belong in the goals.

(Edit by @Malvoz: Moved this part from the goals section in 8d983f6.)

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.

This by itself is a goal.

(Edit by @Malvoz: Extracted this part to describe a goal in 8d983f6.)

• Define and embed accessibility of map feature and location information into HTML for use by screen readers and other assistive technology.
• Define and design security of map information considerations into the Web platform.
• Define the markup to create mapping mashups that doesn’t necessarily require scripting or detailed mapping server technology knowledge i.e. that can be accomplished about as easily as linking to a document.
• Simplify the use of public spatial data infrastructures (SDI), such as Open Street Map and national and international SDIs, by designing the integration of those services into the proposed Web platform mapping standards.
• Defining and (advocate for) adding map-enabled HTML to the serialization formats available from existing spatial (map) content management systems, APIs and Web Services.

This last bullet point also seems to mix in the proposal. Is the goal to have one serialization format that is adopted by all spatial content management systems, APIs and Web Services?

Non-goals

• Changing the operating model or availability of existing spatial (map) content management systems, APIs and Web Services.
• Backwards-incompatible changes to HTML / breaking the Web

Breaking the web is not a non-goal, it's an anti-goal (or requirement to not do).

(Edit by @Malvoz: Removed this non-goal in 2a7800b.)

Alternative Approaches

• SVGMap - is it possible to merge the SVGMap proposal and this proposal? Or are they competing proposals?
• APIs: Leaflet, OpenLayers and others, (albeit others without any notion of cross-origin resource sharing) provide excellent map scripting APIs and events. Can these or similar APIs be built on top of the proposed HTML infrastructure? Would life be simpler for authors with the proposed HTML?
• Status quo

Good questions, and we should answer them and evaluate different proposals against the use cases and requirements.

A High Level API

The Extensible Web Manifesto calls for iterative development and evolution of platform features, starting with low-level ‘primitives’ and resulting eventually in high-level features. Although there are several low-level primitive proposals inherent or implicated in this proposal, overall this can be seen as a proposal for a high-level feature. That feature is declarative dynamic Web maps in HTML. Web mapping is a mature category of JavaScript library that is well into the stage of its development life cycle that some of the aggregate characteristics of those libraries should be incorporated into the platform. As such, this proposal captures some of the ‘cow paths’ of open and closed source JavaScript Web mapping libraries, as well as taking into consideration how to incorporate server-side mapping services and APIs.

That maps is a mature problem space and we can reach for a high-level API makes sense, but those APIs should still be on top of low-level primitives (existing or new ones).

The map element

To allow authors to create declarative Web maps that have approximately the same authoring complexity as <video> or <audio> elements do today, we propose to extend the processing model of the currently existing HTML <map> element. The current HTML <map> element, with its associated <img> and child <area> elements constitutes a simple Web map, wherein the pixel-based coordinate system of the element is shared and used by the <map>’s child elements to draw geometries to act as hyperlinks. This relationship, that of parent node-child node with a shared coordinate system is an ideal extension point for more dynamic Web mapping. If it turns out that the code involved in the <map> element implementation is too much like spaghetti, we will have to create a new and similar element anyway. So if possible we should avoid that particular form of technical debt and adopt, maintain and extend the existing <map> element.

map is a legacy element in HTML and is treated as essentially obsolete; it hasn't gotten new features or improvements, other than for web compat and interop. Reusing legacy elements in HTML for new features is usually not a good choice, as web compat constraints what can be done and it can be a source of confusion for web developers.

The web compat constraints cannot be understated. map is used on 1.96% of the web. Even things that seems minor can break pages. If you want to reuse a legacy element for a new feature, you need a very compelling case to make it worth the risk.

(Edit: filed https://github.com/Maps4HTML/HTML-Map-Element/issues/30 )

The proposed extension would create a standard <map> widget that contains controls in a closed shadow root,

This is opening a can of worms. Does this happen for all map elements? If yes, how does that not break web compat? If no, and it's toggled by an attribute, that seems like considerable implementation complexity and an unnecessary source of bugs.

(similar to <video> today), with child <layer> elements which are in, and may contain, light DOM map-related markup, the vocabulary of which is also part of this proposal.

What markup goes in a layer?

A working example custom element prototype is available (although it’s not yet a fully compliant ‘polyfill’. For one thing, it doesn’t work on Webkit due to the use of custom built-in elements. A parallel <geo-map> autonomous custom element suite is available for Webkit. For another, the light DOM content of <layer> is not currently active or available as an API).

Move the polyfill reference to an appendix or separate section.

(Edit by @Malvoz: Moved to a separate section in 15bfd7c.)

The map element

The layer element

A layer is a primitive abstraction that is shared by many if not most maps, both on and off the Web. Even in the case that a map doesn’t have more than a single layer, the map itself can be considered to be composed of that single layer. A key characteristic of map layers is that they share the same coordinate system as other layers in the map, allowing the rendering engine to lay out and render content over the same coordinate space. This is in contrast to the normal rendering of HTML elements, which are laid out in document order down the page. There is precedent for the proposed rendering model for maps in HTML, however. The “client side image map” of HTML, implemented by the <img>, <map> and <area> elements, has this rendering model; the <area>s “coords” attribute are expressed in units of the pixel-based coordinate system of the <map>-associated <img> element.

Other examples: <canvas> (imperative), SVG (declarative). While they are things that have a coordinate space, and maps have that as well, it doesn't follow that it necessarily makes sense to build a maps feature on top of them.

An author-friendly system for dynamic Web mapping, such as that intended by this proposal, would make it as simple as possible to automatically layer map content, ideally re-using and extending the markup for <img> <map> and <area> that has become familiar. A more thorough discussion of how this proposal conforms or relates to the HTML Design Principles is beyond the scope of this explainer, but is available here.

(I'll review that separately.)

The layer element

Layers are added to maps by adding <layer> elements as children of the <map> element. Every <layer> added to the map must share the same coordinate system declared by the <map> in its projection attribute. If the layer added does not share the same coordinate system as the <map>, it will not be displayed and the layer will be ‘disabled’ in the layer control of the map widget. The set of possible coordinate systems is small, and the values enumerated by the MapML specification. If no projection attribute is specified, the default coordinate system is that of Web Mercator, signified by the “OSMTILE” value.

The <layer> element renders content by one of two alternate means. The first is by referring to remote content at a URL specified by the src attribute. This is described under Key Scenarios below. The response to a request the the src’s value should be “MapML” content, identified over the network by the “text/mapml” media type. MapML is intended to be part of the HTML vocabulary and to be parsed with the (almost) unmodified HTML parser.

"(almost) unmodified HTML parser" implies modifications. Which ones, and why? Proposals to change to the HTML parser is usually met with resistance from browser vendors due to the risk of resulting security problems. See whatwg/html#2253 (comment)

To achieve that, some elements in the MapML specification rely on and extend the definitions of elements of the same name in HTML. The second rendering path for <layer> is to include “MapML” content inline in light DOM.

(I'll review the spec separately.)

It’s great that we can imagine a way to extend HTML to include dynamic Web maps using almost-existing browser code infrastructure,

What does almost-existing browser code infrastructure mean? What infrastructure is missing?

but where will layer content as envisioned come from? Without content, new browser code would not be useful. What’s needed is a way to get the vast amount of existing content from services that have well-defined standard and not-so-standard interfaces, into the new HTML-MapML format available at simple URLs, without requiring significant change to the content, but especially without requiring browsers to ‘understand’ interfaces other than the uniform interface of HTTP. This might seem like a tall order, but a key design constraint followed by HTML-MapML is that the vocabulary itself should represent abstractions that ‘fit’ the existing content, so that if the services by which the content is accessed today were to provide HTML-MapML as a serialization format, then such content would be rendered inherently compatible with browsers, even before script execution. Such experimentation has formed the basis of significant experimentation by several participants through the OGC Testbed program, and has proven to be readily possible in practice, through the creation of server shims. We anticipate that should the Web community agree to work with the mapping community on this proposal, that we will have success in persuading the public spatial data infrastructures around the world to be made available to the browser in HTML-MapML.

I appreciate the chicken-and-egg problem, but I think it's not really a problem. Browsers implement features based on the feature's own merit all the time, without needing prior existing content. The motivation for a polyfill should be to get real-world experience and iterate on the API shape to inform what the standard API should look like, and to demonstrate support from web developers.

Moreover, I think creating a legacy of web content before a proposal is implemented can hurt the proposal more than it helps. Bugs in the polyfill can get relied on by web content, resulting in the final API needing to use different names from what is used in the polyfill. (Examples: Array.prototype.contains; Node.prototype.rootNode)

For the situation of no browser implementation and only a polyfill, I suggest not using the names that you want to reserve for the final API until it is shipped by at least one browser. (This was practiced by PictureFill, which used spans until picture was implemented in browsers.)

Even using a feature after it has been shipped by one browser is not without problems: bugs in the first implementation can get relied on (accidentally) by web content, leading to those bugs getting "stuck", and other vendors having to copy those bugs, or it can take considerate effort over many years to remove the original API. (Example: Shadow DOM, which had a spec, then shipped, then the spec changed significantly, but the original implementation couldn't be removed due to web compatibility. "v0" was finally removed this year, 6 years after it was introduced, and 4 years after "v1" shipped.)

I'll skip reviewing the remainder of the explainer for now. If getting maps a first-class feature in the web platform is a goal, the process is imperative to its success.

(snip)

Use Cases and Requirements

This proposal is being evaluated against the Use Cases and Requirements for Web mapping, to identify gaps between the required functionality and the polyfilled behaviour.

Considered alternatives

TBD - we have considered many alternatives, I have just run out of steam to document them, at the moment. Also this document is already quite long. As things progress, I will add content here.

I'm looking forward to seeing those alternatives documented.

Stakeholder Feedback / Opposition

Some participants have said we should start over, because of the sunk costs fallacy; that doesn’t seem to be in the spirit of iteration, nor hopefully is it correct to see this proposal as a waste of energy or money. A better strategy would be to solicit concrete, actionable and incremental change requests. It is in that spirit that the current explainer is offered.

It's not a waste to develop a concrete proposal, but I think it should be positioned as one proposal out of several when several exist, and be open to being evaluated as such.

The objective of this project is to get Web browser projects to agree that Web maps as a high level feature are desirable and that the proposal is implementable, and then to implement and ship the feature. To get there from here, we need browser developer participation, the absence of which appears equivalent to opposition. So, there is work to do.

I hope my feedback here is helpful for the getting from here to there.

(snip)

Gridsets, Tile Matrix Sets, Tile Caches etc

<map> and <layer> to unify OpenLayers, Leaflet, ESRI, Google Maps, Apple Maps, HERE, D3, MapBox, TomTom, Bing Maps, OpenStreetMap, WMS, WFS, WMTS etc.:

This section reads a little bit insulting, which was not the intent. It was meant to suggest that direct integration of REST APIs is not an achievable of desirable goal of the Web platform.

We should look at some other explainer non-goals sections to see if there is a pattern we should follow.

I would be in favour of removing the section until it can be re-written, fwiw.

https://github.com/Maps4HTML/MapML-Proposal#the-textmapml-mime-type

The proposed doctype for such a map document is <!doctype mapml>

https://maps4html.org/MapML/spec/#documents

A MapML document is a [MicroXML] document. As such, it MUST have a single root element named <mapml>. It MUST NOT have a DOCTYPE declaration

MapML Use Case, Requirement, and Capability Matrix (comes from the h1 of that document, was added in #27) I think reads too similar to Use Cases and Requirements for Standardizing Web Maps. It is also a strange title to refer to in writing.

I suggest renaming to MapML UCR Fullfillment Matrix, that's also how it is referred to from the index at https://maps4html.org.

If there is agreement to change this, it must also be reflected in https://maps4html.org/MapML/spec/#use-cases-and-requirements (Edit: created Maps4HTML/MapML#178).

@prushforth WDYT?

it's worth making an example, if we can, of the built-in that falls back to an image map in Safari.

Originally posted by @prushforth in #39 (comment)

Is the purpose of the sections Alternative considerations and Considered Alternatives the same? Can we remove one?

Specifically, when we mention "OpenStreetMap" and "GeoJSON", we should have links, at least the first time they're mentioned, as not everybody is going to be familiar with these concepts.

Suggested URLs:
https://wiki.openstreetmap.org/wiki/Main_Page
https://tools.ietf.org/html/rfc7946

Un-composed URLs to map documents that have a defined map media type ~ compatible with the existing HTML parser and which defines map document, not map/feature/location API semantics (hypermedia constraint)

I think it's valuable to reference https://www.w3.org/2020/maps/report, perhaps under a new heading in the Detailed design discussion section.

The explainer currently only mentions the HTML Design Principles. I think it's appropriate to also mention the Web Platform Design Principles.

It seems that WebKit is proposing a <model> HTML element. It would be ideal if we could join forces to persuade that team that spatial data is a keystone for XR, and their <model> might be made to work well with <map> .

Let's discuss use cases for how to conceptually integrate the two proposed elements, and how they could share real-world coordinate systems.

/cc @cperey @lieberjosh @janerivi @hober @othermaciej

This issue will be the parent of issues which are identified as "low-level features", or primitives of the Web platform, which are not currently implemented and which form part of this proposal. This will serve as an inventory of features we are asking to be developed and standardized in the Web platform.

• Web Mercator
• Canadian Geospatial Data Infrastructure's Lambert Conformal Conic definition
• WGS 84
• Virtual globes (Dynamic Azimuthal Equidistant)(?)

Some(one) expressed concerns around humans writing (complex) MapML (I can't find the particular statement that I vaguely recall, can search harder if that's necessary), this is mostly a misunderstanding, similar to SVG or MathML, while the markup can be written manually for certain use cases, it's mostly going to be generated by data providers and tools.

We should clarify this. MapServer does a good job of that:

Don’t worry about the complexity of the <mapml> document. It is automatically generated by MapServer and consumed by the viewer. It is not intended to be generated by humans.

As does MathML:

https://w3c.github.io/mathml/#abstract:

While MathML is human-readable, authors typically will use equation editors, conversion programs, and other specialized software tools to generate MathML. Several versions of such MathML tools exist, both freely available software and commercial products, and more are under development.

https://w3c.github.io/mathml/#interf_genproc:

although MathML can be written by hand and read by humans, whether machine-aided or just with much concentration, the future of MathML is largely tied to the ability to process it with software tools.

We should probably add a paragraph or two with a similar statement about MapML under the Map Markup elements heading.

And I think we should rename that heading to MapML Document elements because the Web Mapping elements: <map>, <layer>, <area> (which are intended to be written widely by humans) are "Map Markup elements" too.

We should certainly include the clarification in the MapML spec as well.

Interactive form element for map content loading (<extent>) from geospatial / OGC / non-spatial services and APIs