Rename metadata properties of data extraction requests

[tyrasd]

1. The response of (non-full-history) data extraction requests includes a property @lastEdit when metadata is requested. This property contains the value of the timestamp metadata field of the respective OSM element, which is not always the “last edit” time of it. Since also the documentation does not explain what exactly is returned in each property, the current situation could lead to some users to mistake the returned timestamp as the actual time where this entity was last edited. This could be resolved by renaming the property to something more neutral, e.g. @osmTimestamp perhaps?
   • alternatively: remove this (useless) property from the output completely.
2. The returned metadata property @version does not follow the nomenclature for the very closely related metadata fields @osmType and @osmId. It could make sense to rename it to @osmVersion for improved consistency.

[bonaparten]

This could be resolved by renaming the property to something more neutral, e.g. `@osmTimestamp` perhaps?

I am not sure whether @osmTimestamp prevents misleadings. I would either find a better name(?) or change the description of @lastEdit in the documentation with something like last edit of the OSM element at the given snapshot timestamp.

It could make sense to rename it to @osmVersion for improved consistency.

I am for it!

[tyrasd]

I would either find a better name or change the description of […] in the documentation

why not both? :nerd_face:

---

last edit of the OSM element at the given snapshot timestamp

this would be incorrect, since the returned values is (as I tried to explain) not necessarily the last edit of the OSM element.

the most concise/useful description I could give would be following:

Value of the timestamp metadata field of the underlying OSM element. Note that this does not always reflect the last edit of the OSM element at the given snapshot timestamp, since it ignores minor edits to the OSM element (i.e. where only the element's members are changed).

---

find a better name

sure, @osmTimestamp is not perfect (e.g. it's not very descriptive, and it could could be confused with the state of the underlying OSM database, etc.), but it would fit to the naming scheme of the other osm element metadata fields (@osmId, @osmType, [@osmVersion]). It would be also less incorrect than what the current @lastEdit implies. Anyway, I'm all ears for better alternative names. :ear:

[bonaparten]

why not both?

Because changing the name implies changing the description anyway since the description is wrong.

this would be incorrect, since the returned values is (as I tried to explain) not necessarily the last edit of the OSM element.

You are right!

Value of the timestamp metadata field of the underlying OSM element. Note that this does not always reflect the last edit of the OSM element at the given snapshot timestamp, since it ignores minor edits to the OSM element (i.e. where only the element's members are changed).

It looks like a good description.

sure, @osmTimestamp is not perfect (e.g. it's not very descriptive, and it could could be confused with the state of the underlying OSM database, etc.), but it would fit to the naming scheme of the other osm element metadata fields (@osmId, @osmType, [@osmVersion]). It would be also less incorrect than what the current @lastEdit implies. Anyway, I'm all ears for better alternative names. ear

But if the problem is to fit the naming scheme we can change it to @osmLastEdit and we are still stuck on the problem. @osmTimestamp isn't a good name (and I am not saying that @lastEdit is better), what does "timestamp of the OSM element" mean if the state of the element at that time still doesn't refer to the states of its members? I think the description, more than the naming, adds value for the users.

[tyrasd]

I think the description, more than the naming, adds value for the users.

from personal experience this might not be the case. Many users (including myself) only read the manual when absolutely necessary and trust their intuition or educated guessing as long as that works. That's how (good) design works: You optimize for easy recognition and don't force users to think/learn/read about things which are not necessary.

IMHO @lastEdit particularly fails to be a good design choice because it leads users to the wrong conclusions while intuitively interpreting the data. It also doesn't give a hint to read it up in the documentation, since the field name already comes presented as an easy to understand message (but it's a trap, however!). Again, I agree that @osmTimestamp is also not great when it comes to provide a good intuition about it's content, but at least it is vague enough (in my opinion) to trigger an interested user to look it up on the documentation.

The reason why it's hard to come up with a useful name for this property is that the property in itself is quite useless in the first place (yes, really!) when looking at it from the context of the ohsome API. The only alternative solution I can see is to remove the property from the output altogether. What do you think about that?

[bonaparten]

from personal experience this might not be the case. Many users (including myself) only read the manual when absolutely necessary and trust their intuition or educated guessing as long as that works. That's how (good) design works: You optimize for easy recognition and don't force users to think/learn/read about things which are not necessary.

That is true, but I meant in this case the description, more than the naming, adds value for the users unless we use extremely precise words ending up with a very long property name.

The only alternative solution I can see is to remove the property from the output altogether. What do you think about that?

I think it depends on the users. If they find it useful we should not remove it and we should rather try to find a meaningful name and improve the description in the documentation. Otherwise, we should remove it.

[tyrasd]

If they find it useful

do they? if yes, for what purpose do they use it?

[bonaparten]

I don't know if they use it and I don't know if it was implemented before the contribution endpoint, but we shouldn't ascribe any behavior to users, we should ask them about the purpose instead.