NB: This document only describes the suppressed field on temp and suspend basal intervals ingested through the legacy "jellyfish" data ingestion service. If your concern is working with all of Tidepool's production data—both that ingested through the legacy "jellyfish" service and the data ingested through the new platform data ingestion service—in a client application, then you will also want to familiarize yourself with the new suppressed specification.
Note that there is presently no dedicated marker to indicate which service a datum was ingested through, the new platform service or the legacy jellyfish service. However, it is possible to determine this for some data by the make of device: no Animas data has ever been ingested through the jellfish service, and to date the data from all other makes of insulin pump (Insulet, Medtronic via CareLink integration, Tandem) have and do only get ingested through the legacy jellyfish service.
In the near future, after we release support for data ingestion through Medtronic's device communications protocols (instead of via CareLink), it may no longer be possible to conclusively determine the service a datum was ingested through via the device make. When this comes to pass, we recommend that client software attempt to treat all data as if it were ingested through the new platform service and simply drop or ignore fields (such as suppressed) and/or sub-fields (such as some of those inside suppressed) that do not match the current data model specification as found in this documentation.
the legacy suppressed field
The most important thing to be aware of when looking at the suppressed field on temp and/or suspend basals ingested via the legacy jellyfish service is that jellyfish did not (and does not) validate this field at all other than to require that if this optional field is present, it must be an object.
Due to this very lax "validation," you can expect to see some variation with respect to what suppressed looks like on jellyfish-ingested basals. What follows are descriptions of two known variations from the new suppressed specification, but there may be many more.
additional fields present within suppressed
The new specification for suppressed allows only a small number of the fields found on a top-level basal object to appear on the suppressed embedded basal object, with all of those not specified on the embedded object—such as time and duration, among many others—omitted due to equivalence with the parent basal. In contrast, a suppressed on a basal ingested through the jellyfish service can be expected to have all (or almost all) of the fields a normal basal has, and when the time-related fields such as time and duration are present they often do not match the parent basal's, although they should. This occurs with the greatest regularity when a temp basal crosses one or more basal schedule boundaries; often the code clones the original scheduled basal as the suppressed for each temp segment, preserving a time, duration, etc. on the suppressed from the scheduled that are no longer accurate. (Instead of adding in code to update these fields in the suppressed, we made the choice in the new specification to simply avoid doubly specifying shared fields.)
many levels of nested suppressed
In contrast to the new specification, in which an edited temp basal is considered a cancellation of the previous followed by the programming of a new temp, the data ingestion code that targets the jellyfish ingestion service allows a temp to suppress another temp. Hence there are cases of temps with many many layers of nesting inside the suppressed field either due to a bug in the code that splits temps crossing basal schedule boundaries into segments or due to the actual presence of many closely sequential or edited temps (such as may be scheduled by an open-source closed loop system). A rather extreme example of one of these can be observed in this gist. We advise to ignore anything in such a case that does not match the revised specification—all but the top suppressed in the case of a temp, or two layers deep (potentially) with a suspend that suppresses a temp, which in turn suppresses a scheduled.