Machine-readable Map Feature list/Archive
Data Model
The data model specifies the strcuture of a OsmTagDefinitionList. An OsmTagDefinitionList holds a list of OsmTagDefinitions (also called Map Features).
- For each OsmTagDefinition a key and a type must be defined. Typical examples for keys (from the currently defined Map Features): highway, building, maxheight. The type must be a OsmTagType. The most general type is string. It is the default type.
- For an OsmTagDefinition a list of localized display names and descriptions can be defined.
- A list of OsmLabelDefinitions can be assigend to a OsmTagDefinition. Each OsmLabelDefinition must have a value. Typical examples for values (from the currently defined Map Features): primary (for the tag highway), yes (for the tag building).
- For an OsmLabelDefinition a list of localized display names and descriptions can be defined. We use OsmLocalizedString for this purpose. We use ISO Language Codes and ISO Country Codes for defining the locale.
- Both an OsmTagDefinition and a OsmLabelDefinition are applicable for certain OSM primitives. We distinguish between the OSM primitive types node, way, relation and area. Strictly speaking, area is not an OSM primitive but a specialization of way. If nothing else is defined an OsmTagDefinition or an OsmLabelDefinition is applicable to all primitive types.
- For both an OsmTagDefinition and a OsmLabelDefinition a iconName can be defined. It can be used in interactive applications (editors, validators) in menu items, drop down lists, etc.
- We distinguish between the following OsmTagTypes:
- string - the most general type, an arbitray string
- boolean - a boolean value, either true or fale
Schema
The following listing shows a possible XML Schema for the proposed data model.
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/osm-tag-definition-list" xmlns:tns="http://www.example.org/osm-tag-definition-list" elementFormDefault="qualified">
<simpleType name = "OsmTagType">
<restriction base = "string">
<enumeration value = "string"/>
<enumeration value = "boolean"/>
</restriction>
</simpleType>
<complexType name="OsmTagDefinitionList">
<sequence>
<element name="osm-tag-definition" type="tns:OsmTagDefinition" minOccurs="0" maxOccurs="unbounded"></element>
</sequence>
<attribute name="version" type="string"></attribute>
</complexType>
<complexType name="OsmTagDefinition">
<sequence>
<element ref="tns:displayName" minOccurs="0"
maxOccurs="unbounded">
</element>
<element ref="tns:description" minOccurs="0"
maxOccurs="unbounded">
</element>
<element name="label" type="tns:OsmLabelDefinition" minOccurs="0"
maxOccurs="unbounded"></element>
</sequence>
<attribute name="key" type="string" use="required"></attribute>
<attribute name="iconName" type="string" use="optional"></attribute>
<attribute name="applicableForNode" type="boolean"
use="optional" default="true">
</attribute>
<attribute name="applicableForWay" type="boolean" use="optional"
default="true">
</attribute>
<attribute name="applicableForArea" type="boolean"
use="optional" default="true">
</attribute>
<attribute name="applicableForRelation" type="boolean"
use="optional" default="true">
</attribute>
<attribute name="type" type="tns:OsmTagType" use="optional"
default="string">
</attribute>
</complexType>
<complexType name="OsmLabelDefinition">
<sequence>
<element name="value" type="string" minOccurs="1"
maxOccurs="1">
</element>
<element ref="tns:displayName" minOccurs="0" maxOccurs="unbounded"></element>
<element ref="tns:description" minOccurs="0" maxOccurs="unbounded"></element>
</sequence>
<attribute name="iconName" type="string" use="optional"></attribute>
<attribute name="applicableForNode" type="boolean"
use="optional" default="true">
</attribute>
<attribute name="applicableForWay" type="boolean" use="optional"
default="true">
</attribute>
<attribute name="applicableForArea" type="boolean"
use="optional" default="true">
</attribute>
<attribute name="applicableForRelation" type="boolean"
use="optional" default="true">
</attribute>
</complexType>
<complexType name="OsmLocalizedString">
<simpleContent>
<extension base="string">
<attribute name="locale" type="string" use="optional" default="en"></attribute>
</extension>
</simpleContent>
</complexType>
<element name="displayName" type="tns:OsmLocalizedString"></element>
<element name="description" type="tns:OsmLocalizedString"></element>
<element name="osm-tag-definition-list" type="tns:OsmTagDefinitionList"></element>
</schema>
Sample
<?xml version="1.0" encoding="UTF-8"?>
<tns:osm-tag-definition-list xmlns:tns="http://www.example.org/osm-tag-definition-list" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.example.org/osm-tag-definition-list osm-tag-definition-list.xsd " version="1.0">
<!-- ************************************************************************ -->
<!-- Highway: sample for a tag with one defined label and localized strings -->
<!-- for two locales -->
<!-- ************************************************************************ -->
<tns:osm-tag-definition key="highway" iconName="highway.png">
<tns:displayName locale="en">Highway</tns:displayName>
<tns:displayName locale="de">Wege</tns:displayName>
<tns:description locale="en">The highway tag is the primary tag used for highways. It is often the only tag. There are conventions for its use in particular countries.</tns:description>
<tns:description locale="de">Der highway-Tag ist die hauptsächlich genutzte Art und Weise um Straßen zu kennzeichnen</tns:description>
<tns:label>
<tns:value>motorway</tns:value>
<tns:displayName locale="en">Motorway</tns:displayName>
<tns:displayName locale="de">Autobahn</tns:displayName>
<tns:description locale="en">A restricted access major divided highway, normally with 2 or more running lanes plus emergency hard shoulder. Equivalent to the Freeway, Autobahn, etc.. </tns:description>
<tns:description locale="de">Straße mit baulich getrennten Fahrtrichtungen (i. A. Grünstreifen) und besonderen Nutzungsbeschränkungen. Typischerweise zwei Fahrspuren je Fahrtrichtung oder mehr und ein Standstreifen.</tns:description>
</tns:label>
</tns:osm-tag-definition>
<!-- ************************************************************************ -->
<!-- building: sample for a tag of type boolean -->
<!-- ************************************************************************ -->
<tns:osm-tag-definition key="building" type="boolean">
</tns:osm-tag-definition>
</tns:osm-tag-definition-list>
Manage and harvest accepted features - Conventional approach
This proposal suggests
- to continue with the current practice of maintaing one wiki page per tag definition, value definition and - in the future - tag category
- to instantiate a suitable template in each of these pages. Harvesters will read this template instance and extract data for the machine-readable feature list from it
- to accept redundant data on the wiki. Harvesters will rely on the template instances in the individual pages. Wiki editors will have to make sure that this data is consistent with data in overview pages like Map Features.
We need three templates
- a template for TagDefinition (we should reuse the existing Template:KeyDescription) will be used to declare a tag on the Wiki (the equivalent of a tag-def in the machine-readable feature list)
- a template for ValueDefinition (we should reuse the existing Template:ValueDescription) will be used to declare a value definition on the Wiki (the equivalent of a value-def in the machine-readable feature list)
- Template:CategoryDefinition will be used to declare a category on the Wiki (the equivalent of a category in the machine-readable feature list)
This approach follows current practice. It only requires that two existing templates (Template:KeyDescription and Template:ValueDescription) be slightly modified and a third template be added. See Template talk:KeyDescription for a discussion on how to extend Template:KeyDescription for our needs.
For each tag with key key and each supported language language a wiki page <language>:Key:<key> is maintained. This page must include an instance of Template:TagDefinition and it must declare the category Category:<locale>:Keys.
This approach follows current practice. It only requires slight modifications in the existing Wiki pages.
For each value definition with key key and value value and each supported language language a wiki page <language>:Tag:<key>=<value> is maintained. This page must include an instance of Template:ValueDefinition and it must declare the category Category:<locale>:Tags. This approach follows current practice. It only requires slight modifications in the existing Wiki pages.
For each category with name category and each supported language language a wiki page <language>:TagCategory:<category> is maintained. We have to use TagCategory instead of Category because Category is already reserved by the Wiki. This page must include an instance of Template:CategoryDefinition and it must declare the category Category:<locale>:Categories. This is an extension of the current practice. The respective wiki pages would have to be created.
Finally, the category Category:MapFeatureContent refers to all Category:<locale>:Keys, Category:<locale>:Tags and Category:<locale>:Categories.
OSM contributors maintain the individual tag, value and category pages.
An automatic harvester starts with the category page Category:MapFeatureContent, visits the tag, value and category pages and extracts the required infos from the template instances in these pages.
Other proposals (to be reviewed)
We suggest to migrate the current Map Features to a new Map Features list which uses new templates for this purpose, in particular the three templates described below:
Similar templates are already in use in Proposed_features.
This is a sample page for a cleaned up Map Feature list using these templates.
In addition the Template:KeyDescription and Template:ValueDescription should be expanded and used to harvest the Tag informations. This allows the harvester to get informations about Tags that are not on the Map Feature list. (for example Deprecated, Proposed Tags). This also allows people to add informations about their Tags in sue without the need to vote something. Good for special tags that don't appear often in the OSM Database but are present and useful.