FHIR CI-Build

This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon

8.3 Resource Group - Content

FHIR Infrastructure icon Work GroupMaturity Level: 3 Trial UseSecurity Category: Business Compartments: Device, Patient, Practitioner

Represents a defined collection of entities that may be discussed or acted upon collectively but which are not typically expected to act collectively. These collections are also not typically formally or legally recognized.

NOTE: Group may be used to define families or households, which in some circumstances may act collectively or have a degree of legal or formal recognition. This should be considered an exception. When Group is used for types of entities other than Patient or RelatedPerson, the expectation remains that the Group will not act collectively or have formal recognition - use Organization if these behaviors are needed.

For example, it is possible for a 'family' Group to be a performer of an Observation or owner of a Task. However, this is not permitted for a Group made up of Practitioners, PractitionerRoles or Organizations. Organization or CareTeam would need to be used instead. A Group of Practitioners could, however, be a subject of an Observation.

8.3.1 Scope and Usage

8.3.1.1 Use Cases

The Group resource is used in one of two ways:

  1. To define a group of specific people, animals, devices, etc. that is being tracked, examined, acting collectively or otherwise referenced as part of healthcare-related activities
  2. To define a set of possible people, animals, devices, etc. that are of interest for some intended future healthcare-related activities

Examples of the former could include a family, a household, or group therapy or treatment sessions, exposed entities tracked as part of public health, etc. The latter might be used to define expected subjects for a clinical study.

Both use cases are handled by a single resource because the data elements captured tend to be similar.

NOTE: While Specimen does not quite fit with this definition, it is being retained as part of Group to avoid making a breaking change to the Observation resource.

8.3.2 Boundaries and Relationships

There are a number of mechanisms in FHIR for communicating collections of resources:

  • The List resource - enumerates a flat collection of resources and provides features for managing the collection. While a particular List instance may represent a "snapshot", from a business process perspective the notion of "List" is dynamic – items are added and removed over time. The List resource references other resources. Lists may be curated and have specific business meaning. For use cases where Group is suitable (e.g. for a list of Patients to be viewed on a dashboard), the Group resource should be preferred to the List resource. The underlying rationale is that a collection of patients, practitioners, etc. is likely to be of interest as the subject of a measure, observation, communication, etc., which Group is intended to support.
  • This Group resource - defines a group of specific people, animals, devices etc. by enumerating them, or by describing qualities that group members have. The group resource refers to other resources, possibly implicitly. Groups are intended to be acted upon or observed as a whole; e.g. performing therapy on a group, calculating risk for a group, etc. This resource will commonly be used for public health (e.g. describing an at-risk population), clinical trials (e.g. defining a test subject pool) and similar purposes.
  • CareTeam. Group is distinct from CareTeam. Group is patient-independent and identifies an undifferentiated set of individuals who are intended to be the target of one or more clinical activities (e.g. set of clinical trial participants, set of individuals impacted by or at risk of a public health event, a herd or flock, etc.) The CareTeam resource establishes a set of relationships and roles and is specific to a particular Patient. The actors are the individual members or organized group of individuals. CareTeam can be referenced by EpisodeOfCare, Encounter, or CarePlan to identify the set of individuals (and their respective roles) who are intended to be involved in providing the care defined by those resources. Groups containing practitioners are not allowed to perform actions for patient care.
  • The Bundle resource - is an infrastructure container for a group of resources. It does not have narrative and is used to group collections of resources for transmission, persistence or processing (e.g. messages, documents, transactions, query responses, etc.) The content of bundles is typically algorithmically determined for a particular exchange or persistence purpose.
  • The Composition resource - defines a set of healthcare-related information that is assembled together into a single logical document that provides a single coherent statement of meaning, establishes its own context and that has clinical attestation with regard to who is making the statement. The composition resource provides the basic structure of a FHIR document. The full content of the document is expressed using a bundle. Compositions will often reference Lists as the focus of particular sections.
  • The DomainResource.contained element - allows multiple resources to be nested inside any DomainResource. This is a special type of grouping where the grouped resources lose independent existence - they no longer have their own identifiers, can't easily be queried independently, etc. Use of this grouping is a technical mechanism for managing the independence of resources and has no impact on meaning.

8.3.3 References to this Resource

8.3.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Group TU DomainResource Group of multiple entities
+ Rule: Group.type SHALL be defined if Group.membership is either 'definitional' or 'enumerated'

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
... url ΣC 0..1 uri Canonical identifier for this Group, represented as an absolute URI (globally unique)
+ Warning: URL should not contain | or # - these characters make processing canonical references problematic
... identifier Σ 0..* Identifier Business Identifier for this Group

