KML Best Practice

The increase in applications consuming and producing KML (which powers applications like Google Earth™) requires that best practices be established to promote interoperability. This document describes best practices for validating KML and for using metadata and attribution. These best practices supplement the OGC KML 2.2 & 2.3 Specifications and Google KML Reference.

• Validating KML
  • Types of Validation
  • Well-formed validation
  • Schema validation
  • Specification validation
  • KML Validation Tools
  • Basic validation
  • KML Schema Validation tools
• Managing Saved Places KML in Google Earth
  • Maintenance and periodic cleaning of your saved places
  • Best Practice for KML Developers
  • Repairing a damaged or corrupt KML file
  • Backups
• KML Attribution / Contribution
  • Add Attribution as XML comments in the KML file
  • Add Attribution to description
  • Add Attribution as ExtendedData
• Reference

Validating KML

Types of Validation

There are three classes of KML validation that apply to XML-based standards.

1. Well-formed validation. This validates a given XML document is well-formed with respect to XML standard meaning:

• The XML document has a single root element.
• All start and end tags are matched and names are case sensitive.
• Attribute names in elements are unique (i.e., no duplicate names).
• Content contains only characters allowed by the appropriate encoding (e.g., UTF-8, etc.).

In most cases, a KML document will not load in Google Earth™ if it is not well formed.

A common error found in KML files involves labeling the file with the default UTF-8 encoding in the XML prolog while inadvertently copying/pasting an international character or graphic symbol (e.g., the degrees symbol º) from an email or document in the description field of one of the placemarks. Google Earth ignores such errors, but strict XML parsers fail to parse them and abort loading these documents with a fatal parse error. Replacing the UTF-8 encoding with ISO-8859-1 in the XML prolog resolves this issue.

2. Schema validation. Valid XML documents conform to declared XML Schema specifications and its structure is valid as defined by the Schema.

• Schema defines a strict order of elements and spelling of element/attribute names which are case-sensitive.
• KML schema defines the hierarchy of abstract and concrete elements and as such what elements/attributes are inherited.
• KML schema defines where non-KML namespaces may appear.

In case of KML, valid documents conform to the published OGC KML 2.2 XML Schema and additional schemas as defined in the given KML document instance.

3. Specification validation. Valid KML documents conform not only to the KML XML Schema but also follow the strict design and business rules as defined in the specification. Many such rules are not covered by KML XML Schema validation.

For example: KML specification defines the following rules:

• LineString geometries consist of two or more coordinate tuples, each consisting of floating point values for longitude, latitude, and altitude. The altitude component is optional. Space must be inserted between tuples. Do not include spaces within a tuple.

• LinearRing contains four or more tuples, each consisting of floating point values for longitude, latitude, and altitude. The altitude component is optional. Do not include spaces within a tuple. The last coordinate must be the same as the first coordinate. Coordinates are expressed in decimal degrees only.

The coordinates component of a LineString and LinearRing from the KML XML Schema perspective must only be a list of strings separated by whitespace so "a b c" is valid by its schema type definition and likewise there is no range checking of latitude/longitude values within coordinate tuples.

• The value of the following Feature elements shall be inherited by all Feature members of a hierarchy: atom:author, atom:link, Region, and TimePrimitive, unless overruled by the presence of such elements locally. Inheritance of these elements continues to any depth of nesting, but if overruled by a local declaration, then the new value is inherited by all its children in turn.

Additional discussion of validation can be found in the KML Errata.

KML Validation Tools

    <atom:link href="https://maps.google.com/?ll=37.50002,127.03656..." />
----^

Managing Saved Places KML in Google Earth

	<NetworkLink>
		<name>Colored by Age</name>
		<visibility>1</visibility>
		<open>0</open>
		<Snippet maxLines="1">Updates every 5 minutes</Snippet>
		<Link>
			<href>http://earthquake.usgs.gov/earthquakes/feed/kmlage/1.0/week</href>
			<refreshMode>onInterval</refreshMode>
			<refreshInterval>300</refreshInterval>
		</Link>
	</NetworkLink>

KML Attribution / Contribution

Organizations should use a disciplined approach in how they deliver their KML services. Without such an approach, information within the KML files can become outdated or used inappropriately, resulting in decisions based on misleading or obsolete information. Attribution such as the following should be included within the KML data to ensure that user expectations are clearly defined with regard to the data provided via KML.

