docs/customize/Import-Styles.md

   1 ## Configuring the Import
   2
   3 Which OSM objects are added to the database and which of the tags are used
   4 can be configured via the import style configuration file. This
   5 is a JSON file which contains a list of rules which are matched against every
   6 tag of every object and then assign the tag its specific role.
   7
   8 The style to use is given by the `NOMINATIM_IMPORT_STYLE` configuration
   9 option. There are a number of default styles, which are explained in detail
  10 in the [Import section](../admin/Import.md#filtering-imported-data). These
  11 standard styles may be referenced by their name.
  12
  13 You can also create your own custom style. Put the style file into your
  14 project directory and then set `NOMINATIM_IMPORT_STYLE` to the name of the file.
  15 It is always recommended to start with one of the standard styles and customize
  16 those. You find the standard styles under the name `import-<stylename>.style`
  17 in the standard Nominatim configuration path (usually `/etc/nominatim` or
  18 `/usr/local/etc/nominatim`).
  19
  20 The remainder of the page describes the format of the file.
  21
  22 ### Configuration Rules
  23
  24 A single rule looks like this:
  25
  26 ```json
  27 {
  28     "keys" : ["key1", "key2", ...],
  29     "values" : {
  30         "value1" : "prop",
  31         "value2" : "prop1,prop2"
  32     }
  33 }
  34 ```
  35
  36 A rule first defines a list of keys to apply the rule to. This is always a list
  37 of strings. The string may have four forms. An empty string matches against
  38 any key. A string that ends in an asterisk `*` is a prefix match and accordingly
  39 matches against any key that starts with the given string (minus the `*`). A
  40 suffix match can be defined similarly with a string that starts with a `*`. Any
  41 other string constitutes an exact match.
  42
  43 The second part of the rules defines a list of values and the properties that
  44 apply to a successful match. Value strings may be either empty, which
  45 means that they match any value, or describe an exact match. Prefix
  46 or suffix matching of values is not possible.
  47
  48 For a rule to match, it has to find a valid combination of keys and values. The
  49 resulting property is that of the matched values.
  50
  51 The rules in a configuration file are processed sequentially and the first
  52 match for each tag wins.
  53
  54 A rule where key and value are the empty string is special. This defines the
  55 fallback when none of the rules match. The fallback is always used as a last
  56 resort when nothing else matches, no matter where the rule appears in the file.
  57 Defining multiple fallback rules is not allowed. What happens in this case,
  58 is undefined.
  59
  60 ### Tag Properties
  61
  62 One or more of the following properties may be given for each tag:
  63
  64 * `main`
  65
  66     A principal tag. A new row will be added for the object with key and value
  67     as `class` and `type`.
  68
  69 * `with_name`
  70
  71     When the tag is a principal tag (`main` property set): only really add a new
  72     row, if there is any name tag found (a reference tag is not sufficient, see
  73     below).
  74
  75 * `with_name_key`
  76
  77     When the tag is a principal tag (`main` property set): only really add a new
  78     row, if there is also a name tag that matches the key of the principal tag.
  79     For example, if the main tag is `bridge=yes`, then it will only be added as
  80     an extra row, if there is a tag `bridge:name[:XXX]` for the same object.
  81     If this property is set, all other names that are not domain-specific are
  82     ignored.
  83
  84 * `fallback`
  85
  86     When the tag is a principal tag (`main` property set): only really add a new
  87     row, when no other principal tags for this object have been found. Only one
  88     fallback tag can win for an object.
  89
  90 * `operator`
  91
  92     When the tag is a principal tag (`main` property set): also include the
  93     `operator` tag in the list of names. This is a special construct for an
  94     out-dated tagging practise in OSM. Fuel stations and chain restaurants
  95     in particular used to have the name of the chain tagged as `operator`.
  96     These days the chain can be more commonly found in the `brand` tag but
  97     there is still enough old data around to warrant this special case.
  98
  99 * `name`
 100
 101     Add tag to the list of names.
 102
 103 * `ref`
 104
 105     Add tag to the list of names as a reference. At the moment this only means
 106     that the object is not considered to be named for `with_name`.
 107
 108 * `address`
 109
 110     Add tag to the list of address tags. If the tag starts with `addr:` or
 111     `is_in:`, then this prefix is cut off before adding it to the list.
 112
 113 * `postcode`
 114
 115     Add the value as a postcode to the address tags. If multiple tags are
 116     candidate for postcodes, one wins out and the others are dropped.
 117
 118 * `country`
 119
 120     Add the value as a country code to the address tags. The value must be a
 121     two letter country code, otherwise it is ignored. If there are multiple
 122     tags that match, then one wins out and the others are dropped.
 123
 124 * `house`
 125
 126     If no principle tags can be found for the object, still add the object with
 127     `class`=`place` and `type`=`house`. Use this for address nodes that have no
 128     other function.
 129
 130 * `interpolation`
 131
 132     Add this object as an address interpolation (appears as `class`=`place` and
 133     `type`=`houses` in the database).
 134
 135 * `extra`
 136
 137     Add tag to the list of extra tags.
 138
 139 * `skip`
 140
 141     Skip the tag completely. Useful when a custom default fallback is defined
 142     or to define exceptions to rules.
 143
 144 A rule can define as many of these properties for one match as it likes. For
 145 example, if the property is `"main,extra"` then the tag will open a new row
 146 but also have the tag appear in the list of extra tags.
 147
 148 ### Changing the Style of Existing Databases
 149
 150 There is normally no issue changing the style of a database that is already
 151 imported and now kept up-to-date with change files. Just be aware that any
 152 change in the style applies to updates only. If you want to change the data
 153 that is already in the database, then a reimport is necessary.