Consent

See FHIR specification

Mapping to MIDATA Consents

A consent resource may represent a consent on the MIDATA platform.

Consents on the MIDATA platform need to conform to a profile defined on this page.

If you need to store consents not related to MIDATA see below in the hybrid use section.

Minimal resource content

The minimal resource content looks like this:

{
   "resourceType":"Consent",
   "status": statusValue,
   "scope":{
      "coding":[
         {
            "system":"http://terminology.hl7.org/CodeSystem/consentscope",
            "code": consentScopeValue
         }
      ]
   },
   "policy":[
      {
         "uri":"http://hl7.org/fhir/ConsentPolicy/opt-in"
      }
   ],
   "category":[
      {
         "coding":[
            {
               "system":"http://midata.coop/codesystems/consent-category",
               "code":"my-category"
            }
         ]
      }
   ]
}

The “status” may be one of these values:

  • “proposed” - The consent has not been confirmed by the patient. The patient will be notified and needs to confirm the consent either on the MIDATA portal or using an application.
  • “active” - The consent is active and needs no additional confirmation. In order to create an active consent some preconditons must be satisfied.

Preconditions for creation of an active consent:

  • Application that creates the consent is used by the patient
  • Application has flag “Shares data with 3rd party” set
  • Project has “Participant is registered by external software” enabled.
  • Application may access all data that is shares by this consent
  • Application must be able to read patient resource

For the “policy” only the fixed “uri” with value “http://hl7.org/fhir/ConsentPolicy/opt-in” is supported.

The “scope” may only have “code” with value “patient-privacy” or “research” taken from system “http://terminology.hl7.org/CodeSystem/consentscope”. Other values are not supported.

Identifier references for grantees and the patient

If the id of the target person is known a normal FHIR reference may be used. Otherwise a reference using an identifier may be used. The following code systems are supported for identifier references:

  • “http://midata.coop/identifier/patient-login” - login name (email) of user. The user must already have an MIDATA account.
  • “http://midata.coop/identifier/patient-login-or-invitation” - login name (email) of user. If the user has no MIDATA account an invitation to create one is sent. The consent is automatically bound to the user account once created.
  • “http://midata.coop/identifier/practitioner-login” - login name (email) of practitioner. The practitioner must already have an MIDATA account. (This is a reference to a Practitioner resource)
  • “http://midata.coop/identifier/group-name” - name of a practitioner team on MIDATA. (This is a reference to a Group resource)

The value of the identifier is the login name (email) for persons or team name for groups.

If the logged in user posting the new consent is the patient himself the “patient” may be omitted. Otherwise a FHIR reference must be used as described above.
(For a full example, see at the end of the page.)

 {
   ...
   "patient":{
      "identifier":{
         "system":"http://midata.coop/identifier/patient-login-or-invitation",
         "value":"user@example.com"
      },
      "display":"Example account holder"
   }
   ...
}

The target practitioners must be listed in the “actor” section of the “provision” section. The role must be “GRANTEE”. Practitioner or Group references may be direct resource references or use identifiers as described above.

 {
   ...
   "provision":{
      "type":"permit",
      "actor":[
         {
            "role":{
               "coding":[
                  {
                     "system":"http://hl7.org/fhir/v3/RoleCode",
                     "code":"GRANTEE"
                  }
               ]
            },
            "reference":{
               "identifier":{
                  "system":"http://midata.coop/identifier/practitioner-login",
                  "value":"doctor@example.com"
               },
               "display":"Dr. Mueller"
            }
         }
      ]
   }
   ...
}

The project that the account holder will join can be specified by providing a second category with system “http://midata.coop/codesystems/project-code” and the project code as “code”. If the project to join is given it is not necessary to provide information about what data needs to be shared. This information will be added by the platform automatically based on the research project definition on MIDATA.

 {
   ...
   "category":[
      {
         "coding":[
            {
               "system":"http://midata.coop/codesystems/consent-category",
               "code":"my-category"
            }
         ]
      },
      {
         "coding":[
            {
               "system":"http://midata.coop/codesystems/project-code",
               "code":"JRF5-SF4P"
            }
         ]
      }
   ]
   ...
}

