AndWellness-JSON

From CSL Wiki

(Difference between revisions)
Jump to: navigation, search
Revision as of 18:14, 4 November 2009
Selsky (Talk | contribs)
(→Prompt Types and Sub-types)
← Previous diff		 Revision as of 23:37, 4 November 2009
Selsky (Talk | contribs)

Next diff →
Line 10: Line 10:
* All keys use lowercase. * All keys use lowercase.
-* All multi-word keys use dashes as a word separator.+* All multi-word keys use dashes as a word separator, with some exceptions.
* All multi-word values use underscores as a word separator. * All multi-word values use underscores as a word separator.
Line 17: Line 17:
* '''phone-version''': A float representing the phone application version. Required. Usage TBD. * '''phone-version''': A float representing the phone application version. Required. Usage TBD.
* '''protocol-version''': A float representing the JSON protocol version the current message adheres to. Required. Usage TBD. * '''protocol-version''': A float representing the JSON protocol version the current message adheres to. Required. Usage TBD.
 +* '''username''': A string used for identification. Required.
* '''data''': An array of objects. At least one packet is required and 500 is the maximum. * '''data''': An array of objects. At least one packet is required and 500 is the maximum.
Line 22: Line 23:
"phone-version":0.1, "phone-version":0.1,
"protocol-version":0.1, "protocol-version":0.1,
 + "username":"bob@example.com",
"data":[first packet],[second packet], ... ,[nth packet] "data":[first packet],[second packet], ... ,[nth packet]
} }
Line 29: Line 31:
The data packet is a JSON Object with a set of standard and function-specific data elements. The data packet is a JSON Object with a set of standard and function-specific data elements.
-* '''user-name''': A string used for identification. Required. 
* '''date''': A string in the ISO 8601 format to the detail of seconds “YYYY-MM-DD hh:mm:ss”. Required. * '''date''': A string in the ISO 8601 format to the detail of seconds “YYYY-MM-DD hh:mm:ss”. Required.
* '''time''': An int specifying the number of milliseconds since the epoch. * '''time''': An int specifying the number of milliseconds since the epoch.
* '''type''': A lowercase string specifying the data type. Required. * '''type''': A lowercase string specifying the data type. Required.
-* '''sub-type''': A lowercase string specifying the data subtype (specialization). Required.+* '''subtype''': A lowercase string specifying the data subtype (specialization). Required.
-* '''latitude''': A float representing latitude. Required.+* '''location''': An object for housing location data. Contains latitude and longitude and will probably contain other elements in the future.
-* '''longitude''': A float representing latitude. Required.+** '''latitude''': A float representing latitude. Required.
-* '''time-zone''': A string representing a standard time zone. Required.+** '''longitude''': A float representing latitude. Required.
 +* '''timezone''': A string representing a standard time zone. Required.
* Feature specific data. * Feature specific data.
Line 42: Line 44:
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"type", "type":"type",
- "sub-type":"subtype",+ "subtype":"subtype",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
- "time-zone":"EST",+ "longitude",-77.0366
 + },
 + "timezone":"EST",
... ...
}] }]
-=== Message Types and Sub-types ===+=== Message Types and Subtypes ===
-Each JSON message has a type and a sub-type. The reason we have introduced typing into the message protocol is due to the nature of having only one upload URL (API entry point). If we had separate URLs for mobility uploads and prompt responses, we could remove one level of typing from these messages. It would be nice for AndWellness to have multiple URLs as described, but for the PDV, separate URLs would be a difficult task due to the PDV's generic nature of being able to interface with many third-party applications and datatypes.+Each JSON message has a type and a subtype. The reason we have introduced typing into the message protocol is due to the nature of having only one upload URL (API entry point). If we had separate URLs for mobility uploads and prompt responses, we could remove one level of typing from these messages. It would be nice for AndWellness to have multiple URLs as described, but for the PDV, separate URLs would be a difficult task due to the PDV's generic nature of being able to interface with many third-party applications and datatypes.
=== Mobility Types and Sub-types === === Mobility Types and Sub-types ===
Line 61: Line 64:
The mobility <code>type</code> allows us to specify details for messages related to the phone user's mobility state. The mobility <code>type</code> allows us to specify details for messages related to the phone user's mobility state.
-The mobility <code>sub-types</code> are: <code>mode_only</code> and <code>mode_features</code>. Each sub-type specifies a data packet as described below.+The mobility <code>subtypes</code> are: <code>mode_only</code> and <code>mode_features</code>. Each sub-type specifies a data packet as described below.
* type: '''mobility''' * type: '''mobility'''
Line 70: Line 73:
** sub-type: '''mode_features''' ** sub-type: '''mode_features'''
*** '''features''' An object specifying classification features. Required. *** '''features''' An object specifying classification features. Required.
 +**** '''mode''' A string as described by mode_only above. Required.