• Information Current As Of Date
• Frequency of KML file/service updates
• Office of Primary Responsibility
• Contact Phone Number / Website / Email Address
• Source of Information
• ...

Add Attribution as XML comments in the KML file

The simplest but least desirable method is to include the metadata as unformatted text nested inside an XML comment at the start of the KML file as shown below. The attribution metadata is included with minimal change to the KML, but the data is hidden from the casual user. To view this text, an end user would need to view the source of the KML as XML. Typically only a developer would attempt to view the raw KML data. This is the quickest approach to just annotate the KML with appropriate attribution text.

<?xml version="1.0" encoding="UTF-8"?>
<!--
Information Current As Of 2010-01-25T08:00:43Z
Frequency of KML file/service updates:
	KML updated daily at 0800Z or something like NetworkLink auto-refreshes with default update rate at 60 second interval.
	Data updates are available every 10 seconds so clients can change the update interval to no less than 10 seconds.
Office of Primary Responsibility: My Company
Contact Phone Number / Website / Email Address: 123-555-1212 anyuser@domain.any.org
Source of Information: XYZ System
...
-->
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
...
</Document>
</kml>

Add Attribution to description

The second method is to add metadata attribution to the description element of the outermost container element in the KML. This allows producers to add attribution metadata to a KML Feature, where the description is displayed in a pop-up balloon in Google Earth™ when an end user clicks on that feature. Producers can format the description using the richness of HTML, including JavaScript and CSS. Consider adding a snippet with a short description that appears in the menu list view while the full description appears in the Feature's pop-up balloon.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <Snippet>
    Short description of the data/service
  </Snippet>
  <description>
<![CDATA[
Description of the data/service
 
<B>Information Current As Of 2010-01-25T08:00:43Z</B><BR>
<B>Frequency of KML file/service updates:</B><BR>
 NetworkLink auto-refreshes with default update rate at 60 second interval.<BR>
 Data updates are available every 10 seconds so clients can change the update interval to no less than 10 seconds.<BR>
<B>Office of Primary Responsibility:</B> My Company<BR>
<B>Contact Phone Number / Website / Email Address:</B><BR>
 123-555-1212 anyuser@domain.any.org<BR>
<B>Source of Information:</B> XYZ System<BR>
...
  </description>
...
</Document>
</kml>

Add Attribution as ExtendedData

The third approach involves adding the metadata in an ExtendedData element to the KML document. This method is a machine-parsable implementation; the other methods added metadata as unstructured free-form text. Example below shows the raw KML text for this approach. As in the second approach, adding attribution to the description, in this method the end user can view the metadata formatted in a pop-up dialog box when it is viewed in Google Earth™. If the Document element has no description tag then the ExtendedData is autoformatted in Google Earth™ as an HTML table with a border around the table cells. The ExtendedData values also can be inserted into a custom description or BalloonStyle template using Entity Replacement for Extended Data Elements, with the names of the ExtendedData elements as placeholders (e.g. $[ContactPhone]).

For further details see Google's Tutorial on Adding Custom Data to KML.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
      <ExtendedData>
        <Data name="Information Current As Of">
          <value>2010-01-25T08:00:43Z</value>
        </Data>
        <Data name="Update Frequency">
          <value>NetworkLink auto-refreshes with default update rate at 60 second interval.
 Data updates are available every 10 seconds so clients can change the update interval to no less than 10 seconds.</value>
        </Data>
        <Data name="Office of Primary Responsibility">
          <value>Data Owner</value>
        </Data>
        <Data name="ContactPhone">
          <value>123-555-1212</value>
        </Data>
        <Data name="ContactEmail">
          <value>anyuser@domain.any.org</value>
        </Data>
        <Data name="Source">
          <value>XYZ System</value>
        </Data>        
      </ExtendedData>
...
</Document>
</kml>

Reference

• OGC KML Standard (Specification and related documents)
  OGC KML Standard Development Best Practices, OGC Document 08-125r1 Version: 0.6

• KML Reference Errata and Addendum
  http://kml4earth.appspot.com/kmlErrata.html

• Google KML Reference
  https://developers.google.com/kml/documentation/kmlreference

• KML Validator service
  http://www.kmlvalidator.com/home.htm

Google Earth (TM) and Google Maps (TM) are registered trademarks of Google Inc. KML4Earth is not affiliated with Google.
KML4Earth is not an official source of information on Google or Google Earth. But, we try to get reliable information whenever we can.

Created and maintained by jasonm1