I was reviewing the spec comments that we received over the past few months on the SSE spec, and because there was a fair amount of feedback about the “by” attribute on sx:history, I’d like to explain where the spec ended up.


Just to refresh your memory: every time an item or entry in a feed is changed, the endpoint making the change needs to add an sx:history element to call out the changes. The element has three attributes: a sequence attribute (the change number), a when attribute (date/time for the change), and a by attribute (the endpoint that made the change).


For purposes of sync, the by attribute has to uniquely identify the participating “endpoint”. You can think of by as the “endpoint ID.” The real world entity that the endpoint stands for could be one of several different things depending on your implementation: it could represent a user; or a user on a device; or a process for a user on a device; or something even more specific. One important consideration in picking which one of those things is an endpoint is that the by attribute determines the granularity of conflict detection. Any time an update is made by the same endpoint (the same “by”), that update subsumes all previous updates from that endpoint.


For a practical example, consider the case where I’m syncing data from my laptop to my phone. I change entry A on my laptop; then later (but before I’ve had a chance to sync) I change entry A on my phone. When I sync, one of two things happens. If the by attribute on both my laptop and my phone is identical, then one of those changes is discarded, because as far as the algorithm is concerned, they’re from the exact same endpoint. If the by attribute is different on the two devices, then both changes are preserved. At some point I’ll get to view both changes and choose which one I want to keep; no data is lost.


There were some suggestions that the by attribute should be required or recommended to be a URI. The reason that might be interesting is to somehow identify the (human) author of the change, or at least provide a pointer to the author. That’s definitely a useful thing to do. In the end, though, we felt that such a recommendation would make it harder for implementers to craft useful and unique endpoint IDs for their application.


Our recommendation is to choose the by attribute based on your granularity of conflict detection. Use a different element such as atom:author in order to indicate the source of a change.


Thanks for the feedback (past and future), it’s much appreciated!