kml:description considered harmful

KML lacks two important elements. It has neither 1) a simple and universal element equivalent to Dublin Core description (such as {http://purl.org/dc/elements/1.1/}description), nor 2) an excellent element for encapsulating or linking to rich content accompanying placemarks. Instead of the first, we have kml:Snippet. Snippet! It's somewhere in between a title and a description and that's no place to be. Instead of the second, we have kml:description, which supports an under-specified subset of HTML and other media including video.

The kml:description element is not about metadata anymore, it's about adding rich content -- charts, photos, video -- to popup windows of a geographic browsers. Under-specification of the content of kml:description is a problem. Which HTML elements are valid? Why shouldn't all be valid? The choice only between escaping HTML and using CDATA blobs is another problem. XHTML in a description wouldn't break the KML document; why shouldn't we be able to use XHTML without CDATA? Lack of support for dynamic content is yet another problem. Why can't we specify rich content by a URL, to be fetched only as needed and refreshed only if modified? Limitations of KML's description element and its ties to the original implementation hold us back. We need something better.

The Atom community wrestled with the same issues and came up with the atom:content element. An atom:content element may contain text, HTML, XHTML, XML, encoded binary media, or provide a URL to another document or media resource. When prompted, Atom processors (such as a news reader) display this content to a user. All HTML or XHTML elements are valid. CDATA blobs are unnecessary and not allowed. Atom's content element comes with clear processing instructions: HTML must be escaped, and should be valid within a <div>. The immediate child element of XHTML content must be a <div>. While guided by implementations, none of this depends on unspecified behavior of a particular Atom processor.

The "src" attribute of the atom:content element provides developers with more options. It allows you to decouple semi-static data from dynamic data. The locations and identifiers of physical instruments deployed in the field (river gauges, ASOS, you name it) can be decoupled from their nearly real-time observations and measurements. Serve a representation of the deployed instruments as a static document updated only as are the physical objects. From each instrument entry, link to a specialized web resource that produces tables or graphs on demand.

Atom processors can also take advantage of the "src" attribute to improve performance perceived by a user. Fetch the feed, show users titles and summaries first, get rich content as the user asks for it -- or get the rich content in the background, or during lulls in user activity. Processors should also be able to exercise conditional GET to avoid reloading unchanged rich content.

The atom:content element appears to support all of the requirements of, and overcome all of the faults of, kml:description. It fully embraces and accommodates rich content and provides new design options via links to dynamic or massive content. KML is already open to Atom elements (version 2.2 already includes atom:author, atom:link, and atom:name) and so atom:content is a more natural replacement for kml:description than RSS 1.0's content element or RSS 2.0's enclosure element. I'm not in a position to offer any advice to Google, but -- considering its investment in Atom, to act on the commonalities between KML and Atom seems useful and even profitable.

I've heard from KML folks that nothing pushes the spec forward more than working code. I'm not interested in writing a new geographic browser, but I can start serving KML enhanced with atom:content (which meets needs of a user that just cropped up on Monday), support it in my own KML processing packages, and perhaps even exercise my withering C++ skills on a libkml patch. After that? Let's swap in atom:summary for kml:Snippet. Snippet!

Comments

Re: kml:description considered harmful

Author: Matt Giger

I feel your pain, really I do. EarthBrowser follows the KML spec when it can but in order for it to be useful, I've changed it where reasonable. For example, if the description element starts with 'http', it loads that page or image. Don't you love how Snippet is capitalized unlike all other nodes with no children? How about that "maxLines" attribute? I've heard that "working code" suggestion to my request for improvements too, it's just an easy way to divert criticism. By handing KML over to the OGC, they got government agencies to adopt it, but they lost the ability to fix the broken parts. Sadly, I suspect that KML will die over time if it cannot be improved. I've been moving away from KML lately. It is very useful in many circumstances, however it is too rigid, bloated and confusing to author with. I've written on my blog a long time ago about how the structure of KML shows the innards of Google Earth and it isn't very impressive. Looking at the new Google Earth browser plugin API, you can see that it's internal structure remains static and ossified. GEarth, and by extension KML, is in desperate need of a re-write, I hope the OGC will grant Google permission to add some new features to it's KML based data browser.

Re: kml:description considered harmful

Author: Bryan Lawrence

Oh please, please, someone from Google read this and do the right thing (TM)!

Re: kml:description considered harmful

Author: Sean

Thanks for the comments. Matt, is this something your EarthBrowser could support? I've read some statements by Google Earth folks that don't rule out development of non-standard features related to KML, but you've had more interaction with them than I. If you're pessimistic, maybe I should dial down my optimism.

Re: kml:description considered harmful

Author: mpd

OGC does not need to "grant" anyone permission to make changes to any standard. The OGC change request procedure is open to members and non-members alike, and so Sean can go ahead and submit this request. The OGC is then obliged to act on it. Google uses the same procedure, so you are now equals, although they do have the source code for Google Earth, of course.

Re: kml:description considered harmful

Author: Sean

Wow, that change request procedure is worse than a lashing. Is it so to discourage trivial requests? It might be less work to patch libkml. I downloaded the form and the empty (!) instructions, got started on it, but editing the KML Word file (!) will have to wait a week or so.

Re: kml:description considered harmful

Author: mpd

I didn't say that it was a good process, just an open one.