Machine-readable Map Feature list

From OpenStreetMap Wiki
Jump to: navigation, search

Contents

Aim

Generate a list of Map features that can be used for further usage in other programs. See the dev mailinglist

curent usage of such a list:

Use cases

Interactive Applications (editors, validators, etc.)


Could be used in: JOSM, Potlatch

Others

Where can this list be useful?

File format

The file format is documented reusing the approach for the API v0.5.

Basic elements

localized descriptions and display names

display-name declares a localized display name of an object. description declares a localized description of an object. value-summary declares a localized summary of tag values

We use the xml:lang attribute to specifiy the language used. 

<!ELEMENT description (#PCDATA)>
<!ATTLIST description  xml:lang  NMTOKEN #IMPLIED>

<!ELEMENT display-name (#PCDATA)>
<!ATTLIST display-name  xml:lang  NMTOKEN #IMPLIED>

<!ELEMENT value-summary (#PCDATA)>
<!ATTLIST value-summary xml:lang  NMTOKEN #IMPLIED>

map feature list (map-feature-list)

map-feature-list is the root element of the machine-readable map features list

It consists of tag-defs, categories and presets. 


<!ELEMENT map-feature-list     ((tag-def|category|preset)*)>
<!ATTLIST map-feature-list  version      CDATA #REQUIRED>
<!ATTLIST map-feature-list  release-id   CDATA #REQUIRED>
<!ATTLIST map-feature-list  release-date CDATA #REQUIRED>
<!ATTLIST map-feature-list  xml:lang     NMTOKEN  "en">

tag definitions (tag-def)

tag-defs are definitions of tags. They are called tag definitions instead of tags because tag is reserved in API v0.5 for a specific key/value pair of an OSM primitive.

A tag-def defines


A tag-def can declare a list of suggested, predefined values for the tag, which we call value definitions or value-defs. 

<!ELEMENT tag-def              ((display-name|description|value-def|category|value-summary)*)>
<!ATTLIST tag-def key          CDATA #REQUIRED>
<!ATTLIST tag-def onnode       (yes|no)  "no">
<!ATTLIST tag-def onway        (yes|no)  "no">
<!ATTLIST tag-def onarea       (yes|no)  "no">
<!ATTLIST tag-def onrelation   (yes|no)  "no">
<!ATTLIST tag-def state        (draft|voting|proposed|accepted|rejected|deprecated) "accepted">

value definitions (value-def)

value-defs are suggested, predefined values for tags. Value definitions are also called labels.

A value-def defines 

<!ELEMENT value-def              ((display-name|description)*)>
<!ATTLIST value-def value         CDATA #REQUIRED>
<!ATTLIST value-def onnode       (yes | no)  "no">
<!ATTLIST value-def onway        (yes | no)  "no">
<!ATTLIST value-def onarea       (yes | no)  "no">
<!ATTLIST value-def onrelation   (yes | no)  "no">
<!ATTLIST value-def state        (draft|voting|proposed|accepted|rejected|deprecated)  "accepted">

categories (category)

A category groups a set of tag definitions.

A category defines 

<!ELEMENT category              ((display-name|description)*)>
<!ATTLIST category  name        ID #IMPLIED>
<!ATTLIST category  ref         IDREF #IMPLIED>
<!ATTLIST category  icon        CDATA "">

cat-ref is used to link a tag-def to a category. 

   <!-- refers to a category with name physiscal defined elsewhere in the file -->
   <category ref="physical">

preset

A preset is a partially defined set of tags (key/value-pairs). Interactive applications use presets to tag certain map objects with consistent set of tags. presets are transient. In contrast not nodes, ways and relations they are not stored in the OSM database. They are supposed to assist users in applying "correct" tags for specific real-world objects.

presets are therefore mainly useful for interactive applications (aka editors). To offline data validation tools information about used presets is not available.


A preset can

A preset defines 

<!ELEMENT implies                EMPTY>
<!ATTLIST implies   key          CDATA #REQUIRED>
<!ATTLIST implies   value        CDATA #REQUIRED>

<!ELEMENT requires                EMPTY>
<!ATTLIST requires   key          CDATA #REQUIRED>
 
<!ELEMENT suggests                EMPTY>
<!ATTLIST suggests   key           CDATA #REQUIRED>

<!ELEMENT preset   ((implies|requires|suggests|display-name|description)*)>
<!ATTLIST preset   name          NMTOKEN #REQUIRED>

Full DTD

The current version of the DTD is available from the SVN repository. 

<!ELEMENT map-feature-list     ((tag-def|category|preset)*)>
<!ATTLIST map-feature-list  version      CDATA #REQUIRED>
<!ATTLIST map-feature-list  release-id   CDATA #REQUIRED>
<!ATTLIST map-feature-list  release-date CDATA #REQUIRED>
<!ATTLIST map-feature-list  xml:lang     NMTOKEN  "en">

<!ELEMENT description (#PCDATA)>
<!ATTLIST description  xml:lang  NMTOKEN #IMPLIED>

<!ELEMENT display-name (#PCDATA)>
<!ATTLIST display-name  xml:lang  NMTOKEN #IMPLIED>

<!ELEMENT value-summary (#PCDATA)>
<!ATTLIST value-summary xml:lang  NMTOKEN #IMPLIED>


<!ELEMENT tag-def              ((display-name|description|value-def|category|value-summary)*)>
<!ATTLIST tag-def key          CDATA #REQUIRED>
<!ATTLIST tag-def onnode       (yes|no)  "no">
<!ATTLIST tag-def onway        (yes|no)  "no">
<!ATTLIST tag-def onarea       (yes|no)  "no">
<!ATTLIST tag-def onrelation   (yes|no)  "no">
<!ATTLIST tag-def state        (draft|voting|proposed|accepted|rejected|deprecated)  "accepted">


<!ELEMENT value-def              ((display-name|description)*)>
<!ATTLIST value-def value         CDATA #REQUIRED>
<!ATTLIST value-def onnode       (yes | no)  "no">
<!ATTLIST value-def onway        (yes | no)  "no">
<!ATTLIST value-def onarea       (yes | no)  "no">
<!ATTLIST value-def onrelation   (yes | no)  "no">
<!ATTLIST value-def state        (draft|voting|proposed|accepted|rejected|deprecated)  "accepted">


<!ELEMENT category              ((display-name|description)*)>
<!ATTLIST category  name        ID #IMPLIED>
<!ATTLIST category  ref         IDREF #IMPLIED>


<!ELEMENT implies                EMPTY>
<!ATTLIST implies   key          CDATA #REQUIRED>
<!ATTLIST implies   value        CDATA #REQUIRED>

<!ELEMENT requires                EMPTY>
<!ATTLIST requires   key          CDATA #REQUIRED>
 
<!ELEMENT suggests                EMPTY>
<!ATTLIST suggests   key           CDATA #REQUIRED>

<!ELEMENT preset   ((implies|requires|suggests|display-name|description)*)>
<!ATTLIST preset   name          NMTOKEN #REQUIRED>

Examples

Example 1 - 3 tag definitions, 3 categories, not localized, no images, no presets 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE osm-tag-def-list SYSTEM "osm-tag-definition-list.dtd" >
 
<osm-tag-def-list release-date="2008-12-20" release-id="00001" version="0.1">
 
 
<tag-def key="highway" onnode="yes" onway="yes" onarea="yes">
	<display-name>Highway</display-name>
	<description>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.</description>
 
	<value-def value="motorway" onway="yes">
		<display-name>Motorway</display-name>
		<description>A restricted access major divided highway, normally with 2 or more running lanes plus emergency hard shoulder. Equivalent to the Freeway, Autobahn, etc.. </description>		
	</value-def>
 
	<value-def value="motorway_link" onway="yes">
		<display-name>Motorway Link</display-name>
		<description>The link roads (sliproads/ramps) leading to/from a motorway from/to a motorway or lower class highway. Normally with the same motorway restrictions. </description>		
	</value-def>
 
	<value-def value="pedestrian" onway="yes" onarea="yes">
		<display-name>Pedestrian</display-name>
		<description>For roads used mainly/exclusively for pedestrians/shopping areas. Also for tagging squares and plazas (in which case, add area=yes.</description>		
	</value-def>
 
	<value-def value="bus_stop" onnode="yes">
		<display-name>Bus Stop</display-name>
		<description>A small bus stop. Larger stations should be tagged as amenity=bus_station instead. </description>		
	</value-def>
	<category ref="physical" />
</tag-def>
 
 
<tag-def key="operator" onnode="yes" onway="yes" onarea="yes">
	<display-name>Operator</display-name>
	<description>The operator tag can be used to name a company or corporation who's responsible for a certain object or who operates it.</description>		
 
	<category ref="naming"/>
	<category ref="non-physical"/>
</tag-def>
 
 
<tag-def key="name" onnode="yes" onway="yes" onarea="yes">
	<display-name>Name</display-name>
	<description>The common default name. (Note: For disputed areas, please use the name as displayed on e.g. street signs for the name tag. Put all alternatives into either localized name tags (e.g. name:tr/name:el) or the variants (e.g. loc_name/old_name/alt_name). Thank you.) </description>		
 
	<category ref="naming"/>
</tag-def>
 
 
<category name="physical">
	<display-name>Physical</display-name>	
</category>
 
<category name="non-physical">
	<display-name>Non-Physical</display-name>	
</category>
 
<category name="naming">
	<display-name>Naming</display-name>	
</category>
 
 
 
</osm-tag-def-list>

Maintaining map features on the OSM wiki

Tags have to be defined on the Wiki in a way that they

Where tag definitions are maintained today

Today, tag definitions are maintained in several places on the Wiki:

Examples: Key:highway
Template:KeyDescription declares a subset of the data we need for tag-def. Shortcomings:
  • no data about a localized display name
  • no data about whether the key is applicable to a relation
  • can refer to one group (we call them category) only
  • no data about the status in the life cycle
Examples: Tag:highway=motorway
Template:ValueDescription declares a subset of the data we need for value-def. Shortcomings:
  • no data about a localized display name
  • no data about whether the key is applicable to a relation


Using Semantic MediaWiki in the future

An upgrade of the OSM wiki to the Semantic MediaWiki (SMW) could help to reduce redundant definitions of tags and values, see talk mailing list. The idea has been discussed extensively on the discussion page. The discussion led to a propsoal for a new structure of the OSM wiki regarding pages, which include content about map features.

Basic concepts

See subarticle OWL, Semantic MediaWiki and more

Classes

We have four classes (in OWL terminology). Naming conventions follow those used in OWL, i.e.:

Some of the properties have multiplicity 1, others 0..1 and other *. It is not possible to restrict multiplicity in SMW. It seems that multiplicity is always *: just repeat a property declaration with another value in order to assign multiple values to it. For clarity, the intended multiplicity of the properties is given below in [..].


KeyDef

An individual of KeyDef describes a key used in OSM for tagging a map element.
Semantic Properties:
Name Multiplicity Type Description
key 1 (mandatory) String the defined key, i.e. highway or access
displayName * String an localized display name for the key. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized display names for multiple languages are maintained.
description * String an localized description for the key. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized description for multiple languages are maintained.
onNode 0..1 (optional) Boolean whether this key is applicable to nodes or not. If missing, false is assumed.
onWay 0..1 (optional) Boolean whether this key is applicable to ways or not. If missing, false is assumed.
onArea 0..1 (optional) Boolean whether this key is applicable to areas or not. If missing, false is assumed.
onRelation 0..1 (optional) Boolean whether this key is applicable to relations or not. If missing, false is assumed.
state 0..1 (optional) String either draft, voting, proposed, accepted,rejected, or deprecated; if missing, accepted is assumed.
lang 1 (mandatory) String the language of language dependent properties like displayName or description.
photo 0..1 (optional) Page the value of photo refers to an image with a photo of a typical real-world situation where an OSM map feature can be used.
rendering 0..1 (optional) Page The value of rendering refers to a sample rendering of a map feature on a map
group * Page holds the name of a group this KeyDef belongs to.
implies * Page refers to another map feature which is implied by this KeyDef. Example values are Key:highway (referring to another KeyDef) or Tag:highway/primary (referring to another ValueDef)
requires * Page refers to another map feature which is required by this KeyDef. Example values are Key:name (referring to another KeyDef) or Tag:access/no (referring to another ValueDef)
suggests * Page refers to another map feature which is suggested to be used together with this KeyDef. Example values are Key:name (referring to another KeyDef) or Tag:access/no (referring to another ValueDef)

ValueDef

An individual of ValueDef is a Name/Value-Pair used in OSM for tagging a map element.
Semantic Properties:
Name Multiplicity Type Description
key 1 (mandatory) String the defined key, i.e. highway or access
key 1 (mandatory) String the defined value, i.e. primary or yes
displayName * String an localized display name for the key. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized display names for multiple languages are maintained.
description * String an localized description for the key. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized description for multiple languages are maintained.
onNode 0..1 (optional) Boolean whether this key is applicable to nodes or not. If missing, false is assumed.
onWay 0..1 (optional) Boolean whether this key is applicable to ways or not. If missing, false is assumed.
onArea 0..1 (optional) Boolean whether this key is applicable to areas or not. If missing, false is assumed.
onRelation 0..1 (optional) Boolean whether this key is applicable to relations or not. If missing, false is assumed.
state 0..1 (optional) String either draft, voting, proposed, accepted,rejected, or deprecated; if missing, accepted is assumed.
lang 1 (mandatory) String the language of language dependent properties like displayName or description.
photo 0..1 (optional) Page the value of photo refers to an image with a photo of a typical real-world situation where an OSM map feature can be used.
rendering 0..1 (optional) Page The value of rendering refers to a sample rendering of a map feature on a map
group * Page holds the name of a group this ValueDef belongs to.
implies * Page refers to another map feature which is implied by this KeyDef. Example values are Key:highway (referring to another KeyDef) or Tag:highway/primary (referring to another ValueDef)
requires * Page refers to another map feature which is required by this KeyDef. Example values are Key:name (referring to another KeyDef) or Tag:access/no (referring to another ValueDef)
suggests * Page refers to another map feature which is suggested to be used together with this KeyDef. Example values are Key:name (referring to another KeyDef) or Tag:access/no (referring to another ValueDef)

Preset

An individual of Preset describes, how an OSM element is tagged with various map features in order to precisely describe a kind of real-world objects.
Semantic Properties:
Name Multiplicity Type Description
name 1 (mandatory) String the unique name of the preset, i.e. hotel
displayName * String an localized display name for the preset. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized display names for multiple languages are maintained.
description * String an localized description for the preset. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized description for multiple languages are maintained.
lang 1 (mandatory) String the language of language dependent properties like displayName or description.
implies * Page refers to another map feature which is implied by this Preset. Example values are Key:highway (referring to another KeyDef) or Tag:highway/primary (referring to another ValueDef)
requires * Page refers to another map feature which is required by this Preset. Example values are Key:name (referring to another KeyDef) or Tag:access/no (referring to another ValueDef)
suggests * Page refers to another map feature which is suggested to be used together with this KeyDef. Example values are Key:name (referring to another KeyDef) or Tag:access/no (referring to another ValueDef)

Group

An individual of Group describes a specific group of map features.
Semantic Properties:
Name Multiplicity Type Description
name 1 (mandatory) String the unique name of the group primary
displayName * String an localized display name for the group. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized display names for multiple languages are maintained.
description * String an localized description for the group. Should not include HTML or wiki formatting because it will be used by applications other than the OSM wiki. See below on how localized description for multiple languages are maintained.
lang 1 (mandatory) String the language of language dependent properties like displayName or description.

Relationship between classes and Wiki categories

For each class we create a wiki category, i.e.

Relationships between properties and Wiki pages

In SWW, we can describe each property in a respective page in the namespace Property:, for instance Property:name or Property:implies. Creating property pages is not mandatory, but it makes sense, because the page provides semantic information about the property to editors. Editors can learn there what the meaning of a specific property is and what range of values are acceptable for this property.

Following the OSM philosophy, editors are still free to use whatever property they want, assigning whatever value they feel appropriate. However, editors are strongly encouraged to use a canonical set of semantic properties (those defined in the preceding sections) consistently.

A property page includes

It does not include, however:

Individuals and how we maintain them on the SMW

A specific key (for instance highway)

  • create a page Key:highway
  • include property declarations in the wiki source. They set the instantiated properties (OWL lingo), i.e. the property values for this individual. You may use a trailing | in [[property::value | ]] if setting the property should be invisible. Here's an example: 
 [[key::highway]]
 [[onNode::false]]
 [[onArea::true]]
 [[onWay::true]]
 [[onRelation::false]]
 [[state::accepted]]
 [[group::physical]]
Alternatively, you may want to use {{#set: key=highway}} which silently sets the property key
  • make sure it is marked as individual of the class KeyDef by including the following wiki category 
 [[Category:KeyDef]]
  • make sure there is at least one language specific page with language specific properties, for instance En:Key:highway. It should include 
 [[displayName::Highway]]
 [[description::This is the description for Highway]]
 [[lang::en]]
Furthermore, this page will include the rest of the wiki text for this key in english.

A specific value (for instance highway/residential)

  • create a page Tag:highway/residential
  • include property declarations in the wiki text. They define the instantiated properties (OWL lingo), i.e. the property values for this individual. You may use a trailing | in [[property::value | ]] if setting the property should be invisible. Here's an example: 
 [[key::highway]]
 [[value::residential]]
 [[onNode::false]]
 [[onArea::false]]
 [[onRelation::false]]
 [[state::accepted]]
 [[group::physical]]
Alternatively, you may want to use {{#set: key=highway}} which silently sets the property key
  • make sure it is marked as individual of the class ValueDef by including the following wiki category in the text 
  [[Category:ValueDef]]
  • make sure there is at least one language specific page with language specific properties, for instance En:Tag:highway/residential. It should include 
 [[displayName::Residential road]]
 [[description::This is the description for a residential road ]]
 [[lang::en]]
Furthermore, this page will include the rest of the wiki text for this value in english.

A specific group (for instance physical)

  • create a page Group:physical
  • include property declarations in the wiki text. They set the instantiated properties (OWL lingo), i.e. the property values for this individual. You may use a trailing | in [[property::value | ]] if setting the property should be invisible. Here's an example: 
 [[name::physical]]
Alternatively, you may want to use {{#set: name=physical}} which silently sets the property name
  • make sure it is marked as individual of the class Group by including the following wiki category 
  [[Category:Group]]
  • make sure there is at least one language specific page with language specific properties, for instance En:Group:physical. It should include 
 [[displayName::Physical]]
 [[description::Description for feature category Physical]]
 [[lang::en]]
Furthermore, this page will include the rest of the wiki text for this group.

A specific preset (for instance residential_road)

  • create a page Preset:residential_road
  • include property declarations in the wiki text 
 [[name::residential_road]]
 [[requires::Tag:highway/residential]]
 [[suggest::Key:name]]
 [[suggest::Tag:oneway/yes]]
 [[suggest::Key:maxspeed]]
Alternatively, you may want to use {{#set: name=residential}} which silently sets the property name


  • make sure it is marked as individual of the class Preset 
  [[Category:Preset]]
  • make sure there is at least one language specific page with language specific properties, for instance En:Preset:residential_road. It should include 
 [[displayName::Residential Road]]
 [[description::Description Residential Road ]]
 [[lang::en]]
Furthermore, this page will include the rest of the wiki text for this Preset.

Proposal for structuring map feature pages

Currently, map feature pages are maintained in specific pseudo-namespaces for map feature pages:

We continue with this approach in SWM:

For technical reasons we have to avoid equal signs (=) in page titles. SMW can't cope with them in semantic queries. Current page titles like Tag:highway=primary therefore have to be changed to Tag:highway/primary.

Internationalization / Localization

Most of the semantic properties of KeyDef, ValueDef, Group and Preset are languge independet. For instance, neither key nor value nor onNode has to be localized. There are, however, some semantic properties, whose values have to translated in several languages, for instance

Map feature pages are therefore maintained in one or more "language flavors" (as we always did on the OSM wiki):

Furthermore some semantic properties have country specific values:

Object properties and internationalized page titles

In the preceding section we introduced internationalized and localized page titles for map feature pages

In the context of SWN, property values are always considered to be wiki links. A property declaration [[description::This is a long description]] will lead to a wiki link This is a long description.

Some of our properties in SWN are, in OWL lingo, object properties, i.e. their instantiated object properties refer to other individuals. If we refer to other individuals of KeyDef, ValueDef, Group or Preset we newer include a language prefix or a country postfix in the value.

Valid examples:

Invalid examples:

Object properties therefore refer to the page in the default language. If we want to direct readers to a specific language dependent page, then we have to hide the property declaration and to add a wiki link explicitly, i.e. 

 [[implies::Key:highway | ]] <!-- hide the property declaration -->  
 Implies [[FR:Key:highway |<tt>highway</tt>]] <!-- add an explicit link to the french page -->

Harvesting map features

Data flow and tool chain (aka "architecture")


See also

Infrastructure

Archive

Outdated stuff, less useful stuff

Retrieved from "http://wiki.openstreetmap.org/wiki/Machine-readable_Map_Feature_list"
Personal tools
Namespaces
Variants
Actions
site
Toolbox