**** '''speed''' A float. Required. **** '''speed''' A float. Required.
**** '''variance''': A float. Required. **** '''variance''': A float. Required.
Line 78: Line 82:
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"mobility", "type":"mobility",
"sub-type":"mode_only", "sub-type":"mode_only",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
 + "longitude",-77.0366
 + },
"time-zone":"EST", "time-zone":"EST",
"mode":"still" "mode":"still"
Line 92: Line 97:
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"mobility", "type":"mobility",
"sub-type":"mode_features", "sub-type":"mode_features",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
 + "longitude",-77.0366
 + },
"time-zone":"EST", "time-zone":"EST",
"features":{ "features":{
 + "mode":"still",
"speed":0.0, "speed":0.0,
"variance":0.0, "variance":0.0,
Line 108: Line 115:
}] }]
-=== Prompt Types and Sub-types ===+=== Prompt Types and Subtypes ===
-The prompt <code>type</code> allows us to specify details for messages related to the phone user's EMA responses. Each prompt <code>type</code> message must contain a <code>sub-type</code>. For the initial rollout of the application, the server will be accepting responses for five different prompts: stress, mood, energy, glucose level, and blood pressure. Stress, mood, energy, and glucose level have range-bound values while blood pressure has values for systolic and diastolic pressure. +The prompt <code>type</code> allows us to specify details for messages related to the phone user's EMA responses. Each prompt <code>type</code> message must contain a <code>subtype</code>. For the initial rollout of the application, the server will be accepting responses for five different prompts: stress, mood, energy, glucose level, and blood pressure. Stress, mood, energy, and glucose level have range-bound values while blood pressure has values for systolic and diastolic pressure.
{| border="1" cellpadding="10" cellspacing="0" {| border="1" cellpadding="10" cellspacing="0"
Line 137: Line 144:
* type: '''prompt''' * type: '''prompt'''
-** sub-type: a lowercase string that is one of: stress, mood, energy, bloodpressure+** subtype: a lowercase string that is one of: stress, mood, energy, bloodpressure
*** response: any JSON object (the format of the response depends on the sub-type) *** response: any JSON object (the format of the response depends on the sub-type)
-Example (<code>type=prompt, sub-type=stress</code>)+Example (<code>type=prompt, subtype=stress</code>)
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"prompt", "type":"prompt",
- "sub-type":"stress",+ "subtype":"stress",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
- "time-zone":"EST",+ "longitude",-77.0366
 + },
 + "timezone":"EST",
"response":1 "response":1
}] }]
-Example (<code>type=prompt, sub-type=mood</code>)+Example (<code>type=prompt, subtype=mood</code>)
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"prompt", "type":"prompt",
- "sub-type":"mood",+ "subtype":"mood",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
- "time-zone":"EST",+ "longitude",-77.0366
 + },
 + "timezone":"EST",
"response":1 "response":1
}] }]
Line 171: Line 180:
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"prompt", "type":"prompt",
- "sub-type":"energy",+ "subtype":"energy",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
- "time-zone":"EST",+ "longitude",-77.0366
 + },
 + "timezone":"EST",
"response":1 "response":1
}] }]
-Example (<code>type=prompt, sub-type=glucose_level</code>)+Example (<code>type=prompt, subtype=glucose_level</code>)
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"prompt", "type":"prompt",
- "sub-type":"glucose_level",+ "subtype":"glucose_level",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
- "time-zone":"EST",+ "longitude",-77.0366
 + },
 + "timezone":"EST",
