Validating KML As You Go

To use some of KML's more advanced features (such as, Region, TimeSpan/TimeStamp, ScreenOverlay, and Tours), you must author the KML yourself, since there are no options in Google Earth for creating these features. You could use a basic text editor, such as Notepad on Windows, or TextEdit or TextMate on Mac OS X, but they don't provide any error-checking. This means that you won't discover mistakes until you try to open the file in Google Earth, and receive a parse error.

jEdit is an open-source, Java-based text editor that works on Windows, Mac OS X, and Linux. Using a few additional plug-ins, jEdit provides as-you-type error checking to ensure that your KML is well-formed and validates against the official KML schema. You can also use the Super Abbreviations plugin to quickly insert snippets of KML. This tutorial will show you how to set-up jEdit for editing KML, demonstrate some of its error-checking abilities, and show you how to use the KML abbreviations.

Prerequisites

  • No programming skills needed.
  • Familiarity with KML code will help, but advanced knowledge is not required.

Install the software

The first thing you'll need to do is install jEdit and the Java Runtime Environment that it relies on. You'll also need to download a file that we'll use later in the tutorial.

Install the Java Runtime Environment (JRE):

  1. Go to http://www.java.com and click Free Java Download.
  2. Follow the instructions provided to install JRE.
    Note that your computer may already have JRE installed. Please ignore any messages about Java not being compatible with your browser, and download & install JRE anyway.

Install jEdit:

  1. Go to http://www.jedit.org and click the Download link in the upper right corner of the page.
  2. Choose the latest stable version near the top of the page, which at the time of this writing is jEdit 5.0.0.
  3. Install jEdit on your computer:
    1. Windows users, Download and Run the appropriate installer for your operating system.
      Note: During the Windows installation process, we recommend that you use the defaults for all settings, except that you should uncheck the option for: "Start jEdit Server automatically on system startup". This feature isn't required, and unselecting it will prevent unnecessary programs from starting up on your computer.
    2. Mac OSX users, download the .dmg file, open it, and copy the jEdit.app file to your Applications folder. If you see an error that says "jEdit.app is damaged and can't be opened...", go into the OSX Security & Privacy control panel and choose to Allow application downloaded from: Anywhere.

Download the abbreviations file:

  1. Right-click the link below and select Save As, Save Link As, or Save Target As, depending on your browser.

    kml_superabbrevs_gx.abv - jEdit Super Abbreviations for KML
     
  2. Save the file to your hard drive, somewhere you can find it again.

    Note that this is not a pure text file. It contains some binary codes, so don't worry if you open it up in a text editor and see strange characters.


Set up jEdit for KML editing

Open the General Options dialog:

  1. Open jEdit if it's not already open.
  2. Select Utilities (menu) > Options > Global Options (tab)
jEdit Screenshot - Utilities menu, Options

Set up jEdit to treat KML files as XML:

  1. In the Global Options Dialog, go to the list on the left, and under the jEdit folder, select the Editing page.
  2. Select the "Change settings for mode:" dropdown and select "xml"
  3. Un-check the Use default settings checkbox.
  4. In the lower half of the page, find the "File name glob:" option.
  5. Edit the line to add ",kml" inside the brackets, so that the line ends up looking like the line below:

*.{xml,xhtml,xsd,qrc,ui,docbook,kml}

  1. Click Apply at the bottom of the Global Options dialog

Set Editing options for XML (& KML):

NOTE: This step is OPTIONAL. We recommend that you use the settings below to help your KML comply with the Google KML style guidelines, but if you use jEdit for other XML editing tasks which require different settings, then you may skip to the next section below.

  1. While still in the Global Options dialog, on the Editing page...
  2. Make sure the "Change settings for mode:" dropdown, has "xml" selected.
  3. Change Tab width to 2
  4. Change Indent width to 2
  5. Check the checkbox for "Soft (emulated with spaces) tabs"
  6. Change Default edit mode: to xml
  7. Your Editing options for xml mode should now look like those in the image below. Click Apply at the bottom of the Global Options dialog.
jEdit screenshot - General Options, Editing XML

Set the default character encoding to UTF-8:

