[OSM-dev] 0.6: Attribute Naming, version on <nd>?

[Christopher Schmidt]

So, 0.6 is introducing a couple of new attributes in input/output. The
naming of these isn't 100% clear, so I'd like to make it so that it is
clear; or perhaps it is clear, and I just don't like it :)

I'll state upfront that one of the things that I like most as a
developer is the fact that any OSM node/way/relation XML I find, I can
take, as-is, and post back to the API with modifications to save a new
copy.

With that in mind, I think that we should seek to make the input/output
of all objects use:
 
 * id -- ID of object in database. For 'create', this is the 'new id',
         created on the server. For objects which are not yet created,
         this may be a negative 'placeholder' value.
 * version -- The most recent version of the object, from the
              perspective of the object holder. This might be 
              the version that the client last downloaded; the server
              should always deliver the most recent version with any
              request.

This would then be the same on all input/output, allowing easy
copy/paste of XML from a response.

There is one other new-style piece of information which is only
applicable to changeset-uploading: the 'old id', the placeholder ID with
which 'create' objects were uploaded. I think that 'old_id' is
appropriate for this.

This means that a node returned via /node/123 would look like:

 <node id="123" version="12" ... />

A node posted to the same URL would look the same.

A node returned via the changeset/diff upload would be uploaded like:

  <node id="-1" ... />

and be returned like:

  <node id="124" old_id="-1" version="1" ... />

The other attribute that is new is the 'changeset' identifier.
Currently, nothing in the code uses this, as far as I know. I'd like to
suggest that the changeset identifier be placed on the parent node of
the document. The reason to place it there -- instead of on the objects
-- is that a single document, even a diff upload, should only be used
for posting items to a single changeset. Forcing it on the topmost
element -- either <osm> or <osmChange> -- seems an easy way to ensure
this.

So, posting a full document to /node/123:

<osm version="0.6" changeset="34">
  <node id="123" version="12" ... />
</osm>

Posting a full osmChange:

<osmChange version="0.6" changeset="37">
  <create>
    <node id="-1" lat="12" lon="34" />
  </create>
  <modify>
    <way id="7" version="8">
      <nd ref="-1" />
      <nd ref="23" />
      <nd ref="123" />
    </way>
  </modify>
</osmChange>

Response:

<osmChange version="0.6" changeset="37">
  <create>
    <node id="124" old_id="-1" version="1" lat="12" lon="34" />
  </create>
  <modify>
    <way id="7" version="9">
      <nd ref="124" />
      <nd ref="23" />
      <nd ref="123" />
    </way>
  </modify>
</osmChange>

This brings a couple other questions to my mind:

 * Currently, we don't report or check the versions on nodes that are
   part of a way. If a node has since been deleted, the way will simply
   include the node, afaik (or at least, it won't complain because of a
   version mismatch.) Should we report versions of nodes, and require
   that they match when saving a way? (The data needs to be available
   everywhere already anyway: if you have a node, you got a version with
   it.) 

 * Same question applies for relations, I think.

Would love feedback on this...

Regards,
-- 
Christopher Schmidt
MetaCarta