You can provide the MIDATA consent type using the “purpose” field in the “provision” section:

 {
   ...
   "provision":{
      "purpose":[
         {
            "system":"http://midata.coop/codesystems/consent-type",
            "code": consentType
         }
      ]
   }
   ...
}

The following values for consentType are supported:

  • “HEALTHCARE” - A consent where an account holder (Patient) shares data with Practitioners.
  • “STUDYPARTICIPATION” - A consent with scope “research” where an account holder (Patient) shares data with an research project.
  • “CIRCLE” - A consent where an account holder (Patient) shares data with other account holders (Patients).
  • “REPRESENTATIVE” - A consent where an account holder (Patient) gives full rights for his account to another person.

If no “purpose” is provided in the consent the platform tries to automatically determine the consent types “HEALTHCARE”, “STUDYPARTICIPATION” and “CIRCLE” from looking at the “scope” and “actors” of the consent.

The consent type “REPRESENTATIVE” must be explicitly provided. See Managing Delegation for more information.

The data to be shared is specified in the “provision” section of the resource. There are multiple granularities for providing the sharing information

  • A) Detailed list of combinations of FHIR resource types, codings and data source
  • B) (Simple, flat) list of codings to be shared
  • C) direct list of FHIR resource instances to be shared

Detailed list

The provision section of the consent resource may contain nested provision sections. This can be used to provide a detailed list of what data to share. Each “provision” element may select a slice of the available data by using the “class” and “code” field. For “class” entries the following code systems are supported:

  • “http://hl7.org/fhir/resource-types” - restrict by FHIR resource type
  • “http://midata.coop/codesystems/group” - restrict by MIDATA content group
  • “http://midata.coop/codesystems/app” - restrict by source application (use internal application name as “code”)
  • “http://midata.coop/codesystems/content” - restrict by MIDATA content type

For “code” entries directly give the codings as they are used in the resources. See Registered Codes for a list of codes known to MIDATA. For example use “http://loinc.org” as system and “8302-2” as code for resources with code for body height.

The following example selects all Observations with the loinc code “3141-9” in the code field and all Compositions created by the application “demo” with the loinc code “89196-0” in the code field of the Composition.

{
   ...
   "provision":{
      "type":"permit",
      "provision":[
         {
            "type":"permit",
            "class":[
               {
                  "system":"http://hl7.org/fhir/resource-types",
                  "code":"Observation"
               }
            ],
            "code":[
               {
                  "coding":[
                     {
                        "system":"http://loinc.org",
                        "code":"3141-9"
                     }
                  ]
               }
            ]
         },
         {
            "type":"permit",
            "class":[
               {
                  "system":"http://hl7.org/fhir/resource-types",
                  "code":"Composition"
               },
               {
                  "system":"http://midata.coop/codesystems/app",
                  "code":"demo"
               }
            ],
            "code":[
               {
                  "coding":[
                     {
                        "system":"http://loinc.org",
                        "code":"89196-0"
                     }
                  ]
               }
            ]
         }
      ]
   }
   ...
}

(Simple, flat) List of codings

You can provide a (flat) list of codings that the account holder will share with the grantee(s). This is the level of granularity when the consent is created using the MIDATA portal. Example for sharing all resources with Loinc code “3141-9” (Body Weight) and midata.coop code “AllergyIntolerance”. (MIDATA assigns this code to all AllergyIntolerance FHIR resources)

 {
   ...
   "provision": {
      "type":"permit",
      "code":[
         {
            "coding":[
               {
                  "system":"http://loinc.org",
                  "code":"3141-9"
               }
            ]
         },
         {
            "coding":[
               {
                  "system":"http://midata.coop",
                  "code":"AllergyIntolerance"
               }
            ]
         }
      ]
   }
   ...
}