NOTE: This is OPTIONAL. UTF-8 is a standard character encoding that works well on most systems, and we recommend it for KML, especially if you plan to use international characters. But if you use jEdit for other types of work, and don't want to change the default encoding to UTF-8, then you may skip to the next section below. If you don't set UTF-8 as default, then please remember to set the encoding for your KML files to UTF-8 whenever you create or edit them, buy selecting Utilities (menu) > Buffer Options > Character Encoding (dropdown) > UTF-8.

  1. Select Utilities (menu) > Options > Global Options (tab) > Encodings.
  2. Select the "Default character encoding:" dropdown.
  3. From the dropdown, select "UTF-8".
  4. Click Apply at the bottom of the Global Options dialog
    Note: If you have any currently open kml files, check that they are encoded in UTF-8, at Utilities > Buffer Options... > Character encoding.
jEdit screenshot - General Options, Encodings
  1. Click OK to save your changes and close the Global Options dialog


Install jEdit plugins

  1. Open jEdit, click on the Plugins menu, and select Plugin Manager
  2. Click on the Install tab of the Plugin Manager window
  3. Select the following plugins:
    • SuperAbbrevs
    • XML  (Note: jEdit will automatically select these other associated plugins: CommonControls, EclipseIcons, ErrorList, SideKick, and XercesPlugin)
jEdit screenshot - Plugin Manager, install plugins
  1. Click the Install button to download and install the plugins
  2. Click the Manage tab to check that all the plugins are installed: SuperAbbrevs, XML, etc.
  3. When complete, click the Close button to dismiss the Plugin Manager

    Note: If the plugin download is slow, does not progress, or displays an error, then you can follow the steps below to choose another download server:
    1. Stop the download
    2. Click the Download Options button
    3. Click on Update Mirror List
    4. Choose a geographic location close to you
    5. Click OK
    6. Repeat steps 1-6 above to select and install the jEdit plugins.


Configure the plugins

Open the Plugin Options Dialog:

  1. Select Plugins (menu) > Plugin Options

Configure the Side Kick plugin:

  1. Click and expand the SideKick plugin folder in the list on the left
  2. Select General underneath SideKick
  3. Under Auto parsing Settings, check Parse on buffer save
  4. Under Auto parsing Settings, check Parse on keystroke
  5. Adjust the slider After last keystroke, wait (seconds) to 1 second.
    Note that you can adjust this setting later to change how long jEdit waits after you finish typing to check the KML file for errors.
  6. Click Apply at the bottom of the Plugin Options dialog
jEdit screenshot - Plugin Options, SideKick

Configure the Error List plugin:

  1. Click to select the Error List plugin in the list on the left
  2. Check Automatically display on error (should already be checked by default)
  3. Check Auto-close on no errors
  4. Check Auto-refocus on Text Area
  5. Check Show error icons in the gutter
  6. Click Apply at the bottom of the Plugin Options dialog
jEdit screenshot - Plugin Options, ErrorList

Configure the Super Abbreviations plugin:

  1. Click and expand the SuperAbbrevs plugin folder in the list on the left.
  2. Select Abbreviations under SuperAbbrevs.
  3. Using the Select Mode: drop-down menu, select xml.
  4. Click the Import normal abbrevs button at the lower right.
  5. Click on the Import from file button, which is the fourth button, near the plus (+), minus (-), and Edit buttons near the bottom of the dialog window.

    Note: In some versions of jEdit, the Import from file button may not be visible, but don't worry, it is still clickable! If you don't see the fourth button to the right of the others, place the mouse over the center of the (+) or (-) button and slowly move it horizontally to the right (across the Edit button), until a small square appears under the mouse, and then click. On some systems, the tool-tip "Import from file" will appear when you are over the correct spot for the button.
jEdit screenshot - Plugin Options, SuperAbbrevs, import abbreviations
  1. In the Open dialog window, navigate to where you saved the kml_superabbrevs_gx.abv file. Select it and click the Open button.
  2. Click Apply at the bottom of the Plugin Options dialog.
jEdit screenshot - Plugin Options, SuperAbbrevs, Imported
  1. Click OK to close the Plugin Options window.


Dock the plugins

We like to dock the Error List plugin at the Bottom of the jEdit window, and the Side Kick plugin on the Left side of the jEdit window. This makes them easily accessible as you edit your KML.

