Open tyrasd opened 3 years ago
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 likelast 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!
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:
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.
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?
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.
If they find it useful
do they? if yes, for what purpose do they use it?
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.
@lastEdit
when metadata is requested. This property contains the value of thetimestamp
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?@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.