Instead of codings it is also possible to provide a list of MIDATA content “groups” to be shared: This following example shares all resources (not restricted to resource type) that are in the MIDATA record tree in the “movement” part of the record tree. (Note that this uses the “class” field instead of the “code” field!)

{
   ...
   "provision": {
      "type":"permit",
      "class":[
         {
            "coding":[
               {
                  "system":"http://midata.coop/codesystems/group",
                  "code":"movement"
               }
            ]
         }
      ]
   }
   ...
}

List of resource instances

You can provide a list of FHIR resource instances that shall be shared. This example shares the Observation with id “12345” and the “Condition” with id “23456”. The only supported value for “meaning” is “instance”.

{
   ...
   "provision":{
      "type":"permit",
      ...
      "data":[
         {
            "meaning":"instance",
            "reference":{
               "reference":"Observation/12345"
            }
         },
         {
            "meaning":"instance",
            "reference":{
               "reference":"Condition/23456"
            }
         }
      ]
   }
   ...
}

Restricting by time

A MIDATA consent may have an expiration date and a date after which shared data is frozen (the grantee always sees the data as it was at the freeze time)

Expiration time may be provided using the “period.end” field in the provision section. Data freeze time may be provided using the “dataPeriod.end” field in the provision section.

{
   ...
   "provision":{
      {
         "period":{
            "end" : "2023-01-01"
         },
         "dataPeriod":{
            "end" : "2022-06-30"
         }            
      }
   ]
   ...
}

Adding a category

You can providing a category for the consent using the code system “http://midata.coop/codesystems/consent-category”. You can then use the category code for searching consents by category. You can also define email messages to be automatically sent by the platform for each category of consent seperately.

{
   ...
   "category":[
      {
         "coding":[
            {
               "system":"http://midata.coop/codesystems/consent-category",
               "code":"my-category"
            }
         ]
      }
   ]
   ...
}

The title of the consent as shown in the MIDATA portal may be provided using a FHIR extension:

{
   ...
   "extension":[
      {
         "url":"http://midata.coop/extensions/consent-name",
         "valueString": titleForConsent         
      }
   ]
   ...
}

Hybrid use

This FHIR resource may be used in two different ways on the MIDATA platform. It may be used as a “normal” FHIR resource in order to store data or it may be used as part of built-in functionality of the platform. In the later case each instance of the resource corresponds to an entity of the platform.

Semantical type

The semantical type is “documents/patient-consent” if the resource is used for data storage without additional platform logic. Otherwise the semantical type is “Consent”.

If you need access to this FHIR resource you need to add either one or both of the content types to the access filter.

If an instance of the Consent FHIR resource is treated as normal FHIR resource or with MIDATA platform logic is based on the resource content.

The differentiation between MIDATA and non-MIDATA consents is done based on these rules:

  • If the consent contains a category with the code system “http://midata.coop/codesystems/consent-category” it is treated as MIDATA consent.
  • If the consent contains a purpose with the code system “http://midata.coop/codesystems/consent-type” it is treated as MIDATA consent.
  • If the request is not for at least FHIR R4 it is treated as MIDATA consent.
  • If non of the above applies the resource is treated as a normal data resource.

Read

Read a single Consent by id.

Request:

[GET] /fhir/Consent/<id>

Read specific version

Read a specific version of a single Consent by id.

Request:

[GET] /fhir/Consent/<id>/_history/<version>

Retrieve history

Retrieve all versions of a single resource.

Request:

[GET] /fhir/Consent/<id>/_history

Search for resources of type Consent

Request:

[GET] /fhir/Consent?searchParams

List of supported search parameters:

Supported query parameters:

