Elements are the basic components of OpenStreetMap's conceptual data model of the physical world. Elements are of three types:
- nodes (defining points in space),
- ways (defining linear features and area boundaries), and
- relations (which are sometimes used to explain how other elements work together).
All of the above can have one or more associated tags (which describe the meaning of a particular element).
- Main article: Node
A node represents a specific point on the earth's surface defined by its latitude and longitude, referred to the World Geodetic System 1984. Each node comprises at least an id number and a pair of coordinates.
Nodes can be used to define standalone point features. For example, a node could represent a park bench or a water well.
Nodes are also used to define the shape of a way. When used as points along ways, nodes usually have no tags, though some of them could. For example, highway=traffic_signals marks traffic signals on a road, and power=tower represents a pylon along an electric power line.
- Main article: Way
Note that closed ways occasionally represent loops, such as roundabouts on highways, rather than solid areas. The way's tags must be examined to discover which it is. For elements with tags that could both be a linear representation or an area-representation of a real life object (such as man_made=pier) the tag area=yes or area=no can be used to avoid ambiguity or misinterpretation. See also: Way#Differences between linear and area representation of features
Areas with holes, or with boundaries of more than 2,000 nodes, cannot be represented by a single way. Instead, the feature will require a more complex multipolygon relation data structure.
- Main article: Relation
- A route relation, which lists the ways that form a major (numbered) highway, a cycle route, or a bus route.
- A turn restriction that says you can't turn from one way into another way.
- A multipolygon that describes an area (whose boundary is the 'outer way') with holes (the 'inner ways').
Thus, relations can have different meanings. The relation's meaning is defined by its tags. Typically, the relation will have a 'type' tag. The relation's other tags need to be interpreted in light of the type tag.
The relation is primarily an ordered list of nodes, ways, or other relations. These objects are known as the relation's members.
Each element can optionally have a role within the relation. For example, a turn restriction would have members with "from" and "to" roles, describing the particular turn that is forbidden.
A single element such as a particular way may appear multiple times in a relation.
- Main article: Tag
All types of data element (nodes, ways and relations), as well as changesets, can have tags. Tags describe the meaning of the particular element to which they are attached.
A tag consists of two free format text fields; a 'key' and a 'value'. Each of these are Unicode strings of up to 255 characters. For example, highway=residential defines the way as a road whose main function is to give access to people's homes. An element cannot have 2 tags with the same 'key', the 'key's must be unique. For example, you cannot have an element tagged both amenity=restaurant and amenity=bar.
There is no fixed dictionary of tags, but there are many conventions documented on this wiki (starting with the Map Features page). Tag usage can be measured with the Taginfo application. If there is more than one way to tag a given feature, it's probably best to use the most common approach.
Not all elements have tags. Nodes are often untagged if they are part of ways. Both ways and nodes may be untagged if they are members of a relation.
Within the OSM database, we store these attributes for nodes, ways and relations. Your application may not need to make use of all of them, and some third-party extracts produced from OSM data may not reproduce them all.
|id||integer (64-bit)||Used for identifying the element. Element types have their own ID space, so there could be a node with id=100 and a way with id=100, which are unlikely to be related or geographically near to each other.|
Positive (>0) values are used for all existing elements (and will remain assigned when they are modified or deleted); negative values (<0) are reserved (their scope limited to the current changeset and never stored in the database) and only used when sending data to the OSM database for identifying new objects to create and reference them in other created or modified objects (the server will replace these temporary identifiers sent by the editing application, by assigning an actual positive identifier for each created object, and will return a mapping from the negative identifiers used to their assigned positive identifiers).
|user||character string||The display name of the user who last modified the object (informative only and may be empty). A user can change their display name at any time (existing elements will reflect the new user name without needing any version change).|
|uid||integer||The numeric identifier of the user who last modified the object. An user identifier never changes.|
|timestamp||W3C standard date and time formats.||Time of the last modification (e.g. "2016-12-31T23:59:59.999Z").|
|visible||"true" or "false"||Whether the object is deleted or not in the database, if visible="false" then the object should only be returned by history calls.|
|version||integer||The edit version of the object. Newly created objects start at version 1 and the value is incremented by the server when a client uploads a new version of the object. The server will reject a new version of an object if the version sent by the client does not match the current version of the object in the database.|
|changeset||integer||The changeset number in which the object was created or updated (supporting 64-bit is recommended in applications for compatibility with long term evolution of the OSM database, but applications that only query data without updating them may ignore this informative attribute).|
Of course, in addition, we store the tags, and also a full editing history of every element.
Historically there was another element type. This is:
- segments (connecting two nodes and making up a way).
XML Caution and Notes on Nomenclature
- Main article: OSM XML
This documentation targets users of high level OSM tools such as editors, it does not serve as a low level data standard. Users who are looking for a low level standard will need to do some interpreting of the documentation to get a clear understanding and should be aware of departures from the XML standard.
The set of Elements in OSM XML that are referred to as elements in documentation are a subset of the actual XML elements found in the data. i.e. The term Element in XML and the term Element in OSM XML are not synonymous.
Elements in OSM data are defined as one of node, way, and relation. XML elements tag, nd, and member are not referred to as elements in OSM XML but they are indeed XML elements.
This does not serve to make the data invalid in any way it is merely a semantic obfuscation that has crept into the documentation that is viewed as too unimportant to rectify.
Users of XML tools should also be aware that nodes, ways and relations share the same object id space. Any tool which is solely referring to an OSM object by its id will encounter undefined behavior (e.g. Document.getElementById()). OSM Objects must always be referred to both with their object ids and their respective object type (node, way, relation).