... version Σ 0..1 string Business version of the Group
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name Σ 0..1 string Label for Group
... title Σ 0..1 string Name for this Group (human friendly)
... status ?!Σ 0..1 code draft | active | retired | unknown
Binding: PublicationStatus (Required)
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher

... description 0..1 markdown Natural language description of the group
... useContext Σ 0..* UsageContext The context that the content is intended to support

... purpose 0..1 markdown Why this Group is defined
... copyright 0..1 markdown Use and/or publishing restrictions
... copyrightLabel T 0..1 string Copyright holder and year(s)
... type Σ 0..1 code person | animal | practitioner | device | careteam | healthcareservice | location | organization | relatedperson | specimen | medication | substance | biologicallyDerivedProduct | nutritionProduct
Binding: Group Type (Required)
... membership Σ 1..1 code definitional | conceptual | enumerated
Binding: Group Membership Basis (Required)
... code Σ 0..1 CodeableConcept Use of the Group (and by implication, kind of members)
Binding: Group Code (Extensible)
... quantity Σ 0..1 unsignedInt Number of members
... managingEntity Σ 0..1 Reference(Organization | RelatedPerson | Practitioner | PractitionerRole) Entity that is the custodian of the Group's definition
... combinationMethod ?!Σ 0..1 code all-of | any-of | at-least | at-most | except-subset
Binding: Group Characteristic Combination (Required)
... combinationThreshold 0..1 positiveInt Provides the value of "n" when "at-least" or "at-most" codes are used
... characteristic Σ 0..* BackboneElement Include / Exclude group members by Trait

.... code Σ 1..1 CodeableConcept Kind of characteristic
Binding: Example Characterist ic Codes (Example)
.... value[x] Σ 1..1 Value held by characteristic
..... valueCodeableConcept CodeableConcept
..... valueBoolean boolean
..... valueQuantity Quantity
..... valueRange Range
..... valueReference Reference()
..... valueUri uri
..... valueExpression Expression
.... exclude Σ 1..1 boolean Group includes or excludes
.... description 0..1 markdown Natural language description of the characteristic
.... method 0..* CodeableConcept Method for how the characteristic value was determined
Binding: Definition Method (Example)

.... determinedBy[x] 0..1 Defines the characteristic
..... determinedByReference Reference(Device | DeviceDefinition | DeviceMetric)
..... determinedByExpression Expression
.... offset ?!Σ 0..1 CodeableConcept Reference point for comparison
Binding: Characteristic Offset (Example)
.... instances[x] C 0..1 Number of occurrences meeting the characteristic
+ Rule: Ranges have to be positive
..... instancesUnsignedInt unsignedInt
..... instancesRange Range
.... duration[x] 0..1 Length of time in which the characteristic is met
..... durationDuration Duration
..... durationRange Range
.... period 0..1 Period Period over which characteristic is tested
.... timing 0..* RelativeTime Timing in which the characteristic is determined

... member 0..* BackboneElement Who or what is in group

.... entity 1..1 Reference(CareTeam | Device | Group | HealthcareService | Location | Organization | Patient | Practitioner | PractitionerRole | RelatedPerson | Specimen | Medication | Substance | BiologicallyDerivedProduct | NutritionProduct) Reference to the group member
.... involvement 0..* CodeableConcept Code that describes how user is part of the group
Binding: Group Involvement (Example)

.... period 0..1 Period Period member belonged to the group
.... inactive 0..1 boolean If member is no longer in group

doco Documentation for this format icon

See the Extensions for this resource

 

Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) , the spreadsheet version & the dependency analysis

8.3.4.1 Terminology Bindings

Path ValueSet Type Documentation
Group.versionAlgorithm[x] VersionAlgorithm Extensible

Indicates the mechanism used to compare versions to determine which is more current.
Group.status PublicationStatus Required

The lifecycle status of an artifact.
Group.type GroupType Required

Types of resources that are part of group.
Group.membership GroupMembershipBasis Required

Basis for membership in a group
Group.code GroupCode (a valid code from Group Type) Extensible

A code that describes the use of the group. The use of the group usually dictates what kind of entities can be members of the group
Group.combinationMethod GroupCharacteristicCombination Required

Logical grouping of characteristics for the Group Resource.
Group.characteristic.code ExampleCharacteristicCodes Example

This value set contains an example set of LOINC codes that might be used to define common characteristics for grouping individuals in FHIR Group resources.
Group.characteristic.method DefinitionMethod Example

The method used to define, describe, or determine a characteristic value.
Group.characteristic.offset CharacteristicOffset Example

Reference point for characteristic.valueQuantity.
Group.member.involvement GroupInvolvement Example