Dock the Error List plugin:

  1. Select Plugins (menu) > ErrorList > Error List
  2. Find the Error List window which has appeared (it might appear behind the main jEdit window).
  3. Click on the small, black, downward pointing arrow at the upper left of the window.
  4. Choose Dock at Bottom
  5. The Error List window is now docked at the bottom of the main jEdit window. It can be expanded or collapsed by clicking the Error List button at the button.

Dock the Side Kick plugin:

  1. Select Plugins (menu) > SideKick > SideKick
  2. Find the Sidekick window which has appeared.
  3. Click on the small, black, downward pointing arrow at the upper left of the window.
  4. Choose Dock at Left.
  5. The Sidekick window is now docked at on the left of the main jEdit window. It can be toggled by clicking the SideKick button on the left (below the File Browser button).

You should now see the Error List button at the bottom and the Sidekick button at the left of your jEdit window, as shown below. Click the buttons to open or close the window for each.

jEdit screenshot - plugins docked

Create keyboard shortcuts for SupperAbbrevs

In this section we'll set some keyboard shortcuts for the SuperAbbrevs plugin, so that you can quickly create KML with very little typing.

Open the Shortcuts settings for SupperAbbrevs:

  1. Select Utilities (menu) > Options > Global Options (tab).
  2. Select the Shortcuts page from the list.
  3. From the Edit Shortcuts drop-down menu near the top of the window, select: Plugin: SupperAbbrevs.

For the Shift Tab command, set shortcut S+TAB:

  1. In the first row, for "Shift Tab", click the middle cell to edit the Primary Shortcut (the column should be labeled "Primary Shortcut", but may be blank).
  2. In the Specify Shortcut dialog that appears, press your SHIFT & TAB keys together to create the S+TAB shortcut.
  3. Click OK to close the dialog.
    Note: You may see a warning that S+TAB is already used by another command, but unless you specifically use it for other work, you can safely override it.

For the Show expansion dialog command, set shortcut C+ENTER:

  1. In the second row, for "Show expansion dialog", click the middle cell to edit the Primary Shortcut.
  2. In the Specify Shortcut dialog, press CTRL & ENTER together, (Command and Enter on a MAC) to create the C+ENTER shortcut.
  3. Click OK to close the dialog.
    Note: You may see a warning that C+ENTER is already used by another command, but unless you specifically use it for other work, you can safely override it.

For the Tab command, set shortcut TAB:

  1. In the third row, for "Tab", click the middle cell to edit the Primary Shortcut.
  2. In the Specify Shortcut dialog, press your Tab key to create the TAB shortcut.
  3. Click OK to close the dialog.
    Note: You may see a warning that TAB is already used by another command, but unless you specifically use it for other work, you can safely override it.
jEdit screenshot - Global Options, Shortcuts for SuperAbbrevs
  1. Click OK to close the Options dialog.

Now you're ready to start editing and validating KML!

KML Schema Headers:

Don't worry about this right now, but when you create a new KML file using SuperAbbrevs (detailed below), then the validation and error-checking tools will work as expected. But if you open an existing KML file, or copy/paste KML code into your file from Google Earth or elsewhere, it may not contain all the necessary Schema header information for the plugins to work. In this case, replace the <kml...> line in your file, either using SuperAbbrevs, or by copy/pasting the complete <kml...> tag below:

KML Schema Header:

<?xml version="1.0" encoding="UTF-8"?>

<kml xmlns="http://www.opengis.net/kml/2.2"
     xmlns:gx="http://www.google.com/kml/ext/2.2"
     xmlns:kml="http://www.opengis.net/kml/2.2"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation=
       "http://www.opengis.net/kml/2.2
        http://schemas.opengis.net/kml/2.2.0/ogckml22.xsd
        http://www.google.com/kml/ext/2.2
        https://developers.google.com/kml/schema/kml22gx.xsd
        http://www.w3.org/2005/Atom
        http://schemas.opengis.net/kml/2.2.0/atom-author-link.xsd">

<!-- ...Insert your KML code here... -->

</kml>

The KML Schema Header is also available in this file: kml_schema_header_gx.txt.




