JOSM file format

The JOSM file format is used by JOSM if and when the user saves/loads data to file. JOSM files have the .osm extension, and the format looks very much like a Planet.osm extracts or the result of a map call from the server, with a few additions. It is both a storage format and a change file format, so in addition to storing data downloaded from the server it can also represent changes made by the user since downloading.

Example

<?xml version='1.0' encoding='UTF-8'?>
<osm version='0.5' generator='JOSM'>
  <bounds minlat='51.5076478723889' minlon='-0.127989783553507' maxlat='51.5077445145483' maxlon='-0.127774884645096' origin='OpenStreetMap server' />
  <node id='26821100' timestamp='2009-02-16T21:34:57+00:00' user='dankarran' visible='true' lat='51.5077286' lon='-0.1279688'>
    <tag k='created_by' v='Potlatch 0.10f' />
    <tag k='name' v='Nelson&apos;s Column' />
    <tag k='tourism' v='attraction' />
    <tag k='monument' v='statue' />
    <tag k='historic' v='monument' />
  </node>
  <node id='-1' visible='true' lat='51.507661490456606' lon='-0.1278000843634869' />
  <node id='346364767' action='delete' timestamp='2009-02-16T21:34:44+00:00' user='dankarran' visible='true' lat='51.5076698' lon='-0.1278143' />
</osm>

The format looks almost exactly like the output from the server, with a few small changes:

• Addition of one or more bound elements which indicate the bounding boxes of the downloads that generated this data (if known). In addition these also have an origin attribute which indicates the server the data came from.
• Entities can have an action attribute which can take one of the values: modify or delete. For modify it indicates it should replace the old version of this entity.
• Creation is indicated by the use of a negative number in the id attribute. This negative ID is simultaneously a placeholder value which can be used elsewhere in the file for dependant object. IDs have to be allocated uniquely throughout the document.

Unlike some other change file formats the order of the entities is by type rather than in the actual order of the changes. The result is another self-consistant file, so it will always be possible to reorder the changes in such a way that referential integrity is preserved.

usage and intended use

The JOSM file-format is intended for the following types of clients:

• editors
• batch-scripts

it is not intended for

• devices with very limited storage-capacity
• devices with limited memory

it is optimized for:

• general usage

This protocol is supported by the following clients:

• JOSM
• Osmosis