tidepool-org/data-model — pull request #18 by cheddar (2014-03-20 04:37:40+00:00)
Title: Add v1 documentation of "incoming" data format

@HowardLook @jebeck @brandonarbiter @kentquirk @cmakler

This is a pull request that starts the documentation of what I am hoping to call the "Tidepool data format v1.0". The intent of this document is that it shows the events that Tidepool understands. The document should actually be reusable as something that we give to vendors to start a conversation with them about what makes the most sense for emitting data.

One assumption I've made with the event structure is that I am trying to make a set of events that are friendly to a device that simply emits an event when it does something. So, it should be a format that we can also expose to the WeAreNotWaiting crowd as something their Android devices could emit and get data into the tidepool platform in real-time.

This format is the output format of the "parsers".

The reason I am creating this document now is because when I explored the issues with basal display and Howard's fakabetic episodes, I realized that there were some things that we hadn't accounted for in the data as of yet. Namely, the premature canceling of temp basals. After thinking about how we can handle that, I felt it best to actually extend our data model with another event that indicates the premature termination of a temp basal. I'm fine making this decision uni-laterally, but I figured it best to at least fish for buy-in first and the best way to do that seemed to be to document what we have and try to explain the use-case through that documentation. Thus, we have this.

So, to be clear, I've only documented the basal data formats so far. The initial "scheduled" and "temp" events are things that we are generating today in the parsers and I do not believe are controversial. The "temp/stop" is a new event that I am proposing we add as a method of indicating that a temp basal has been canceled.

I am hoping for this to spark two conversations:

1) Agreement or disagreement on having a "temp/stop" event in our "standard data format"
2) Discussion of the perceived value of this document, the specification of our format and the strategy for proselytizing our format

I need a conclusion on (1) quickly (within the bounds of tomorrow would be great). So please review the content of what I've written, respond with questions if you do not understand, and maybe we jump on a hangout tomorrow to discuss.

I do not think that pilot needs to block on (2), but a well-defined format is something I strongly want to push out to the world and I want to do everything I can to ensure that the conversation eventually happens.