# Upload Metadata (`upload`) ## Quick Summary ```json { "$ref": "#/components/schemas/upload.v1", "components": { "schemas": { "code.v1": { "title": "Annotation Code", "description": "Annotation codes that appear in Tidepool diabetes data records.\nThe annotation codes are primarily intended for machine processing, but they are usually readable enough to make sense.\nThese are by convention structured as series of strings separated by slashes (`/`), in order from more general to more specific.\nFor example:\n\n * `wrong-device-time` or `time-change`, generic annotations.\n * `basal/unknown-duration` or `bg/out-of-range`, generic annotations around a particular theme.\n * `medtronic/basal/flat-rate`, a manufacturer-specific annotation.\n * `medtronic600/smbg/user-rejected-remote-bg`, a device-specific annotation.", "type": "string", "minLength": 1, "pattern": "^[0-9a-z\\-_]+(/[0-9a-z\\-_]+(/[0-9a-z\\-_]+)?)?$", "enum": [ "animas/basal/flat-rate", "animas/basal/marked-suspended-from-alarm", "animas/bolus/extended-equal-split", "animas/bolus/unknown-duration", "animas/out-of-sequence", "animas/status/fabricated-from-alarm", "basal/auto", "basal/intersects-incomplete-suspend", "basal/mismatched-series", "basal/unknown-duration", "bg/out-of-range", "carelink/basal/fabricated-from-schedule", "carelink/basal/fabricated-from-suppressed", "carelink/basal/off-schedule-rate", "carelink/bolus/missing-square-component", "carelink/wizard/long-search", "final-basal/fabricated-from-schedule", "insulet/basal/fabricated-from-schedule", "insulet/bolus/split-extended", "medtronic/basal/fabricated-from-schedule", "medtronic/basal/flat-rate", "medtronic/basal/one-second-gap", "medtronic/basal/time-change", "medtronic/status/fabricated-from-device-event", "medtronic/wizard/carb-to-exchange-ratio-deconverted", "medtronic600/smbg/bg-reading-received", "medtronic600/smbg/bg-sent-for-calib", "medtronic600/smbg/bg-si-fail-result-recd-frm-gst", "medtronic600/smbg/bg-si-pass-result-recd-frm-gst", "medtronic600/smbg/entered-as-bg-marker", "medtronic600/smbg/entered-in-bg-entry", "medtronic600/smbg/entered-in-bolus-wizard", "medtronic600/smbg/entered-in-meal-wizard", "medtronic600/smbg/entered-in-sensor-calib", "medtronic600/smbg/remote-bg-acceptance-screen-timeout", "medtronic600/smbg/user-accepted-remote-bg", "medtronic600/smbg/user-rejected-remote-bg", "medtronic600/smbg/user-rejected-sensor-calib", "spring-forward", "stats-how-calculated", "stats-how-calculated-average-cbg", "stats-how-calculated-average-smbg", "stats-how-calculated-range-cbg", "stats-how-calculated-range-smbg", "stats-how-calculated-ratio", "stats-insufficient-data", "status/incomplete-tuple", "tandem/basal/fabricated-from-new-day", "tandem/basal/temp-without-rate-change", "tandem/pumpSettingsOverride/estimated-duration", "tandem/pumpSettingsOverride/fabricated-from-new-day", "time-change", "uncertain-timestamp", "wizard/target-automated", "wrong-device-time" ], "example": "wrong-device-time" }, "bgoutofrange.v1": { "title": "Blood Glucose Out of Range", "type": "object", "properties": { "code": { "type": "string", "enum": [ "bg/out-of-range" ], "example": "bg/out-of-range" }, "value": { "type": "string", "enum": [ "low", "high" ], "example": "low" }, "threshold": { "type": "number", "example": 40 } }, "required": [ "code", "value", "threshold" ] }, "annotation.v1": { "title": "Annotation", "description": "Annotation attached to the diabetes data record to provide additional information. Annotation is at minimum a `code` (string) that describes the annotation. It may also include additional properties that further describe the annotation. The maximum size is 4K bytes.", "type": "object", "allOf": [ { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/code.v1" } }, "required": [ "code" ] }, { "oneOf": [ { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/code.v1" } }, "required": [ "code" ] }, { "$ref": "#/components/schemas/bgoutofrange.v1" } ] } ] }, "annotationarray.v1": { "title": "Annotation Array", "description": "An array of annotations.", "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/annotation.v1" } }, "datetime.v1": { "title": "Date/Time", "description": "[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) / [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp _with_ timezone information", "type": "string", "format": "date-time", "example": "2017-02-06T02:37:46Z", "x-go-type": "string" }, "datasetid.v1": { "title": "Data Set ID", "type": "string", "pattern": "^(upid_[0-9a-f]{12}|upid_[0-9a-f]{32}|[0-9a-f]{32})$", "minLength": 17, "maxLength": 37, "example": "ce8cc5f7595575945f91fc6710db6fef", "x-tags": [ "Data" ] }, "association-type.v1": { "title": "Association Type", "description": "The type of the association. If type is `blob`, `datum`, or `image`, then `id` must also be specified. If type is `url`, then url must also be specified.", "type": "string", "enum": [ "blob", "datum", "image", "url" ], "example": "blob", "x-go-type": "string" }, "reason.v1": { "title": "Association Reason", "description": "The reason for the association.", "type": "string", "minLength": 1, "maxLength": 1000 }, "association-id.v1": { "title": "Association ID", "description": "The ID of the associated Tidepool resource if type is blob, datum, or image.", "type": "string" }, "url.v1": { "title": "URL", "description": "URL", "type": "string", "format": "uri" }, "blob.v1": { "title": "Association (blob)", "type": "object", "properties": { "type": { "$ref": "#/components/schemas/association-type.v1" }, "reason": { "$ref": "#/components/schemas/reason.v1" }, "id": { "$ref": "#/components/schemas/association-id.v1" }, "url": { "$ref": "#/components/schemas/url.v1" } }, "required": [ "type", "id" ] }, "datum.v1": { "title": "Association (datum)", "type": "object", "properties": { "type": { "$ref": "#/components/schemas/association-type.v1" }, "reason": { "$ref": "#/components/schemas/reason.v1" }, "id": { "$ref": "#/components/schemas/association-id.v1" }, "url": { "$ref": "#/components/schemas/url.v1" } }, "required": [ "type", "id" ] }, "image.v1": { "title": "Association (image)", "type": "object", "properties": { "type": { "$ref": "#/components/schemas/association-type.v1" }, "reason": { "$ref": "#/components/schemas/reason.v1" }, "id": { "$ref": "#/components/schemas/association-id.v1" }, "url": { "$ref": "#/components/schemas/url.v1" } }, "required": [ "type", "id" ] }, "url-association.v1": { "title": "Association (url)", "type": "object", "properties": { "type": { "$ref": "#/components/schemas/association-type.v1" }, "reason": { "$ref": "#/components/schemas/reason.v1" }, "id": { "$ref": "#/components/schemas/association-id.v1" }, "url": { "$ref": "#/components/schemas/url.v1" } }, "required": [ "type", "id", "url" ] }, "association.v1": { "title": "Association", "description": "Associate this resource with another Tidepool resource ID.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/blob.v1" }, { "$ref": "#/components/schemas/datum.v1" }, { "$ref": "#/components/schemas/image.v1" }, { "$ref": "#/components/schemas/url-association.v1" } ] }, "associationarray.v1": { "title": "Association Array", "description": "An array of associations for the resource.", "type": "array", "items": { "$ref": "#/components/schemas/association.v1" } }, "clockdriftoffset.v1": { "title": "Clock Drift Offset", "description": "Clock drift offset, expressed as milliseconds.", "type": "integer", "format": "int64", "minimum": -86400000, "maximum": 86400000, "example": 0, "x-tags": [ "Data" ] }, "conversionoffset.v1": { "title": "Conversion Offset", "description": "Conversion offset, expressed as milliseconds.", "type": "integer", "format": "int64", "example": 0, "x-tags": [ "Data" ] }, "tidepooluserid": { "type": "string", "title": "Tidepool User ID", "pattern": "^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$", "description": "String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit [UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))", "readOnly": true, "x-go-type": "string" }, "semanticversion.v1": { "title": "Semantic Version Number", "description": "[Semantic Version Number 2.0.0](http://semver.org/). Regex from their [site](https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string).", "type": "string", "minLength": 5, "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "example": "2.36.1" }, "reversedomainname.v1": { "title": "Reverse Domain Name", "description": "Name in the [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation).", "type": "string", "pattern": "^[a-zA-Z0-9](|[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])(\\.[a-zA-Z0-9](|[a-zA-Z0-9-]{0,61}[a-zA-Z0-9]))+$", "example": "org.tidepool.uploader" }, "deduplicatordescriptor.v1": { "title": "Deduplicator Descriptor", "type": "object", "properties": { "hash": { "type": "string", "minLength": 1 }, "version": { "$ref": "#/components/schemas/semanticversion.v1" }, "name": { "$ref": "#/components/schemas/reversedomainname.v1" } }, "required": [ "name", "version" ], "x-tags": [ "Data" ] }, "deviceid.v1": { "title": "Device ID", "description": "Globally unique to device and repeatable with each upload, e.g. device make and model with serial number", "type": "string", "minLength": 1, "example": "MMT-1711:12345678", "x-tags": [ "Data" ] }, "datetimenotz.v1": { "title": "Date/Time without Timezone", "description": "[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) / [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp _without_ timezone information", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$", "example": "2017-02-06T02:37:46", "x-go-type": "string" }, "jsonpatch.v1": { "title": "JSONPatch", "oneOf": [ { "properties": { "op": { "type": "string", "description": "The operation to perform.", "enum": [ "add", "replace", "test" ] }, "path": { "type": "string", "description": "A JSON Pointer path." }, "value": { "description": "The value to add, replace or test." } }, "required": [ "op", "path", "value" ] }, { "properties": { "op": { "type": "string", "description": "The operation to perform.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "A JSON Pointer path." } }, "required": [ "op", "path" ] }, { "properties": { "op": { "type": "string", "description": "The operation to perform.", "enum": [ "move", "copy" ] }, "from": { "description": "A JSON Pointer path pointing to the location to move/copy from.", "type": "string" }, "path": { "type": "string", "description": "A JSON Pointer path." } }, "required": [ "op", "from", "path" ] } ], "type": "object", "description": "Only have this here because Stoplight doesn't seem to like using the JSONSchema directly as a ref from http://json.schemastore.org/json-patch" }, "eventhistory.v1": { "title": "Event History [Proposed]", "description": "Revision history of the event", "type": "array", "items": { "type": "object", "properties": { "time": { "$ref": "#/components/schemas/datetime.v1" }, "changes": { "$ref": "#/components/schemas/jsonpatch.v1" } }, "required": [ "time", "changes" ] }, "x-tags": [ "Data" ] }, "origin-id.v1": { "title": "Origin ID", "description": "Any external identifier uniquely identifying the resource at the origin source.", "type": "string", "minLength": 1, "maxLength": 100 }, "name.v1": { "title": "Origin Name", "description": "A human-readable name for the origin source.", "type": "string", "minLength": 1, "maxLength": 100 }, "payload.v1": { "title": "Payload", "description": "Grab bag field for data that isn't yet part of the data model. The maximum size is 4K bytes.", "type": "object", "additionalProperties": true }, "origin-type.v1": { "title": "Origin Type", "description": "The type of the origin source.", "type": "string", "enum": [ "application", "device", "manual", "service" ], "example": "device" }, "version.v1": { "title": "Origin Version", "description": "The version of the origin source at the time the resources was obtained.", "type": "string", "minLength": 1, "maxLength": 100 }, "origin.v1": { "title": "Origin", "description": "External origin information for the source of the resource.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/origin-id.v1" }, "name": { "$ref": "#/components/schemas/name.v1" }, "payload": { "$ref": "#/components/schemas/payload.v1" }, "time": { "$ref": "#/components/schemas/datetime.v1" }, "type": { "$ref": "#/components/schemas/origin-type.v1" }, "version": { "$ref": "#/components/schemas/version.v1" } }, "required": [ "id", "name", "time", "type", "version" ] }, "longitude.v1": { "title": "Longitude", "description": "The prime meridian, which passes near the Royal Observatory, Greenwich, England, is defined as 0° longitude by convention. Positive longitudes are east of the prime meridian, and negative ones are west.", "type": "object", "properties": { "units": { "type": "string", "enum": [ "degrees" ], "example": "degrees" }, "value": { "type": "number", "format": "double", "minimum": -180, "maximum": 180, "example": -122.1625595 } }, "required": [ "units", "value" ] }, "latitude.v1": { "title": "Latitude", "description": "Latitude is an angle which ranges from -90° at the South pole to 0° at the Equator to 90° at the North pole.", "type": "object", "properties": { "units": { "type": "string", "enum": [ "degrees" ], "example": "degrees" }, "value": { "type": "number", "format": "double", "minimum": -90, "maximum": 90, "example": 37.4454404 } }, "required": [ "units", "value" ] }, "meters.v1": { "title": "Accuracy (meters)", "description": "Accuracy of a measurement, expressed as meters.", "type": "object", "properties": { "value": { "type": "number", "format": "double", "minimum": 0, "maximum": 1000, "example": 42 }, "units": { "type": "string", "enum": [ "meters" ], "example": "meters" } }, "required": [ "units" ] }, "accuracy-feet.v1": { "title": "Accuracy (feet)", "description": "Accuracy of a measurement, expressed in `feet`.", "type": "object", "properties": { "value": { "type": "number", "format": "double", "minimum": 0, "maximum": 3280, "example": 42 }, "units": { "type": "string", "enum": [ "feet" ], "example": "feet" } }, "required": [ "units" ] }, "accuracy.v1": { "title": "Accuracy", "description": "Accuracy of a measurement", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/meters.v1" }, { "$ref": "#/components/schemas/accuracy-feet.v1" } ] }, "floor.v1": { "title": "Floor", "type": "integer", "format": "int32", "minimum": -1000, "maximum": 1000 }, "elevation-meters.v1": { "title": "Elevation (meters)", "type": "object", "properties": { "units": { "type": "string", "enum": [ "meters" ], "example": "meters" }, "value": { "type": "number", "format": "double", "minimum": 0, "maximum": 10000, "example": 42 } }, "required": [ "units", "value" ] }, "elevation-feet.v1": { "title": "Elevation (feet)", "type": "object", "properties": { "units": { "type": "string", "enum": [ "feet" ], "example": "feet" }, "value": { "type": "number", "format": "double", "minimum": 0, "maximum": 32808, "example": 42 } }, "required": [ "units", "value" ] }, "elevation.v1": { "title": "Elevation", "description": "Elevation, expressed as `meters` or `feet`.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/elevation-meters.v1" }, { "$ref": "#/components/schemas/elevation-feet.v1" } ] }, "gps.v1": { "title": "GPS", "description": "GPS coordinates and related information.", "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/origin.v1" }, "longitude": { "$ref": "#/components/schemas/longitude.v1" }, "latitude": { "$ref": "#/components/schemas/latitude.v1" }, "horizontalAccuracy": { "$ref": "#/components/schemas/accuracy.v1" }, "verticalAccuracy": { "$ref": "#/components/schemas/accuracy.v1" }, "floor": { "$ref": "#/components/schemas/floor.v1" }, "elevation": { "$ref": "#/components/schemas/elevation.v1" } }, "required": [ "longitude", "latitude" ] }, "location.v1": { "title": "Location", "type": "object", "description": "Location information associated with the resource. One or both of `name` and `gps` must be specified.", "properties": { "name": { "type": "string", "description": "A name for the location.", "minLength": 1, "maxLength": 100 }, "gps": { "$ref": "#/components/schemas/gps.v1" } } }, "note.v1": { "title": "Note", "description": "A note associated with the resource.", "type": "string", "minLength": 1, "maxLength": 1000 }, "notearray.v1": { "title": "Note Array", "description": "An array of 1 to 100 notes.", "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/note.v1" } }, "tag.v1": { "title": "Tag", "description": "A tag associated with the resource.", "type": "string", "minLength": 1, "maxLength": 100 }, "tagarray.v1": { "title": "Tag Array", "description": "An array of tags.", "type": "array", "items": { "$ref": "#/components/schemas/tag.v1" } }, "timezonename.v1": { "title": "Time Zone", "description": "A string timezone name from the [IANA timezone database](https://www.iana.org/time-zones)", "type": "string", "example": "Europe/London", "x-tags": [ "Data" ] }, "timezoneoffset.v1": { "title": "Time Zone offset", "description": "Time zone offset, expressed as positive or negative number of minutes from UTC.", "type": "integer", "format": "int32", "minimum": -10080, "maximum": 10080, "example": -420, "x-tags": [ "Data" ] }, "datatype.v1": { "title": "Tidepool Data Type", "description": "Data type", "type": "string", "enum": [ "alert", "basal", "bloodKetone", "bolus", "cbg", "cgmSettings", "controllerSettings", "controllerStatus", "deviceEvent", "deviceStatus", "dosingDecision", "food", "insulin", "physicalActivity", "pumpSettings", "pumpStatus", "reportedState", "smbg", "upload", "water", "wizard" ], "example": "upload", "x-tags": [ "Data" ] }, "uploadid.v1": { "title": "Upload ID", "description": "An upload identifier; this field should be the uploadId of the corresponding upload record", "type": "string", "pattern": "^([0-9a-f]{32}|upid_[0-9a-f]{12})$", "minLength": 17, "maxLength": 32, "example": "0d92d5c1c22117a18f3620b9e24d3c06", "x-tags": [ "Data" ] }, "base.v1": { "title": "Base", "description": "An abstract base data type for all Tidepool diabetes data objects.", "type": "object", "properties": { "annotations": { "$ref": "#/components/schemas/annotationarray.v1" }, "archivedTime": { "allOf": [ { "$ref": "#/components/schemas/datetime.v1" } ], "readOnly": true }, "archivedDatasetId": { "$ref": "#/components/schemas/datasetid.v1" }, "associations": { "$ref": "#/components/schemas/associationarray.v1" }, "clockDriftOffset": { "$ref": "#/components/schemas/clockdriftoffset.v1" }, "conversionOffset": { "$ref": "#/components/schemas/conversionoffset.v1" }, "createdTime": { "$ref": "#/components/schemas/datetime.v1" }, "createdUserId": { "$ref": "#/components/schemas/tidepooluserid" }, "deduplicator": { "$ref": "#/components/schemas/deduplicatordescriptor.v1" }, "deletedTime": { "$ref": "#/components/schemas/datetime.v1" }, "deletedUserId": { "$ref": "#/components/schemas/tidepooluserid" }, "deviceId": { "$ref": "#/components/schemas/deviceid.v1" }, "deviceTime": { "$ref": "#/components/schemas/datetimenotz.v1" }, "guid": { "type": "string", "description": "A string ID. Added to each event during data processing in the Tidepool Uploader or upon ingestion by the platform data ingestion service.", "deprecated": true }, "history": { "$ref": "#/components/schemas/eventhistory.v1" }, "id": { "$ref": "#/components/schemas/datasetid.v1" }, "location": { "$ref": "#/components/schemas/location.v1" }, "modifiedTime": { "$ref": "#/components/schemas/datetime.v1" }, "modifiedUserId": { "$ref": "#/components/schemas/tidepooluserid" }, "notes": { "$ref": "#/components/schemas/notearray.v1" }, "origin": { "$ref": "#/components/schemas/origin.v1" }, "payload": { "$ref": "#/components/schemas/payload.v1" }, "source": { "type": "string", "enum": [ "carelink" ] }, "tags": { "$ref": "#/components/schemas/tagarray.v1" }, "time": { "$ref": "#/components/schemas/datetime.v1" }, "timezone": { "$ref": "#/components/schemas/timezonename.v1" }, "timezoneOffset": { "$ref": "#/components/schemas/timezoneoffset.v1" }, "type": { "$ref": "#/components/schemas/datatype.v1" }, "uploadId": { "$ref": "#/components/schemas/uploadid.v1" } }, "required": [ "id", "type", "time" ], "x-tags": [ "Data" ] }, "devicemanufacturers.v1": { "title": "Device Manufacturers", "description": "An array of string tags indicating the manufacturer(s) of the device.\n\nIn order to avoid confusion resulting from referring to a single manufacturer with more than one name—for example, using both 'Minimed' and 'Medtronic' interchangeably—we restrict the set of strings used to refer to manufacturers to the set listed above and enforce *exact* string matches (including casing).\n\n`deviceManufacturers` is an array of one or more string \"tags\" because there are devices resulting from a collaboration between more than one manufacturer, such as the Tandem G4 insulin pump with CGM integration (a collaboration between `Tandem` and `Dexcom`).", "type": "array", "items": { "type": "string" }, "example": [ "DeviceCo" ], "x-tags": [ "Data" ] }, "devicemodelname.v1": { "title": "Device Model Name", "description": "A string identifying the model of the device.\n\nThe `deviceModel` is a non-empty string that encodes the model of device.\nWe endeavor to match each manufacturer's standard for how they represent model name in terms of casing, whether parts of the name are represented as one word or two, etc.", "type": "string", "minLength": 1, "example": "Devicey McDeviceface", "x-tags": [ "Data" ] }, "deviceserialnumber.v1": { "title": "Device Serial Number", "description": "A string encoding the device's serial number.\n\nThe `deviceSerialNumber` is a string that encodes the serial number of the device.\nNote that even if a manufacturer only uses digits in its serial numbers, the SN should be stored as a string regardless.\n\nUniquely of string fields in the Tidepool device data models, `deviceSerialNumber` *may* be an empty string.\nThis is essentially a compromise: having the device serial number is extremely important (especially for e.g., clinical studies) but in 2016 we came across our first case where we *cannot* recover the serial number of the device that generated the data: Dexcom G5 data uploaded to Tidepool through Apple iOS's HealthKit integration.", "type": "string", "minLength": 1, "example": "B97B6D59", "x-tags": [ "Data" ] }, "devicetag.v1": { "title": "Device Tag", "description": "Tag indicating the function(s) of a particular device.", "type": "string", "maxLength": 100, "enum": [ "bgm", "cgm", "insulin-pump", "fgm", "pen", "manual" ], "x-tags": [ "Data" ] }, "devicetags.v1": { "title": "Device Tags", "description": "An array of string tags indicating the function(s) of the device.\n\nThe `deviceTags` array should be fairly self-explanatory as an array of tags indicating the function(s) of a particular device.\nFor example, the Insulet OmniPod insulin delivery system has the tags `bgm` and `insulin-pump` since the PDM is both an insulin pump controller and includes a built-in blood glucose monitor.", "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/devicetag.v1" }, "x-tags": [ "Data" ] }, "uploaddevice.v1": { "title": "Upload Device", "description": "The device used to provide diabetes data", "type": "object", "properties": { "deviceManufacturers": { "$ref": "#/components/schemas/devicemanufacturers.v1" }, "deviceModel": { "$ref": "#/components/schemas/devicemodelname.v1" }, "deviceSerialNumber": { "$ref": "#/components/schemas/deviceserialnumber.v1" }, "deviceTags": { "$ref": "#/components/schemas/devicetags.v1" } }, "additionalProperties": false, "default": {}, "x-tags": [ "Data" ] }, "platform.v1": { "title": "Client Software Platform", "description": "The software platform on which the client software was run.", "type": "string", "example": "macOS 10.15.4", "x-tags": [ "Data" ] }, "metadata.v1": { "title": "Metadata", "type": "object", "additionalProperties": true, "x-tags": [ "Data" ] }, "clientsoftware.v1": { "title": "Client Software", "description": "The client software that provided diabetes data.", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/reversedomainname.v1" }, "version": { "$ref": "#/components/schemas/semanticversion.v1" }, "platform": { "$ref": "#/components/schemas/platform.v1" }, "private": { "$ref": "#/components/schemas/metadata.v1" } }, "required": [ "name", "version" ], "x-tags": [ "Data" ] }, "computertime.v1": { "title": "Computer Time", "description": "An ISO 8601 formatted timestamp without any timezone offset information.\n\nThe `computerTime` field encodes the *local* time at upload with no timezone offset information since we are storing `timezone` separately.\nWe store this field in order to be able to audit and/or detect the correspondence between the user's browser time and the timezone they selected at the time of upload.\nIf the user selected the timezone that was actually in effect for their browser at the time of upload, then applying the stored `timezone` to the UTC Zulu `time` field will match `computerTime`.\nIf, on the other hand, the user selected a *different* timezone from that effective in their browser at the time of upload, applying the `timezone` to `time` will *not* match `computerTime`.\n\nThere are some use cases when it is perfectly justified to select a timezone that does *not* reflect the browser's current timezone.\nFor example, some insulin pump users do not change the time on their devices when traveling for short periods of time across many timezones, but when uploading a device a user should always choose the timezone that aligns with the most recent data on the device and thus that will *not* match the local browser timezone.", "type": "string", "format": "time", "x-tags": [ "Data" ] }, "datasettype.v1": { "title": "Data Set Type", "type": "string", "enum": [ "continuous", "normal" ], "example": "continuous", "x-tags": [ "Data" ] }, "timeprocessing.v1": { "title": "Time Processing", "description": "A string indicating what variety of processing was used to create the `time` and related fields such as `timezoneOffset` on data in this upload.\n\nFor data auditing purposes, we store a string encoding the type of algorithm used to generate the `time`, `timezoneOffset`, and other related fields from the local `deviceTime`. At present, there are only three options for this value:\n- `none` for data sources that already include a UTC-anchored `time` value. At present, the *only* data source for which this is true is Dexcom G5 or Dexcom G6 data coming through Apple's iOS HealthKit integration.\n- `across-the-board-timezone` for devices (all BGMs, for example) that cannot have their `deviceTime` values [\"bootstrapped\" to a UTC `time` value](http://developer.tidepool.org/uploader/docs/BootstrappingToUTC.html); in such cases, we apply a single user-selected timezone to every `deviceTime` \"across the board\" to generate the `time` value.\n- `utc-bootstrapping` for devices (most insulin pumps and CGMs) where we use a combination of the user-selected timezone at time of upload, the most recent timestamp on device, and the history of display time changes on the device to infer the correct `time` value for each record.", "type": "string", "enum": [ "none", "across-the-board-timezone", "utc-bootstrapping" ], "example": "utc-bootstrapping", "x-tags": [ "Data" ] }, "upload.v1": { "title": "Upload", "description": "Metadata about an upload of diabetes device data to the Tidepool platform.", "allOf": [ { "$ref": "#/components/schemas/base.v1" }, { "$ref": "#/components/schemas/uploaddevice.v1" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "upload" ] }, "byUser": { "$ref": "#/components/schemas/tidepooluserid" }, "client": { "$ref": "#/components/schemas/clientsoftware.v1" }, "computerTime": { "$ref": "#/components/schemas/computertime.v1" }, "dataSetType": { "$ref": "#/components/schemas/datasettype.v1" }, "timeProcessing": { "$ref": "#/components/schemas/timeprocessing.v1" }, "version": { "$ref": "#/components/schemas/semanticversion.v1" } } } ], "x-tags": [ "Data" ] } } } } ``` ## Type (`type`) This is the Tidepool data type most distinct from all others: instead of encoding diabetes device data, the upload type encodes metadata — about uploads of diabetes device data — to Platform. The fields under this type are: 1. [Quick Summary](#quick-summary) 2. [Type (`type`)](#type-type) 3. [By User (`byUser`)](#by-user-byuser) 4. [Computer Time (`computerTime`)](#computer-time-computertime) 5. [Device Manufacturers (`deviceManufacturers`)](#device-manufacturers-devicemanufacturers) 6. [Device Model (`deviceModel`)](#device-model-devicemodel) 7. [Device Serial Number (`deviceSerialNumber`)](#device-serial-number-deviceserialnumber) 8. [Device Tags (`deviceTags`)](#device-tags-devicetags) 9. [Time Processing (`timeProcessing`)](#time-processing-timeprocessing) 10. [Timezone (`timezone`)](#timezone-timezone) 11. [Upload ID (`uploadId`)](#upload-id-uploadid) 12. [Version (`version`)](#version-version) 13. [Examples](#examples) 14. [Keep Reading](#keep-reading) ## By User (`byUser`) The by user field is provided for data auditing purposes. Since Tidepool provides functionality to share data and data permissions between users — for example, between a clinician and a patient — the user that logged in and performed the device upload may not be the PwD whose data is being uploaded. ## Computer Time (`computerTime`) The computer time field encodes the local time at upload with no timezone offset information (Tidepool stores timezone separately). We store this field to audit and/or detect the correspondence between the user's browser time and the timezone they selected at the time of upload. If the user selected the *correct* timezone for their browser, then the timezone will be converted to UTC Zulu time and then again to computer time (which should match the selected timezone). If, however, the user selected a *different* timezone from that effective in their browser, the computer time and timezone will not match. There are some cases where it is perfectly justified to select a timezone that does not reflect the browser's current timezone. For example, some insulin pump users do not change the time on their devices when traveling for short periods of time across many timezones. When uploading a device, a user should *always* choose the timezone that aligns with the most recent data on the device and therefore (in the previous example) will not match the local browser timezone. ## Device Manufacturers (`deviceManufacturers`) To avoid confusion resulting from referring to a single manufacturer with more than one name — for example, using both "Minimed" and "Medtronic" interchangeably — Tidepool restricts device manufacturer string "tags" to those detailed in the quick summary above and enforces exact string matches (including casing). Device manufacturers is an array of one or more string tags because some devices are the result of manufacturer collaboration, such as the Tandem G4 insulin pump with CGM integration (a collaboration between Tandem and Dexcom). ## Device Model (`deviceModel`) The device model is a non-empty string that encodes the model of device. We endeavor to match each manufacturer's standard for how they represent model name in terms of casing, whether parts of the name are represented as one word or two, etc. ## Device Serial Number (`deviceSerialNumber`) The device serial number is a string that encodes the serial number of the device. > Even if a manufacturer only uses digits in its serial numbers, the serial number should be stored as a string regardless. Having the device serial number is extremely important (especially for clinical studies) and should be included whenever possible. However, if the device serial number is unknown, the device serial number may be an empty string. ## Device Tags (`deviceTags`) The device tags array should be fairly self-explanatory as an array of tags indicating the function/s of a particular device. For example, the Insulet OmniPod insulin delivery system has the tags "bgm" and "insulin-pump" since the PDM (personal diabetes monitor) is both an insulin pump controller and includes a built-in blood glucose monitor. ## Time Processing (`timeProcessing`) For data auditing purposes, Tidepool stores a string encoding the type of algorithm used to generate the time, timezone offset, and other related fields from the local device time. At present, there are only three options for this value: * **Across-the-board-timezone for devices** (all BGMs, for example) that cannot have their device time values "bootstrapped" to a UTC time value. In such cases, we apply a single user-selected timezone to every device time "across the board" to generate the time value. * **UTC-bootstrapping for devices** (most insulin pumps and CGMs) where we use a combination of the user-selected timezone (at time of upload), the most recent timestamp on the device, and the history of display time changes on the device to infer the correct time value for each record. * **None** for data sources that already include a UTC-anchored time value. Currently, the only data source for which this is true is Dexcom G5 data coming through Apple's iOS HealthKit integration. ## Timezone (`timezone`) The timezone is the timezone selected by the user manually in the Chrome uploader at the time of upload, or (in the case of Dexcom G5 data from HealthKit), the timezone reported by the mobile device at the time of upload. > Tidepool uses the Moment Timezone library for the implementation of both UTC-bootstrapping (in Tidepool Uploader) and in Tidepool Web. Moment Timezone includes a copy of the IANA timezone database and is updated frequently, but as Tidepool does not always reguarly update dependencies, the possible values of this field are limited to the string timezone names recognized by the IANA timezone database (included in Tidepool's current version of Moment Timezone). ## Upload ID (`uploadId`) The upload ID is generated and returned by Platform when opening an upload session. The upload ID should be used as part of the URI when adding new data. Upload ID should *not* be used in any POST bodies when uploading to Platform. ## Version (`version`) A string identifying the software version of the uploading client. For Tidepool Uploader, this will be a semver (e.g. `1.25.2`). For other uploading clients such as Tidepool iOS applications, the format includes the namespace and semver of the app (e.g. `org.tidepool.blipnotes:1.25:2`). ## Examples ```json Example (client) { "type": "upload", "byUser": "154bb78230", "computerTime": "2016-06-27T18:09:55", "deviceManufacturers": "Tandems", "deviceModel": "Devicey McDeviceface", "deviceSerialNumber": "11359410", "deviceTags": [ "bgm", "cgm" ], "timeProcessing": "across-the-board-timezone", "timezone": "Europe/London", "uploadId": "SampleUploadId", "version": "0.100.0", "clockDriftOffset": 0, "conversionOffset": 0, "deviceId": "DevId0987654321", "deviceTime": "2016-06-27T18:09:55", "guid": "e46ceaf2-e6af-4eb2-9583-3b6095f44474", "id": "eed794bbf9ec4b118f5e4c158216d45d", "time": "2016-06-28T01:09:55.131Z", "timezoneOffset": -420 } ``` ```json Example (ingestion) { "type": "upload", "byUser": "eda1e15c6a", "computerTime": "2016-06-27T18:09:55", "deviceManufacturers": "Tandems", "deviceModel": "Devicey McDeviceface", "deviceSerialNumber": "B97B6D59", "deviceTags": [ "bgm", "cgm" ], "timeProcessing": "utc-bootstrapping", "timezone": "Europe/London", "uploadId": "SampleUploadId", "version": "0.100.0", "clockDriftOffset": 0, "conversionOffset": 0, "deviceId": "DevId0987654321", "deviceTime": "2016-06-27T18:09:55", "time": "2016-06-28T01:09:55.132Z", "timezoneOffset": -420 } ``` ```json Example (storage) { "type": "upload", "byUser": "e9c6044f37", "computerTime": "2016-06-27T18:09:55", "deviceManufacturers": "Tandems", "deviceModel": "Devicey McDeviceface", "deviceSerialNumber": "59579660", "deviceTags": [ "bgm", "cgm" ], "timeProcessing": "utc-bootstrapping", "timezone": "Europe/London", "uploadId": "SampleUploadId", "version": "0.100.0", "_active": true, "_groupId": "abcdef", "_schemaVersion": 0, "_version": 0, "clockDriftOffset": 0, "conversionOffset": 0, "createdTime": "2016-06-28T01:10:00.132Z", "deviceId": "DevId0987654321", "deviceTime": "2016-06-27T18:09:55", "guid": "42b5f8b1-699a-4c15-ab62-33934791ea7b", "id": "451beb9d69b64bc2a60a1696559f94d1", "time": "2016-06-28T01:09:55.132Z", "timezoneOffset": -420 } ``` ## Keep Reading * [Bolus Calculator](/docs/device-data/data-types/calculator) * [Common Fields](/docs/device-data/common-fields) * [Datetime Guide](/docs/datetime) * [Diabetes Data Types](/docs/device-data/data-types) * [Pump Settings](/docs/device-data/data-types/pump-settings) * [Self-Monitored Glucose (SMBG)](/docs/device-data/data-types/smbg) * [Units](/docs/device-data/units)