Name Type Description
_id string The resource identity
_lastUpdated date Only return resources which were last updated as specified by the given range
_page string  
action token Actions controlled by this consent
actor reference Resource for the actor (or group, by role)
category token Classification of the consent statement - for indexing/retrieval
consentor reference Who is agreeing to the policy and exceptions
data reference The actual data reference
date date When this Consent was created or indexed
identifier token Identifier for this record (external references)
organization reference Custodian of the consent
patient reference Who the consent applies to
period date Period that this consent applies
purpose token Context of activities for which the agreement is made
securitylabel token Security Labels that define affected resources
source reference Source from which this consent is taken
status token draft - proposed - active - rejected - inactive - entered-in-error

Create

Create a new resource of type Consent. Creating a consent resource means creating a new consent on MIDATA.

Request:

[POST] /fhir/Consent

Example: Creating a new project participation

Preconditions:

  • Application that creates the consent is used by the patient
  • Application has flag “Shares data with 3rd party” set
  • Project has “Participant is registered by external software” enabled.
  • Application may access all data that is required for the project
  • Application must be able to read patient resource
{
   "resourceType":"Consent",
   "status":"active",
   "scope":{
      "coding":[
         {
            "system":" http://terminology.hl7.org/CodeSystem/consentscope",
            "code":"research"
         }
      ]
   },
   "category":[
      {
         "coding":[
            {
               "system":"http://midata.coop/codesystems/consent-category",
               "code":"my-category"
            }
         ]
      },
      {
         "coding":[
            {
               "system":"http://midata.coop/codesystems/project-code",
               "code":"JRF5-SF4P"
            }
         ]
      }
   ],
   "policy":[
      {
         "uri":"http://hl7.org/fhir/ConsentPolicy/opt-in"
      }
   ],
   "provision":{
      "purpose":[
         {
            "system":"http://midata.coop/codesystems/consent-type",
            "code":"STUDYPARTICIPATION"
         }
      ]
   }
}

{
   "resourceType":"Consent",
   "status":"proposed",
   "scope":{
      "coding":[
         {
            "system":" http://terminology.hl7.org/CodeSystem/consentscope",
            "code":"patient-privacy"
         }
      ]
   },
   "category":[
      {
         "coding":[
            {
               "system":"http://midata.coop/codesystems/consent-category",
               "code":"my-category"
            }
         ]
      }
   ],
   "policy":[
      {
         "uri":"http://hl7.org/fhir/ConsentPolicy/opt-in"
      }
   ],
   "patient":{
      "identifier":{
         "system":"http://midata.coop/identifier/patient-login-or-invitation",
         "value":"fhir.user2@byom.de"
      },
      "display":"Fhir User 2"
   },
   "provision":{
      "type":"permit",
      "actor":[
         {
            "role":{
               "coding":[
                  {
                     "system":"http://hl7.org/fhir/v3/RoleCode",
                     "code":"GRANTEE"
                  }
               ]
            },
            "reference":{
               "identifier":{
                  "system":"http://midata.coop/identifier/practitioner-login",
                  "value":"fhir.doctor1@byom.de"
               },
               "display":"Dr. Mueller"
            }
         }
      ],
      "purpose":[
         {
            "system":"http://midata.coop/codesystems/consent-type",
            "code":"HEALTHCARE"
         }
      ],
      "provision":[
         {
            "type":"permit",
            "class":[
               {
                  "system":"http://hl7.org/fhir/resource-types",
                  "code":"Observation"
               }
            ],
            "code":[
               {
                  "coding":[
                     {
                        "system":"http://loinc.org",
                        "code":"3141-9"
                     },
                     {
                        "system":"http://loinc.org",
                        "code":" 29463-7"
                     }
                  ]
               }
            ]
         },
         {
            "type":"permit",
            "data":[
               {
                  "meaning":"instance",
                  "reference":{
                     "reference":"Observation/12345"
                  }
               }
            ]
         }
      ]
   }
}

Update

Updates a resource of type Consent. Currently only the status and information that is not used by the platform may be updated.

Request:

[PUT] /fhir/Consent/<id>