Let's try it...

This section will walk you through using SuperAbbrevs and other tools to create a basic KML file. We'll introduce some invalid code to see how the ErrorList and Sidekick plugins can be useful for catching errors debugging your KML files.

Start a new KML file:

  1. Open a new "buffer" (a new file) by clicking the "New" button on the toolbar, or by selecting File (menu) > New.
  2. Click the "Save" button on the toolbar, or select File (menu) > Save As...
  3. In the Save dialog, navigate to the location where you want to save your file (eg: C:\Users\<username>\Desktop on a PC).
  4. Type in a new File name (eg: coolmap.kml)
  5. Click the Save button to save the file and close the dialog box.
    Note: when you save the file with the KML extension, jEdit now knows to edit that file in XML mode, so you should see XML selected as the Edit mode in the Sidekick bar on the left, as well as in the Buffer Options dialog (Utilities (menu) > Buffer Options).

Create the basic KML file structure using SuperAbbrevs:

  1. On the first line of the file, type "kml" (without the quotes) and then hit Tab.
  2. You should see the <xml...> tag, <kml...> tag, and </kml> tags appear, with your cursor between the <kml...> and </kml> tags.
    NOTE: The first time you start validating a KML file, the XML plugin will need to download the schema files. When the dialogs titled "Getting resource from remote server" pop up, click Yes for each one (usually 4 of them), to allow the XML plugin to download and cache the necessary files.
  3. Type "doc" (no quotes) and then hit Tab.
    You should see the <Document...>, <name>, and </Document> tags appear, with your cursor highlighting the "doc_id".
  4. Without moving your cursor, type an ID for your KML document (eg: "kml_doc01").
  5. Hit Tab to move to the next variable (doc_name).
  6. Type a name for your document, which will appear in the layers list, for example: "My First Validated KML" (no quotes).
  7. Hit Tab to move the cursor to the next position, between the <name< and </Document< tags.
  8. Type "atom" (no quotes) and then hit Tab.
    You should see the Atom attribution tags appear.
  9. Type your Author Name and a URL (eg: http://www.google.com/earth/outreach) for your KML page or website, hitting Tab to move between them. You can also use Shift-Tab to move back to the previous variable.
  10. When you have filled in the attribution values, hit Tab to go to the end of the line, and then hit Enter to create a new, empty line between the <atom> and </Document> tags.
  11. Save your file so far, using the Save button, or Ctrl-S, or File (menu) > Save.
jEdit screenshot - Sample KML Document

Use SuperAbbrevs to create content in your file:

  1. Type "point" (no quotes) and hit Tab.
  2. You should see a <Placemark> appear, with many sub-tags.
  3. Give your Placemark an ID (eg: "point_01"), then hit Tab.
  4. Give your Placemark a name (eg: "My Favorite Place"), then hit Tab.
  5. Give your Placemark a description (eg: "Hello World!"), then hit Tab.
  6. Give your Placemark a style ID (eg: "style_favorites"), then hit Tab. Note that we have not created any Styles yet, but will do that below.
  7. This Placemark happens to be a simple point geometry, so give it a longitude (eg: "12.345"), then hit Tab, then give it a latitude (eg: "67.890"), then hit Tab one more time to finish editing the Placemark.
  8. Now, repeat the steps above to create another point placemark of your own choosing.
  9. Save your file so far, using the Save button, or Ctrl-S, or File (menu) > Save.
jEdit screenshot - Sample KML Placemarks

To see the list of all available abbreviations, go to Plugins (menu) > Plugin Options > SuperAbbrevs > Abbreviations, and set the Select Mode dropdown to "xml". You will see the list of KML abbreviations which you installed from the file we provided. You can edit them or add your own if you wish.

Use tag auto-completion to create content:

Since the abbreviations file we supplied to SuperAbbrevs contains only the most common KML tag structures and combinations, there are lots of other things we can do with KML by arranging our own tags, and tag auto-completion can be very useful for this. As an example, we'll add some Style tags to our file. There are numerous Style tag options in our SuperAbbrevs, but for this example we'll create one without using SuperAbbrevs.

  1. Find the first Placemark in your file (at or near line 6), make 3 or more empty lines above it, and move your cursor to the middle of the empty lines.
  2. Type an opening Style tag: "<Style id="style_favorites">", then Enter.
  3. Note that if you used a different style ID in your placemarks, then use that in the ID field instead. Also note that ErrorList will show an error, indicating that the </Style> tag is not closed. Ignore these errors for now, since we'll close the tags in a moment.
  4. On the next line type: "<IconStyle>", then Enter.
  5. On the next line type: "<Icon>", then Enter.
  6. On the next line type: "<href>", then enter the URL for an Icon file, such as: "http://maps.google.com/mapfiles/kml/shapes/cycling.png".
  7. Now type "</", and see that the closing </href> tag is auto-completed.
  8. Hit enter to go to the next line, type "</", and see that the closing </Icon> tag is auto-completed.
  9. Repeat typing "</" two more times to auto-complete the </IconStyle> and </Style> tags.
  10. All the errors in your ErrorList should now have disappeared since you correctly closed all the tags. If there are still errors, see if you can find a tag that is not closed correctly, is not capitalized correctly, or is in the wrong place or order.
  11. Save your file so far, using the Save button, or Ctrl-S, or File (menu) > Save.
jEdit screenshot - Sample KML Style

Use Indent XML to correct line indentations:

Look at the tags in the <Style...> section you created and see that they do not have the correct line-returns and indentation. It would be easy to use Enter (new line), Tab (indent) and Shift-Tab (un-indent) to correct these manually, but when you have a large KML or XML file that needs to have all its indentation corrected, there's an easier way.

  1. Go to Plugins (menu) > XML, and select Indent XML
  2. Notice that all the lines in your file are now automatically moved to their correct levels of indentation. Note also that the <atom> tags are wrapped into several lines.
jEdit screenshot - Sample KML Style, Indented

Use Error List to test your validation and error detection:

  1. Move your cursor to an empty line, just below your last </Placemark> tag, and above your closing </Document> tag.
  2. Type "<foo>" (no quotes).
  3. Look in the ErrorList box that appears at the bottom of your jEdit window. If it does not auto-expand, then click the ErrorList button to open it.
  4. Notice that one of the errors (ignore the other error for now) says:

    The element type "foo" must be terminated by the matching end-tag "</foo>"

jEdit screenshot - Sample KML error, ErrorList
  1. Ok, so let's correct that error... after your <foo> tag, type "</" and watch the closing </foo> tag auto-complete, giving you: <foo></foo>.
  2. Look in the ErrorList again, and see that the error noted above has disappeared since we successfully closed the tag.
  3. Look at the remaining error, which includes:

    ... Invalid content was found starting with element ‘foo'...

    This indicates that <foo> is not a valid tag in the KML schema
  4. Delete your <foo></foo> tags, and see that the error disappears.

Inspect your file structure using Sidekick:

  1. Your KML file should now look something like the file shown below.
  2. Click the Sidekick button on the left of the jEdit window to open the Sidekick pane docked on the left.
  3. Look at the basic DOM Tree structure of your KML (DOM = Document Object Model). You should see the top-level kml tag, with the single Document tag under it. The Document contains tags for its name, atom:author, atom:link, Style, and two Placemarks.
  4. Expand the Style tag structure by clicking the icon to the left of the Style tag in the Sidekick tree. The icon should rotate down and reveal the IconStyle tag. Do the same for IconStyle to reveal the Icon tag, and again to reveal the href tag.
  5. Expand one of the Placemark tags to show its sub-tags, including name, snippet, description, styleUrl, and Point. The Point tag can be expanded to show the coordinates tag.
  6. See the screenshot below for what the DOM Tree looks like in Sidekick. You can use it to quickly navigate the structure of complex and lengthy KML files. It allows you to understand the arrangement of your KML content, and to find errors in tag closing, structure, and other issues.

<?xml version="1.0" encoding="UTF-8"?>

<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/kml/2.2 http://schemas.opengis.net/kml/2.2.0/ogckml22.xsd http://www.google.com/kml/ext/2.2 https://developers.google.com/kml/schema/kml22gx.xsd http://www.w3.org/2005/Atom http://schemas.opengis.net/kml/2.2.0/atom-author-link.xsd">

  <Document id="kml_doc01">
    <name>My First Validated KML</name>
    <atom:author>
      <atom:name>A. Googler</atom:name>
    </atom:author>
    <atom:link href="http://www.google.com/earth/outreach/" />

    <Style id="style_favorites">
      <IconStyle>
        <Icon>
          <href>http://maps.google.com/mapfiles/kml/shapes/cycling.png</href>
        </Icon>
      </IconStyle>
    </Style>

    <Placemark id="point_01">
      <name>My Favorite Place</name>
      <snippet></snippet>
      <description><![CDATA[Hello World!]]></description>
      <styleUrl>#style_favorites</styleUrl>
      <Point>
        <coordinates>12.345,67.890,0</coordinates>
      </Point>
    </Placemark>

    <Placemark id="point_02">
      <name>Second Favorite Place</name>
      <snippet></snippet>
      <description><![CDATA[Hello Google Earth!]]></description>
      <styleUrl>#style_favorites</styleUrl>
      <Point>
        <coordinates>12.543,67.098,0</coordinates>
      </Point>
    </Placemark>

  </Document>

</kml>

jEdit screenshot - Sample KML Completed, Sidekick DOM Tree

Load your KML in Google Earth:

  1. Open Google Earth on your computer. If you don't have the latest version installed, you can download it at: www.google.com/earth/.
  2. Find the KML file you created in your computer's file browser (Windows Explorer, OSX Finder, etc.), and double-click to open it, or drag and drop it onto Google Earth.
  3. You should see the file open in Google Earth, and show the two points you created, with the cycle icons defined in your style.
Google Earth screenshot - sample KML from jEdit

I guess the random coordinate numbers we picked ended up in the water, so they aren't actually great places for cycling, but they work for this example. :-)

If your file doesn't look the same in Google Earth, then go back to your KML in jEdit and see if you can find the differences. For example, if the icons aren't showing up (if they are the default yellow pushpins), then maybe you didn't enter the contents of your <Style...> tags correctly, or maybe you didn't spell and capitalize the style IDs exactly the same way in your Style tag and in each of your Placemarks' <styleUrl> tags.



Strict KML Validation

The tools discussed above will validate KML very well, but they don't observe quite all of the obscure, minute details of the official KML specification, most of which are things that would not impact how your KML is displayed.

If you want to double-check your work and run a very strict validation, Glados has developed and published a free online tool where you can upload your KML (or point it to a URL), and get a detailed report of any KML schema errors, or other issues with your file.

You can find the Glados KML Validator here: www.kmlvalidator.com.



Other tools

For Windows users, another option for KML editing is a free software tool called Notepad++. You can find out more and download Notepad++ here: notepad-plus-plus.org.

To set up Notepad++ to interpret KML files as XML follow these steps:

  1. In Notepad++, click on the Settings menu and select Style Configurator.
  2. In the dialog box, find the Language: list and select XML.
  3. In the "User ext.:" box that appears, type "kml" to add it to the extensions.
  4. Click the Save & Close button to exit the dialog.

We suggest that you install the Notepad++ XML Tools plugin and turn on its Tag-auto-close functionality. XML Tools also has a useful option to organize and indent your KML, called: Pretty Print (XML only - with line breaks). Other useful Notepad++ plugins include TextFX, Compare, and HTML Tag.



Videos

The two videos below are from the previous version of this tutorial. Most of the information is still relevant, but some of the screens and procedures shown have changed. The instructions in the tutorial above are correct at the time of this writing (February 2013), but the videos are outdated.

Video: Setting up jEdit Plugins to Validate KML

The following video shows you how to set up jEdit plug-ins to work with XML files and how to properly reference the OGC KML 2.2 schema, so that your documents are validated as you type.


Video: Error checking KML with jEdit and using Super Abbreviations

The following video walks you through checking for errors in a sample KML file, including adding the necessary Schema Header to allow jEdit to detect schema errors. The two files used in the tutorial are linked below:




Discussion / Feedback

Have questions about this tutorial? Want to give us some feedback? Visit the Google Earth Outreach Discussion Group to discuss it with others.



What's Next?

Want to test out your new skills? Check out these other tutorials that require some hand-editing of KML: