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 extract 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.6' 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'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 bounds 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. Example: <node id='132' action='modify' ...>
- The osm element can have the upload attribute with the value false to discourage uploads or with the value never to completely disable accidental uploads.
- 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 dependent 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-consistent 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:
Extracting the pending change to an osmChange file
If you want to extract the pending change from a JOSM file (i.e., elements with action='modify' or 'delete') to an osmChange (a.k.a. OSC) file for use in other applications, the above tools do not appear to be designed to do that (as of a quick look on 2025-07-18). So I (Matt McCutchen a.k.a. M3232) hacked together an XSL transform osm-modified-to-osc.xsl for the conversion. Assuming your system has xsltproc, you would run xsltproc osm-modified-to-osc.xsl my-pending-change.osm >my-pending-change.osc. This transform can be used as part of a workflow to transfer a pending change from JOSM to Vespucci without losing Vespucci's ability to view the original state of modified elements (see this issue thread). At present, the transform also includes a workaround for a Vespucci bug with importing deleted elements from OSC.
The transform is pretty simple-minded. If you run into limitations and are interested in helping to improve it, we can look into moving it to a proper software forge. Alternatively, maybe you can find a way to achieve the goal with other tools or we can get the functionality added to other tools. But for now, I wanted a solution right away and just wanted to share it.