A code that describes how a member of the group participates in the group.

8.3.4.2 Constraints

UniqueKeyLevelLocationDescriptionExpression
img cnl-1Warning Group.urlURL should not contain | or # - these characters make processing canonical references problematicexists() implies matches('^[^|# ]+$')
img grp-1Rule Group.characteristic.instances[x]Ranges have to be positive($this is Range) implies ((low.empty() or ((low.code.exists() or low.value.empty()) and (low.system.empty() or low.system = %ucum) and (low.code.empty() or low.code = '1') and (low.value.empty() or low.value.hasValue().not() or low.value.toString().contains('.').not()) and (low.value.empty() or low.value.hasValue().not() or low.value >= 0))) and (high.empty() or ((high.code.exists() or high.value.empty()) and (high.system.empty() or high.system = %ucum) and (high.code.empty() or high.code = '1') and (high.value.empty() or high.value.hasValue().not() or high.value.toString().contains('.').not()) and (high.value.empty() or high.value.hasValue().not() or high.value >= 0))))
img cnl-2Rule (base)Group.type SHALL be defined if Group.membership is either 'definitional' or 'enumerated'Group.type.exists() or (Group.membership = 'conceptual')

8.3.4.3 Mixing Characteristics and Members

If both Group.characteristic and Group.member are present, then the members are the individuals who were found who met the characteristic. It's possible that there might be other candidate members who meet the characteristic and aren't (yet) in the list. All members SHALL have the listed characteristics.

8.3.4.4 Managing large Groups

For operations to assist in adding to, removing from, or filtering contents of large Groups, see Operations for Large Resources.

8.3.4.5 Membership

Membership testing is used to test for active members of a Group. At a minimum, servers supporting membership testing on Group resources SHALL be able to correctly identify active enumerated entities. Active enumerated entities in a group are entities:

  • listed in Group.member.entity,
  • that do not have Group.member.inactive with a value of true, and
  • do not have an expired Group.member.period (e.g., either the element is not present or has a period covering 'now').

Membership testing MAY also be applied to characteristic-defined Groups. If supported, membership testing is based on the characteristic testing of the Group. Any entity meeting the required characteristics is considered to be active.

Servers SHOULD declare whether they support only the enumerated or characteristic group filters. Servers MAY impose additional membership constraints (e.g. based on modifier extensions).

8.3.4.6 Relationships inside the group

Some systems may track detailed family relationship codes (e.g. child, mother, grandfather) within a group rather than merely saying "family member". There are a few options to support conveying such information:

  • Instances of the PersonalRelationship resource can be used to indicate relationships between group members. Such relationships can be leveraged independent of the participants' involvement of the group
  • More detailed family relationship codes (e.g. from the [Personal Relationship RoleType Valueset](https://terminology.hl7.org/6.0.2/ValueSet-v3-PersonalRelationshipRoleType.html)) MAY be sent as additional Codings in the Group.member.involvement element. These SHOULD also be accompanied by the 'family-member' code to support systems that might not understand more detailed codes. If this is done, then the relationship codes are interpreted as being with respect to whichever group member is designated as "head of household"/"primary contact". If there is no such group member explicitly designated, then the nature of the more detailed personal relationship codes cannot reliably be interpreted.

8.3.5 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource, and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name Type Description Expression In Common
characteristic token Kind of characteristic Group.characteristic.code
characteristic-reference reference An entity referenced in a characteristic (Group.characteristic.value.ofType(Reference))
characteristic-value composite A composite of both characteristic and value On Group.characteristic:
  characteristic: code
  value: (value.ofType(CodeableConcept)) | (value.ofType(boolean))
code token The kind of resources contained Group.code
exclude token Group includes or excludes Group.characteristic.exclude
identifier token Unique id Group.identifier 35 Resources
managing-entity reference Entity that is the custodian of the Group's definition Group.managingEntity
(Practitioner, Organization, PractitionerRole, RelatedPerson)
member reference Reference to the group member Group.member.entity
(Group, Organization, CareTeam, BiologicallyDerivedProduct, Device, Patient, HealthcareService, PractitionerRole, RelatedPerson, Practitioner, Specimen, NutritionProduct, Medication, Substance, Location)
membership token Definitional or enumerated group Group.membership
name string A portion of the Group's name Group.name 28 Resources
status token The current status of the Group Group.status 35 Resources
type token The type of resources the group contains Group.type
url uri The uri that identifies the Group Group.url 34 Resources
value token Value held by characteristic (Group.characteristic.value.ofType(CodeableConcept)) | (Group.characteristic.value.ofType(boolean))