tidepool-org · darinkrauss · Feb 7, 2025
diff --git a/docs/device-data/data-types/cbg.md b/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 samples. For example, every 5 minutes or every 15 minutes between samples. In fact, some newer devices may even report multiple sample intervals from different data streams. For example, a device that reports data from both 1-minute samples and 5-minutes samples. 
+
+In order to distinguish between sample intervals and to assist with accurate statisitical calculations, the `sampleInterval` must be specified. The value must be an integer representing number of milliseconds between samples for the data stream that this datum belongs to. For example, if a device reports both 1-minute and 5-minute sample data, 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 1500000 (milliseconds in 15 minutes).
+
+While this field and value are currently optional in the API implementation, this field will be required in the relatively near future (as of 2025-02-07), so it is marked as such here.
+
+---
+
+## 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 value is optional, this field will actively be used in the relatively near future (as of 2025-02-07), so it is highly recommended to support this field as soon as possible, 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,

diff --git a/docs/device-data/oor-values.md b/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",

diff --git a/docs/partner-integration.md b/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)
 

diff --git a/docs/quick-start/uploading-device-data/continuous.md b/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",

diff --git a/docs/quick-start/uploading-device-data/normal.md b/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
       }

diff --git a/reference/data/models/blood/continuousglucose.v1.yaml b/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'

diff --git a/reference/data/models/blood/glucose/backfilled.yaml b/reference/data/models/blood/glucose/backfilled.yaml
@@ -0,0 +1,4 @@
+title: Glucose Backfilled
+type: boolean
+x-tags:
+  - Data
diff --git a/reference/data/models/blood/glucose/sampleinterval.v1.yaml b/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