Structure of YMapsML

YMapsML documents consist of elements belonging to five namespaces: http://maps.yandex.ru/ymaps/1.x, http://maps.yandex.ru/representation/1.x, http://www.opengis.net/gml, http://maps.yandex.ru/attribution/1.x and http://www.w3.org/2005/Atom. We will assume that the prefixes ymaps, repr, gml, attr and atom correspond to these namespaces, and we will be identifying the namespaces by their prefixes.

The table below shows the original namespaces:

Namespace Schema URL Definition
ymaps http://maps.yandex.ru/ymaps/1.x A language for representing geographical data in the form of abstract geographical objects and collections.
gml http://www.opengis.net/gml GML – the geography description standard.
repr http://maps.yandex.ru/representation/1.x Contains rules for displaying geographical objects on Yandex maps.
attr http://maps.yandex.ru/attribution/1.x Contains details on who provided information about an organization that is shown on Yandex maps.
atom http://www.w3.org/2005/Atom Atom is a syndication format for describing sets of web resources.

Each YMapsML element contains either one or more elements from the specified namespaces, or text, which in any case can include HTML code. HTML markup is always “shown on the screen”, meaning it is displayed as text in the browser. The exception is HTML code that is contained in the gml:description and repr:text elements located inside repr:Template. This code is interpreted by the browser and rendered as formatted text.

Let's look at the structure of a YMapsML document.

The root element of a document is the ymaps:ymaps element. It can contain attr:Attribution elements, one ymaps:GeoObjectCollection element and one repr:Representation element. Any of these elements may be omitted, or even all three may be omitted. The last case is a bit exotic. An “empty” document is usually used as a draft to be filled in later.

The top-level ymaps:GeoObjectCollection element is a container for all the geographical objects and their collections that are included in the document. The repr:Representation element is used for defining the visual appearance of these objects, as well as for setting map parameters. The attr:Attribution element contains details on who provided information about an organization that is shown on Yandex maps.

The YMapsML document that is provided as an example in the section YMapsML usage contains the ymaps:GeoObjectCollection element, but does not contain the repr:Representation element. This means that when displaying this document via the JavaScript API, the map display parameters and the visual appearance of geographical objects will be determined automatically.