[BACK-1913] Add sample interval and backfilled to cbg data type

docs/device-data/data-types/cbg.md

@@ -27,13 +27,32 @@ The device time field is only optional for *this* data type. This is because Tid
 
 ---
 
+## Sample Interval (`sampleInterval`)
+
+With the latest generation of continuous glucose monitors, different devices may support different intervals between glucose samples. For example, every 5 minutes or every 15 minutes between glucose samples. In fact, some newer devices may even report multiple sample intervals from different glucose data streams. For example, a device that reports both 1-minute and 5-minutes glucose samples. 
+
+In order to distinguish between sample intervals and to assist with accurate statistical calculations, the `sampleInterval` should be specified, if it is known. The value must be an integer representing number of milliseconds between samples for the data stream that a datum belongs to. For example, if a device reports both 1-minute and 5-minute samples, then the upload would contain some `cbg` data with a sample interval of 60000 (milliseconds in 1 minute) and others with a sample interval of 300000 (milliseconds in 5 minutes). The typical sample intervals are 60000 (milliseconds in 1 minute), 300000 (milliseconds in 5 minutes), and 900000 (milliseconds in 15 minutes).
+
+While this field is optional, it is strongly encouraged to provide this field, assuming definitive information regarding sample interval is available from the device.
+
+---
+
+## Backfilled (`backfilled`)
+
+The backfilled field, an optional boolean, is used to indicate whether this datum was backfilled from the continuous glucose monitor sensor to the device capturing the data. For example, if the CGM sensor is out-of-range of the mobile phone capturing the data, then when the CGM sensor comes back in-range of the mobile phone, the historic sensor data (while the CGM sensor was out-of-range) is "backfilled" to the mobile phone. If it is definitively known that this datum was indeed backfilled, then this field should be set to `true`. If it is definitely known that this datum was **not** backfilled, then this field should be set to `false`. If it is not definitely known one-way-or-the-other, then this field should **not** be specified.
+
+While this field is optional, it is strongly encouraged to provide this field, assuming definitive information regarding backfill is available from the device.
+
+---
+
 ## Examples
 
 ```json title="Example (client)" lineNumbers=true
 {
     "type": "cbg",
     "units": "mmol/L",
     "value": 3.996538553552784,
+    "sampleInterval": 300000,
     "clockDriftOffset": 0,
     "conversionOffset": 0,
     "deviceId": "DevId0987654321",
@@ -51,6 +70,7 @@ The device time field is only optional for *this* data type. This is because Tid
     "type": "cbg",
     "units": "mg/dL",
     "value": 421,
+    "sampleInterval": 60000,
     "clockDriftOffset": 0,
     "conversionOffset": 0,
     "deviceId": "DevId0987654321",
@@ -66,6 +86,7 @@ The device time field is only optional for *this* data type. This is because Tid
     "type": "cbg",
     "units": "mmol/L",
     "value": 27.25417263603357,
+    "sampleInterval": 300000,
     "_active": true,
     "_groupId": "abcdef",
     "_schemaVersion": 0,

docs/device-data/oor-values.md

@@ -22,6 +22,7 @@ For example, for a low CGM reading for a device that displays in mg/dL with a lo
   "type": "cbg",
   "units": "mg/dL",
   "value": 39,
+  "sampleInterval": 300000,
   "clockDriftOffset": 0,
   "conversionOffset": 0,
   "deviceId": "DevId0987654321",
@@ -56,6 +57,7 @@ For example, for a high CGM reading for a device that displays in mmol/L with a
   "type": "cbg",
   "units": "mmol/L",
   "value": 23.035604162838963,
+  "sampleInterval": 300000,
   "clockDriftOffset": 0,
   "conversionOffset": 0,
   "deviceId": "DevId0987654321",

docs/partner-integration.md

@@ -60,13 +60,15 @@ In addition to the common data fields listed above, Tidepool expects to receive
 | Unit        | `mg/dL` or `mmol/L`                 | `units`                   | `mg/dL`    |
 | Value       | Glucose measurement value, in units | `value`                   | `120`      |
 
-CGM API can optionally also provide Trend information, such as:
+CGM API can optionally also provide Trend and other Sample information, such as:
 
 | Description     | Notes                                                             | Tidepool Data Model Field | Example(s)     |
 | --------------- | ----------------------------------------------------------------- | ------------------------- | -------------- |
 | Trend           | Text representation of the trend                                  | `trend`                   | `moderateRise` |
 | Trend Rate      | Numerical representation of the trend rate                        | `trendRate`               | `2`            |
 | Trend Rate Unit | Unit for the trend rate; default is sample value unit per minutes | `trendRateUnit`           | `mg/dL/min`    |
+| Sample Interval | Sample interval for data; integer, optional, milliseconds         | `sampleInterval`          | `300000`       |
+| Backfilled      | Whether data was backfilled from sensor device; boolean, optional | `backfilled`              | `true`         |
 
 ### Insulin Delivery Devices (Pumps, Pens)
 

docs/quick-start/uploading-device-data/continuous.md

@@ -157,6 +157,7 @@ As an example, uploading a couple of continuous blood glucose (CBG) records migh
       "type": "cbg",
       "value": 119,
       "units": "mg/dL",
+      "sampleInterval": 300000,
       "origin": {
         "id": "06b10116-e85c-4abe-8a35-4eca838bd484",
         "name": "com.apple.HealthKit",
@@ -176,6 +177,7 @@ As an example, uploading a couple of continuous blood glucose (CBG) records migh
       "type": "cbg",
       "value": 120,
       "units": "mg/dL",
+      "sampleInterval": 300000,
       "origin": {
         "id": "1c26886a-ae52-4e43-84cf-5047afe3efc3",
         "name": "com.apple.HealthKit",

docs/quick-start/uploading-device-data/normal.md

@@ -147,6 +147,7 @@ As an example, uploading a couple of continuous blood glucose (CBG) records migh
       "type": "cbg",
       "value": 119,
       "units": "mg/dL",
+      "sampleInterval": 300000,
       "payload": {
         "interstitialSignal": 24.98
       }
@@ -161,6 +162,7 @@ As an example, uploading a couple of continuous blood glucose (CBG) records migh
       "type": "cbg",
       "value": 120,
       "units": "mg/dL",
+      "sampleInterval": 300000,
       "payload": {
         "interstitialSignal": 25.22
       }

reference/data/models/blood/continuousglucose.v1.yaml

@@ -12,6 +12,10 @@ allOf:
         $ref: './glucose/trend.v1.yaml'
       trendRate:
         $ref: './glucose/trendrate.v1.yaml'
+      sampleInterval:
+        $ref: './glucose/sampleinterval.v1.yaml'
+      backfilled:
+        $ref: './glucose/backfilled.v1.yaml'
     required:
       - type
   - $ref: './glucose/glucose.v1.yaml'

reference/data/models/blood/glucose/backfilled.yaml

@@ -0,0 +1,4 @@
+title: Glucose Backfilled
+type: boolean
+x-tags:
+  - Data

reference/data/models/blood/glucose/sampleinterval.v1.yaml

@@ -0,0 +1,7 @@
+title: Glucose Sample Interval
+type: number
+format: int32
+minimum: 0
+maximum: 86400000
+x-tags:
+  - Data