Vespucci Preset System#
Documentation for Vespucci 20.2
As explained in the help documentation Vespucci uses JOSM compatible presets, currently any preset used in JOSM should simply work with Vespucci, however there can be differences. Particularly with the new preset driven tagging interface presets have become even more important and if you are writing presets yourself and want them to work well in Vespucci please keep on reading.
Preset-Driven Tag-Editing in Vespucci#
For the preset based editing to work Vespucci has to match the existing tags, including incomplete, key-only ones with the available presets. This is done in an iterative fashion: the best matching preset is found (weighting presets with fixed key-value tuples higher than such with variable values), then all tags that can be found in linked presets are added (no separate header displayed) and this process is repeated until their are either no tags left or no preset match can be found.
Supported JOSM Preset Elements and Attributes#
Note: this is loosely based on what JOSM claims that works, this may be, and likely is, different from the actual implementation. Language specific attributes are ignored (see Translation). "supported" doesn't necessarily imply the same behaviour as JOSM, simply that Vespucci will do something useful with the value. Icons currently can be in PNG or SVG format.
| Element | Attributes | Support | Notes |
|---|---|---|---|
| <presets> | |||
| author | ignored | ||
| version | supported | ||
| description | partial | ||
| shortdescription | supported | ||
| link | ignored | ||
| icon | ignored | ||
| baselanguage | ignored | ||
| object_keys | extension | comma separated list of top-level keys | |
| <!-- comment --> | ignored | ||
| <group> | supported | ||
| name | supported | required | |
| name_context | supported | ||
| icon | supported | you really should add one for Vespucci | |
| items_sort | extension | sort the items alphabetically, default "yes" | |
| regions | extension | comma separated list of countries this preset group is applicable for | |
| exclude_regions | extension | if true, invert the meaning of regions | |
| <item> | supported | ||
| name | supported | required | |
| name_context | supported | ||
| icon | supported | you really should add one for Vespucci | |
| type | supported | extension: "area" is supported as a replacement for "multipolygon" and matches closed ways with an area=yes tag besides multipolygons | |
| name_template | supported | if set will always be used | |
| name_template_filter | ignored | ||
| preset_name_label | ignored | ||
| match_expression | supported | ||
| deprecated | extension | only use the preset for matching and map icon display | |
| regions | extension | comma separated list of countries this preset item is applicable for | |
| exclude_regions | extension | if true, invert the meaning of regions | |
| autoapply | extension | if true (default), allow auto-applying of the item | |
| min_match | extension | an integer indicating the minimum number of fixed tags that need to match (default is all fixed tags) | |
| <chunk> | supported | chunks can either contain complete fields just as items can, or a sequence of list_entry elements | |
| id | supported | required | |
| <reference> | supported | ||
| ref | supported | required | |
| <key> | supported | ||
| value | supported | required | |
| match | partial | "none" is supported | |
| match_expression | extension | ||
| text | extension | Something to display | |
| values_context | extension | Translation context | |
| object | extension | If present and true or false the tag will be considered as defining/not-defining a top level object, overriding the normal rules | |
| regions | extension | comma separated list of countries this preset group is applicable for | |
| exclude_regions | extension | if true, invert the meaning of regions | |
| <text> | supported | ||
| key | supported | required | |
| text | supported | ||
| match | partial | only the "key", "key!" and "none" values are supported, all other values are ignored | |
| match_expression | extension | ||
| default | supported | ||
| use_last_as_default | partial | "force" has the same effect as "true" | |
| auto_increment | ignored | ||
| length | partial | depending on the settings a modal will be displayed for editing instead of an inline text field | |
| alternative_autocomplete_keys | ignored | ||
| value_template | ignored | ||
| javascript | extension | if value is not set, execute the JS script | |
| i18n | extension | if set to true this tag has i18n variants | |
| value_type | extension | indicate the kind of value this tag should have | |
| regions | supported | comma separated list of countries this preset group is applicable for | |
| exclude_regions | supported | if true, invert the meaning of regions | |
| <combo> | supported | combo elements can contain a sequence of list_entry elements, or references to chunks that contain the same | |
| key | supported | required | |
| text | supported | ||
| text_context | supported | ||
| values | supported | ||
| values_sort | supported | ||
| delimiter | supported | ||
| default | supported | ||
| match | supported | ||
| match_expression | extension | ||
| display_values | supported | ||
| short_descriptions | partial | will only be used if display_values is not present | |
| values_context | supported | ||
| editable | supported | default is "false" | |
| use_last_as_default | partial | "force" has the same effect as "true" | |
| values_searchable | supported | subtype values are added regardless of the setting | |
| length | ignored | ||
| values_no_i18n | ignored | ||
| values_from | supported | extension: if the target method supports a String argument the current key will be passed | |
| regions | supported | comma separated list of countries this preset group is applicable for | |
| exclude_regions | supported | if true, invert the meaning of regions | |
| <multiselect> | supported | multiselect elements can contain a sequence of list_entry elements, or references to chunks that contain the same | |
| key | supported | required | |
| text | supported | ||
| text_context | supported | ||
| values | supported | ||
| values_sort | supported | ||
| delimiter | supported | ||
| default | supported | ||
| match | supported | ||
| match_expression | extension | ||
| display_values | supported | ||
| short_descriptions | partial | will only be used if display_values is not present | |
| values_context | supported | ||
| editable | supported | default is "false" | |
| use_last_as_default | partial | "force" has the same effect as "true" | |
| values_searchable | supported | subtype values are added regardless of the setting | |
| length | ignored | ||
| values_no_i18n | ignored | ||
| values_from | supported | extension: if the target method supports a String argument the current key will be passed | |
| rows | ignored | ||
| value_count_key | extension | reference to a tag that will hold the number of values this multiselect should contain | |
| regions | supported | comma separated list of countries this preset group is applicable for | |
| exclude_regions | supported | if true, invert the meaning of regions | |
| <list_entry> | supported | ||
| value | supported | required | |
| display_value | supported | ||
| short_description | supported | ||
| icon | supported | ||
| icon_size | ignored | ||
| image | extension | ||
| regions | supported | comma separated list of countries this preset group is applicable for | |
| exclude_regions | supported | if true, invert the meaning of regions | |
| <checkgroup> | supported | ||
| columns | ignored | ||
| text | extension | ||
| text_context | extension | ||
| regions | supported | comma separated list of countries this preset group is applicable for | |
| exclude_regions | supported | if true, invert the meaning of regions | |
| <check> | supported | ||
| key | supported | required | |
| text | supported | ||
| text_context | supported | ||
| value_on | supported | ||
| value_off | supported | ||
| disable_off | supported | ||
| default | supported | ||
| match | supported | ||
| match_expression | extension | ||
| use_last_as_default | extension | "force" has the same effect as "true" | |
| regions | supported | comma separated list of countries this preset group is applicable for | |
| exclude_regions | supported | if true, invert the meaning of regions | |
| <label> | supported | ||
| regions | extension | comma separated list of countries this preset group is applicable for | |
| exclude_regions | extension | if true, invert the meaning of regions | |
| <space/> | supported | suppressed immediately after a header or after another space element | |
| regions | extension | comma separated list of countries this preset group is applicable for | |
| exclude_regions | extension | if true, invert the meaning of regions | |
| <optional> | supported | contained fields are not displayed the in "Properties" tab when a preset is applied except if applying with optional fields is used, further matching ignores any optional fields | |
| text | supported | ||
| <separator/> | supported | starts a new row in the preset selection display | |
| <item_separator/> | supported | ||
| regions | extension | comma separated list of countries this preset group is applicable for | |
| exclude_regions | extension | if true, invert the meaning of regions | |
| <link> | supported | not legal inside <chunk> elements | |
| href | supported | including language specific variants | |
| wiki | supported | this will be used with lower preference than href entries | |
| <roles> | ignored | but not the included <role> elements | |
| <role> | supported | ||
| key | supported | required | |
| text | supported | ||
| text_context | supported | ||
| requisite | ignored | ||
| count | ignored | ||
| type | supported | ||
| member_expression | supported | See search language documentation | |
| regexp | ignored | ||
| regions | extension | comma separated list of countries this preset group is applicable for | |
| exclude_regions | extension | if true, invert the meaning of regions | |
| <preset_link> | supported | Used for tag matching and added to preset MRU list for easy access | |
| text | ignored | ||
| text_context | ignored | ||
| alternative | extension | If "true", the linked to preset is an alternative tagging for the object in question |
Name templates#
The Vespucci name templates differ slightly from the JOSM implementation, in particular nested quotes need to be escaped, however any template that works with Vespucci should work with JOSM.
Translation #
While the preset specification includes language specific text by prefixing the keys with the two letter ISO code, for example de.text, in practical terms this doesn't really work. Particularly if lots of languages are in use, the preset file itself would explode in size, become essentially illegible and force the application to parse many 100's if not 1000's of attributes for languages it is not interested in.
For Vespucci I've chosen a different approach based on GNU gettext format files, the simple Preset2Pot utility will generate a .pot file from a preset which you can use with one of the translation services to produce GNU gettext compatible translations of all the strings in the preset (excluding the actual key and value strings).
Extensions#
- deprecated only use this preset for matching, do not offer it for new use and do not find it when searched, it will work analogous for deprecated tags and values.
- javascript execute the script if the value of this tag is empty, the script has access to and can modify the current tags and use the specified default value if any.
- i18n the tag can have i18n variants, for example name and name:de.
- object_keys comma separated list of top level keys, examples would be highway, amenity etc., use this if your preset is introducing new such keys, see the Christmas preset for an example.
- object on fixed value tags. If present and true or false the tag will be considered as defining/not-defining a top level object, overriding the normal rules (see above).
-
value_type type of the value. This avoids having to hardcode such properties in applications, see the Christmas preset for an example.
- opening_hours a normal opening hours syntax tag
- opening_hours_mixed a tag with both text values and opening hours, examples: fee, supervised and lit
conditional conditional access tag- integer a integer numeric value
- website an URL for a website
- phone a phone number
- wikipedia a wikipedia page
- wikidata a wikidata Q ref
- speed a speed value (reserved)
-
items_sort this controls sorting of items in groups, the default is "yes", any other value will disable sorting, the sorting preserves structure. Note: the preset root groups are currently not sortable.
- regions comma separated list of countries this preset group or item is applicable for. Note that from JOSM 18918 on the only difference is that we support the region related tags on combo, multiselect (and not just the values), and the formatting tags.
- exclude_regions if true, invert the meaning of regions. See above for details.
- autoapply if true (default), allow auto-applying of the item.
- min_match modifies Vespuccis matching algorithm to use the specified number of fixed tag matches instead of expecting all to match.
- value_count_key reference to a tag that will hold the number of values this multiselect should contain. Example for the destination:lanes tag this would be value_count_key="lanes".
- alternative indicates that the preset_link points to an alternative tagging of the object.
- image optional reference to a large image in an list_entry. See Bicycle parking preset for an example of using this tag.
- match_expression on text, combo, multiselect and check elements. Note that having a field with the same key multiple times in an item leads to undefined behaviour.