Contents |
When creating KML or KMZ files you may encounter problems due to incorrect notations in the KML code. The KML Validator by Galdos Systems Inc. is a great web application to quickly check your KML code. Even when your KML files are functioning properly it's a good habit to validate them to check their compatibility, meaning their robustness to remain functioning over time.
On this page the usage of the KML Validator will be illustrated using the barcelona_bicycle_stations.kml created in the tutorial about the KML ImageOverlay tool.
The KML example file barcelona_bicycle_stations.kml currently contains the following code:
<?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://earth.google.com/kml/2.1"> <Folder><name>Ground Overlays</name>
<description>Examples of ground overlays</description>
<GroundOverlay> <Icon> <href> http://wiki.activeids.nl/uploads/gps/map_barcelona_bicycle_stations_M.png </href> </Icon> <LatLonBox><north>41.45945274113893</north>
<south>41.34464851702826</south>
<east>2.2364044189453125</east>
<west>2.0908355712890625</west>
</LatLonBox> </GroundOverlay> </Folder></kml>
KML is a type of XML file. Therefore before even checking if the KML code is valid you should check if your KML is in valid XML format. As W3Schools states "With XML, errors are not allowed." and "Errors in XML documents will stop your XML applications.". To check the code (syntax) use the W3Schools XML Validator by pasting the KML code or entering the URL and clicking validate. When elements are not closed correctly you will receive the warning:
"XML Parsing Error: not well-formed
[...] Line Number 17, Column 5".
When entire elements are missing you will receive the warning:
"XML Parsing Error: no element found
[...] Line Number 18, Column 1".
You will always only receive one error at a time as the validator stops at the fist error it encounters. Fix the error in the code line indicated in the warning message and validate again until all errors are solved and you receive the message:
"No errors found".
When your KML file is in valid XML format you can continue to valid the KML code.
In order to validate the code of this KML the file is loaded into the application on kmlvalidator.com. You can validate your own KML file there or enter it into the webpage loaded in the frame below:
Source: kmlvalidator.com
The validation of the KML file results in 2 errors, 0 recommendations and 0 suggestions. Errors mean the KML file is invalid. Recommendations and suggestions are meant for improving the quality and interoperability of the KML file. This however does not mean necessarily mean the KML file will not function for your purpose at this time. Still it is good practice to make your files as compatible as possible. For more information about the issue levels (error etc.) see the KML Validator Help.
The validation returns the following two errors:
Line 1 Error
This does not appear to be an OGC KML document--expected document element in namespace http://www.opengis.net/kml/2.2, but found: http://earth.google.com/kml/2.1
This relates to this OGC KML requirement: RootElement
Line 6 Error
Link element contains an invalid kml:href, could not parse as a URI.
This relates to this OGC KML requirement: LinkReferent
Note: During the validation line 2 in the code of the example above has been moved behind line 1. The error in line 1 therefore refers to line 2 in the example and the error in line 6 refers to line 7 in the example.
Above the error list KML Validator states "All errors must be fixed for the KML to be valid". So the next step is solving the code issues.
When you have relatively little experience with KML code in general the best approach to solving code issues is by starting with small files (few lines of code), trying to solve one issue at a time and working your way down from the top of the file. For solving KML code issues carefully read through the error messages and refer to the provided KML Validator Help pages. Additionally the Google KML Reference is a useful resource for background on the implementation of KML elements.
The first error stated by the KML Validator is an incorrect or unexpected namespace in the RootElement. The RootElement referred to is the <kml> element in line 2 of the example code:
<?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://earth.google.com/kml/2.1"> <Folder><name>Ground Overlays</name>
...
In the namespace the structure elements are defined and it's therefore very important to formulate this one correctly. KML Validator suggests using 'http://www.opengis.net/kml/2.2' instead of 'http://earth.google.com/kml/2.1'. To change the code you can open the KML file in any text editor (eg. Notepad++). Now simply replace the value of the 'xmlns' attribute to redefine the namespace:
<?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://www.opengis.net/kml/2.2"> <Folder><name>Ground Overlays</name>
...
When we now save the file (result: barcelona_bicycle_stations_v1.1.kml) and validate the adjusted KML file using KML Validator it returns only the error in line 6. It could however happen that both errors disappear simultaneously as one might be the result of the other. Therefore it's always good to check after each adjustment. If the issue is not solved or more issues are reported check your adjustments first before continuing.
The error that is still returned is the invalid usage of the <href> element in the <Icon> element on line 7 (which is line 6 after conversion through validation):
<?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://www.opengis.net/kml/2.2"> <Folder><name>Ground Overlays</name>
<description>Examples of ground overlays</description>
<GroundOverlay> <Icon> <href> http://wiki.activeids.nl/uploads/gps/map_barcelona_bicycle_stations_M.png </href> </Icon> <LatLonBox>...
In the error message KML Validator refers to the KML Validator Help page on LinkReferent in which in the case of an ImageOverlay (which is true for the example) is referred further to Icon-href. Here it states the image format must correspond to a registered image media type like PNG, JPEG or GIF. In the code above it is clear the image in the 'href' meets this requirement as it's in PNG format. As the solution doesn't appear to be written in the KML Validator Help pages we'll check the Google KML Reference next.
The Google KML Reference provides an example of how to use the <href> element under the section of the <Icon> element:
<Icon><href>Sunset.jpg</href>
</Icon>And a larger example under the <href> element section itself:
<?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://www.opengis.net/kml/2.2"><Document> <Style id="randomColorIcon"> <IconStyle><color>ff00ff00</color>
<colorMode>random</colorMode>
<scale>1.1</scale>
<Icon><href>http://maps.google.com/mapfiles/kml/pal3/icon21.png</href>
</Icon> </IconStyle> </Style> <Placemark><name>IconStyle.kml</name>
<styleUrl>#randomColorIcon</styleUrl>
<Point><coordinates>-122.36868,37.831145,0</coordinates>
</Point> </Placemark></Document></kml>
When these examples are compared with our example you might not see any difference at first. The address of the image file is formulated correctly, including the 'http://' prefix. However if we look really closely you will notice there is a single ' ' (space) before our URL and the </href> tag is on the next line. So to be sure we will adjust these small differences in our file (result: barcelona_bicycle_stations_v1.2.kml) and test it using KML Validator, which then returns the result:
Status: The KML file is valid and complies with best practices!
Again if you still receive errors or warnings check your adjustments. The problem could for instance also have been in the structure of the KML code. Notice that at first you might have seen in Google's code the <Document> element is used whereas in our example the <Folder> element is used. This was however not the issue as they are both meant to organize certain other elements (they both extend the <Container> element). Therefore it is generally a good way to start at the core of the issue and if you can't find the solution there expand your search. Constantly test your changes and possibly reverse them when it doesn't appear to solve your issue.
