Crafting YAML for selecting features from the Export Tool
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"
buildings
, types
, select
are examples of keys in mappings.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.
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.
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.
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.
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.
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.