"response":1 "response":1
}] }]
-Example (<code>type=prompt, sub-type=blood_pressure</code>)+Example (<code>type=prompt, subtype=blood_pressure</code>)
[{ [{
- "user-name":"bob@example.com", 
"date":"2009-11-03 10:18:33", "date":"2009-11-03 10:18:33",
"time":1257272467077, "time":1257272467077,
"type":"prompt", "type":"prompt",
- "sub-type":"blood_pressure",+ "subtype":"blood_pressure",
- "latitude":38.8977,+ "location": {
- "longitude",-77.0366,+ "latitude":38.8977,
- "time-zone":"EST",+ "longitude",-77.0366
 + },
 + "timezone":"EST",
"response":{ "response":{
"systolic":70, "systolic":70,

Revision as of 23:37, 4 November 2009

Contents

HTTP Between Phone and Server

This page defines the data format (schema) used between a phone and the server application. The client-server protocol uses JSON over HTTP. It is expected that the schema will change over time. The upload URL will be something like http://pilot.andwellness.cens.ucla.edu/upload?json={...}. TBC.

All client-server communication must use UTF-8 character encoding.

JSON

Naming Conventions

  • All keys use lowercase.
  • All multi-word keys use dashes as a word separator, with some exceptions.
  • All multi-word values use underscores as a word separator.

Upload Format

  • phone-version: A float representing the phone application version. Required. Usage TBD.
  • protocol-version: A float representing the JSON protocol version the current message adheres to. Required. Usage TBD.
  • username: A string used for identification. Required.
  • data: An array of objects. At least one packet is required and 500 is the maximum. 
   {
      "phone-version":0.1,
      "protocol-version":0.1,
      "username":"bob@example.com",
      "data":[first packet],[second packet], ... ,[nth packet]
   }

Data Packet

The data packet is a JSON Object with a set of standard and function-specific data elements.

  • date: A string in the ISO 8601 format to the detail of seconds “YYYY-MM-DD hh:mm:ss”. Required.
  • time: An int specifying the number of milliseconds since the epoch.
  • type: A lowercase string specifying the data type. Required.
  • subtype: A lowercase string specifying the data subtype (specialization). Required.
  • location: An object for housing location data. Contains latitude and longitude and will probably contain other elements in the future.
    • latitude: A float representing latitude. Required.
    • longitude: A float representing latitude. Required.
  • timezone: A string representing a standard time zone. Required.
  • Feature specific data.

Example: 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"type",
       "subtype":"subtype",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "timezone":"EST",
       ...
   }]

Message Types and Subtypes

Each JSON message has a type and a subtype. The reason we have introduced typing into the message protocol is due to the nature of having only one upload URL (API entry point). If we had separate URLs for mobility uploads and prompt responses, we could remove one level of typing from these messages. It would be nice for AndWellness to have multiple URLs as described, but for the PDV, separate URLs would be a difficult task due to the PDV's generic nature of being able to interface with many third-party applications and datatypes.

Mobility Types and Sub-types

The mobility type allows us to specify details for messages related to the phone user's mobility state.

The mobility subtypes are: mode_only and mode_features. Each sub-type specifies a data packet as described below.

  • type: mobility
    • subtype: mode_only
      • mode: A lowercase string specifying an mobility mode. The allowed values are: still, walk, run, bike, drive. Required.
  • type: mobility
    • sub-type: mode_features
      • features An object specifying classification features. Required.
        • mode A string as described by mode_only above. Required.
        • speed A float. Required.
        • variance: A float. Required.
        • average: A float. Required.
        • fft: An array of ten floats. Required.

Example (type=mobility, sub-type=mode_only): 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"mobility",
       "sub-type":"mode_only",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "time-zone":"EST",
       "mode":"still"
   }]

Example (type=mobility, sub-type=mode_features): 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"mobility",
       "sub-type":"mode_features",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "time-zone":"EST",
       "features":{
           "mode":"still",
           "speed":0.0,
           "variance":0.0,
           "average":0.0,
           "fft":[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]
       }
   }]

Prompt Types and Subtypes

The prompt type allows us to specify details for messages related to the phone user's EMA responses. Each prompt type message must contain a subtype. For the initial rollout of the application, the server will be accepting responses for five different prompts: stress, mood, energy, glucose level, and blood pressure. Stress, mood, energy, and glucose level have range-bound values while blood pressure has values for systolic and diastolic pressure.

Prompt Response Limits
Stress 1 <= n <= 5
Mood 1 <= n <= 5
Energy 1 <= n <= 5
Glucose Level 1 <= n <= 11
Blood Pressure Two integer values: systolic and diastolic pressure. Min and max for each TBD.

Message hierarchy:

  • type: prompt
    • subtype: a lowercase string that is one of: stress, mood, energy, bloodpressure
      • response: any JSON object (the format of the response depends on the sub-type)

Example (type=prompt, subtype=stress) 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "subtype":"stress",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "timezone":"EST",
       "response":1
   }]

Example (type=prompt, subtype=mood) 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "subtype":"mood",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "timezone":"EST",
       "response":1
   }]

Example (type=prompt, sub-type=energy) 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "subtype":"energy",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "timezone":"EST",
       "response":1
   }]

Example (type=prompt, subtype=glucose_level) 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "subtype":"glucose_level",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "timezone":"EST",
       "response":1
   }]

Example (type=prompt, subtype=blood_pressure) 

   [{
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "subtype":"blood_pressure",
       "location": {
           "latitude":38.8977,
           "longitude",-77.0366
       },
       "timezone":"EST",
       "response":{
           "systolic":70,
           "diastolic":100
       }
   }]

Prompts/EMAs we are considering for future iterations of the application are: diet, exercise, sexual interactions, drug use, and various biomarkers. It would be good to separate the EMAs by proposal. TBD.

Retrieved from "http://www.lecs.cs.ucla.edu/wiki/index.php/AndWellness-JSON"
Personal tools