...
| Code Block |
|---|
{
"files" : [ {
"filename" : "audio_countdown.m4a",
"timestamp" : "2015-03-02T03:26:59-08:00"
}, {
"filename" : "audio_audio.m4a",
"timestamp" : "2015-03-02T03:27:09-08:00"
} ],
"item" : "Voice Activity",
"appVersion" : "version 1.0.2, build 8",
"phoneInfo" : "iPhone 6"
}
|
info.json must contain a list of files. Each file in the bundle must have a corresponding entry in info.json's file list, and vice versa. Each file entry must have a filename and a timestamp representing when the file's data was measured and written. If the data was measured over a long period of time, the timestamp should represent when the data was last measured and written. The timestamp must be in ISO 8601 format (http://en.wikipedia.org/wiki/ISO_8601).
info.json must also include item, which is a human-readable String describing the activity that this data is measured from. The item name must uniquely distinguish the activity from all other activities within the app, and each activity in the app must have the same item name.
info.json may include other fields, in either the top-level struct, or in the file entries, or both. These additional fields are used as metadata for the researchers and have no restrictions imposed by the Bridge server. These fields could include things like app name, app version, OS version, etcmust also include the appVersion and phoneInfo fields, which describe app version and phone hardware (and optionally software) respectively.
Surveys
Surveys consist of metadata in the info.json file as well as individual files for each survey answer.
...
The survey must also have a corresponding schema (see Schemas). The "item" field in info.json must match the schema ID. There must be a field definition in the schema for every "item" field in every possible survey file in the upload bundle. For example, if your survey info.json declares "item":"DailySurvey", and it has files foo.json, bar.json, baz.json with "item":"foo", "item":"bar", and "item":"baz", then you must have a schema with ID "DailySurvey" with fields "foo", "bar", and "baz". TODO: Support server-side surveys, that match the survey and questions using guids and the survey API instead of Upload Schemas.
Non-
...
Survey Data
Some activities will produce non-JSON data, such as audio files or CSVs. If there is at least one non-JSON file in the upload bundle, the Bridge server will automatically detect this and treat the upload bundle as a non-JSON data bundle, even if there is other JSON data in the bundle.
The Bridge server will first use the value of For non-survey data, the Bridge server will use the "item" field in info.json to identify the schema, matching the schema name (not ID) with the item name in info.json. (TODO: Update Bridge server to match with schema ID, then fall back to schema name.) The Bridge server will then match each file in the bundle with the corresponding field in the schema, using the filename. For example, if your bundle contains the files voice_recording.wav, accelerometer_data.csv, and metadata.json, it will match them up with the field names voice_recording.wav, accelerometer_data.csv, metadata.json. For more information about Schemas, see Schemas
info.json will still be preserved as metadata and still be used as JSON data.
JSON Data
Editor's note: ResearchKit data does not tag itself with the data's schema ID, so the Bridge server has to parse into the data to determine its schema. This may or may not be improved in the future.
If an upload bundle is neither a survey nor non-JSON data, then the Bridge server will treat the bundle as a JSON bundle.
The Bridge server first determines the fields the data represents. determine the schema. The schema fields should match one-to-one with the fields in the upload bundle. Since different files can have fields with the same name, it will use filenames to prefix the file's field names to generate the bundle's field names. For example, if your data looks like
...
| Code Block |
|---|
{
"speed":88,
"speedUnit":"mph",
"color":"tope"
}
|
Then your data will schema should have field names "foo.json.xyz", "foo.json.persistence", "foo.json.color", "bar.json.speed", "bar.json.speedUnit", "bar.json.color". The Bridge server will then check these field names and field types against the field definitions of every schema registered to your app. If every required field in the schema is present in your upload bundle representing the correct type, and there are no extraneous fields in your data the schema is not aware of (including both required and optional fields), then the data is matched to the schema.
If no schema matches your data, the server will reject the data.
TODO: Update the server to treat null JSON values and empty strings, structs, and lists as non-existent.(Alternatively, if the entire bar.json should be a single field with the entire JSON file as an attachment, you could declare a field called bar.json.)
Schemas
A schema is defined as follows:
| Code Block |
|---|
{
"name": "Sample Schema",
"schemaId": "sample-schema",
"schemaType": "ios_data",
"revision": 1,
"fieldDefinitions": [
{
"name": "foo",
"required": true,
"type": "STRING"
},
{
"name": "bar",
"required": true,
"type": "INT"
},
{
"name": "baz",
"required": false,
"type": "BOOLEAN"
}
],
"type": "UploadSchema"
}
|
...
schemaId is the machine-readable unique identifier for your schema.
schemaType represents the type of schema. For iOS uploads, valid values are ios_survey for surveys and ios_data for non-surveys.
revision is the revision number of your schema. Schemas are immutable. Once registered, they cannot be modified. However, researchers can upload a new revision of a schema.
...
- ATTACHMENT_BLOB - Used for non-JSON data uploads. Represents any kind of non-JSON attachment that should be uploaded separately from structured data. Generally used for things like audio files.
- ATTACHMENT_CSV - Used for non-JSON data uploads. Represents a file in CSV format. Bridge server will attempt to perform further post-processing on this CSV file.
- ATTACHMENT_JSON_BLOB - Large blobs of JSON data that should be stored separately from structured data. This is treated the same as ATTACHMENT_BLOB, but is tagged as JSON data for researcher convenience.
ATTACHMENT_JSON_TABLE - A blob of JSON data in a structured tabular form, which can be used for additional post-processing on the server. Example:
Code Block [ { "accelerometer":{ "x":0.23, "y":-0.92, "z":0.0 }, "speed":2.78, "feeling":"hungry" }, { "accelerometer":{ "x":0.88, "y":-2.7, "z":-9.8, }, "speed":0.12, "feeling":"excited" } ]- BOOLEAN - true or false
- CALENDAR_DATE - String in YYYY-MM-DD format.
- FLOAT - floating point number, including floats, doubles, and decimals. TODO: Update server to accept ints as floats instead of just floats, decimals, and doubles.
- INLINE_JSON_BLOB - JSON blob that's small enough to fit inside the health data. Generally something that's less than a hundred characters. This is used for things like small lists: [ "apples", "banananas", "cranberries" ].
- INT - integers, including longs and big integers.
- STRING - any non-empty string. NOTE: Strings can't exceed 100 characters in length, or they won't fit into Synapse tables. If this is freeform text from the user, make sure this is limited to 100 characters, or specify the schema as ATTACHMENT_BLOB.
- TIMESTAMP - timestamps, can either be a string in ISO 8601 format or a long that's milliseconds since the beginning of the epoch (1970-01-01).
...