YAML Specification

Crafting YAML for selecting features from the Export Tool

Overview

YAML Feature Selections define how OSM is transformed into other formats, such as Shapefile, SQLite/Geopackage and KML. Many of these formats are tabular, so we need to define a set of columns to fill with OSM data. This feature selection format is similar to style files used by programs such as osm2pgsql and imposm.

A basic complete example of a feature selection with 3 themes:

buildings:
            types:
              - polygons
            select:
              - name
              - building
            where: building IS NOT NULL
          waterways:
            types:
              - lines
              - polygons
            select:
              - name
              - waterway
            where: natural IN ('waterway')
          hospitals:
            select:
              - name
              - amenity
            where: amenity = "hospital"

The YAML format:

  • Is whitespace sensitive. Each child element must be indented below its parent element.
  • Has two data structures: lists and mappings. In the above example, buildings, types, select are examples of keys in mappings.
  • the child elements of select and types are lists. List elements are preceded by a dash. This dash must have a space after it.

For more information about the YAML format, see the YAML specification.

Themes

buildings, waterways and hospitals are examples of themes. In formats that have layers/tables, one theme will be mapped to one table.

Themes are always be the top level keys of the YAML document. Valid characters for themes are letters, numbers and underscores.

Geometry Types

the list values under types can be one or more of - points, - lines, - polygons. if the types key is omitted, all 3 geometry types will be included in the theme.

Column selections

List items under the select key determine the columns for each theme.

select:
            - name
            - amenity

Will populate the name and amenity columns with their values from OSM.

Resources for finding information on OSM tagging conventions:

Filters

Filters are under the where: key in each theme. They define what subset of OSM features belongs to that theme.

where: natural IN ('waterway')

Will filter the theme to only features where the key natural has the value waterway. It is almost always necessary to have some kind of filtering, otherwise your theme will simply include all OSM features for the given geometry types. You can specify a filter using SQL-like syntax. valid SQL keywords are IS NOT NULL, AND, OR, IN, =, !=.

Other examples of filters:

where: 
- natural = 'waterway'
- 'addr:housenumber' IS NOT NULL
- natural IN ('waterway','riverbank')
If the value of 'where' is a list, the effect is that all clauses are 'OR'ed together - a feature will match if any SQL clause is true. This is meant to help make the YAML tidier.

Converting from JOSM Presets

Older versions of the OSM Export Tool used JOSM Preset .XML files to define feature selections. The new YAML format is more flexible in how it transforms OSM data.

If you have an existing XML Preset, you can automatically convert it to YAML via the "Load from JOSM Preset .XML" Button. If your Preset is more complex, you may need to write a new YAML based on the "item" elements contained in the XML.