R6 Ballot (2nd Draft)

Publish-box (todo)

2.2 Resource Basic - Content

FHIR Infrastructure icon Work GroupMaturity Level: 3 Trial UseSecurity Category: Not Classified Compartments: Patient, Practitioner, RelatedPerson

Basic is used for handling concepts not yet defined in FHIR, narrative-only resources that don't map to an existing resource, and custom resources not appropriate for inclusion in the FHIR specification.

2.2.1 Scope and Usage

Basic is a special type of resource. Unlike all other resources, it doesn't correspond to a specific pre-defined HL7 concept. Instead, it's a placeholder for any resource-like concept that isn't already defined in the HL7 specification.

The Basic resource is intended for use in three circumstances:

  1. When an implementer needs a resource concept that is likely to be defined by HL7 in the future but they have not yet done so (due to bandwidth issues, lack of sufficient requirements, lower prioritization, etc.)
  2. When there's a need to convey a narrative-only construct that doesn't neatly correspond to one of the other resources, either because it combines aspects of several resources (e.g. Assessment + Plan) or because the allowed content is flexible such that the system can't be totally sure what sort of content might have been included in the narrative text.
  3. Other than the circumstances above, this resource will see minimal use. To keep the FHIR specification managable, it cannot incorporate every site-specific requirement that might be needed in some implementation somewhere. This set of resources likely won't ever be officially defined in HL7.

There's also a fourth circumstance: An implementer wishes to convey information that could/should be conveyed using a standard resource, however they want to represent the information in a custom format that isn't aligned with the official resource's elements. While this resource would be the preferred way of meeting that use-case because it will at least be wire-format compatible, such a use would not be conformant because making use of the Basic resource would prevent the healthcare-related information from being safely processed, queried and analyzed by other conformant systems.

Implementers don't need to be concerned with which of the three categories their desired resource fits within. If they need a resource and it clearly doesn't fit one of the ones currently defined, they should use Basic.

Note to Implementers: That the inter-version extension mechanism might be used to allow Basic to represent resources that don't exist in the FHIR version being used for exchange, but no specific guidance is provided. If implementers are interested in having this further defined, they should share their use-case on http://chat.fhir.org icon and the committee might consider publishing out an implementation guide providing further guidance.

2.2.2 Background and Context

Basic defines only a minimal set of data elements - those necessary to identify what kind of resource it represents and those necessary to support resource compartmenting. All other data elements are represented using the extension mechanism. It's entirely possible to have a Basic resource instance with nothing other than narrative, a subject and code. And, in practice, that's all many systems will understand.

2.2.3 Boundaries and Relationships

The Basic resource can potentially represent any resource. However, wherever another resource can be used instead of Basic, that resource should always be used.

Other resources that are commonly used to capture 'generic' data are listed below:

  • Observation is preferable to Basic when the data being captured is a point-in-time assertion, particularly if it's potentially subjective and when notions such as 'method' or 'performer' of - how the data was captured are relevant.
  • Questionnaire is appropriate when the focus is on how the data is gathered from the user and where the resulting data won't be directly searchable.
  • Parameters are used when invoking operations or possibly passing information into a messaging call.
  • DocumentReference can be used to encapsulate arbitrary data so long as there is a mime type that corresponds to that structure. However, such data is typically opaque to FHIR queries.

2.2.4 References to this Resource

No references for this Resource.

2.2.5 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Basic TU DomainResource Resource for non-supported content

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... identifier Σ 0..* Identifier Business identifier

... code ?!Σ 1..1 CodeableConcept Kind of Resource
Binding: Basic Resource Types (Example)
... subject Σ 0..1 Reference(Any) Identifies the focus of this resource
... author Σ 0..1 Reference(Practitioner | PractitionerRole | Patient | RelatedPerson | Organization | Device | CareTeam) Who created

doco Documentation for this format icon

See the Extensions for this resource

XML Template

<Basic xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Business identifier --></identifier>
 <code><!-- 1..1 CodeableConcept Kind of Resource --></code>
 <subject><!-- 0..1 Reference(Any) Identifies the focus of this resource --></subject>
 <created value="[dateTime]"/><!-- 0..1 When created -->
 <author><!-- 0..1 Reference(CareTeam|Device|Organization|Patient|Practitioner|
   PractitionerRole|RelatedPerson) Who created --></author>
</Basic>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:Basic;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:identifier  ( [ Identifier ] ... ) ; # 0..* Business identifier
  fhir:code [ CodeableConcept ] ; # 1..1 Kind of Resource
  fhir:subject [ Reference(Any) ] ; # 0..1 Identifies the focus of this resource
  fhir:created [ dateTime ] ; # 0..1 When created
  fhir:author [ Reference(CareTeam|Device|Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ] ; # 0..1 Who created
]

Changes from both R4 and R4B

Basic
Basic.created
  • Type changed from date to dateTime
Basic.author
  • Type Reference: Added Target Types Device, CareTeam

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Basic TU DomainResource Resource for non-supported content

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... identifier Σ 0..* Identifier Business identifier

... code ?!Σ 1..1 CodeableConcept Kind of Resource
Binding: Basic Resource Types (Example)
... subject Σ 0..1 Reference(Any) Identifies the focus of this resource
... author Σ 0..1 Reference(Practitioner | PractitionerRole | Patient | RelatedPerson | Organization | Device | CareTeam) Who created

doco Documentation for this format icon

See the Extensions for this resource

XML Template

<Basic xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Business identifier --></identifier>
 <code><!-- 1..1 CodeableConcept Kind of Resource --></code>
 <subject><!-- 0..1 Reference(Any) Identifies the focus of this resource --></subject>
 <created value="[dateTime]"/><!-- 0..1 When created -->
 <author><!-- 0..1 Reference(CareTeam|Device|Organization|Patient|Practitioner|
   PractitionerRole|RelatedPerson) Who created --></author>
</Basic>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:Basic;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:identifier  ( [ Identifier ] ... ) ; # 0..* Business identifier
  fhir:code [ CodeableConcept ] ; # 1..1 Kind of Resource
  fhir:subject [ Reference(Any) ] ; # 0..1 Identifies the focus of this resource
  fhir:created [ dateTime ] ; # 0..1 When created
  fhir:author [ Reference(CareTeam|Device|Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ] ; # 0..1 Who created
]

Changes from both R4 and R4B

Basic
Basic.created
  • Type changed from date to dateTime
Basic.author
  • Type Reference: Added Target Types Device, CareTeam

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON.

 

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

2.2.5.1 Terminology Bindings

Path ValueSet Type Documentation
Basic.code BasicResourceTypes Example

This value set defines codes for resources not yet supported by (or which will never be supported by) FHIR. Many of the codes listed here will eventually be turned into official resources. However, there is no guarantee that any particular resource will be created nor that the scope will be exactly as defined by the codes presented here. Codes in this set will be deprecated if/when formal resources are defined that encompass these concepts.

2.2.6 Why not custom resources?

Technically, nothing prevents implementers from going off and defining their own resources containing whatever data elements they wish. However, doing so causes several issues:

  • Custom resources don't have a discoverability mechanism in the same way custom codes and extensions do using the ValueSet and StructureDefinition resources. As a result, any implementer that receives a custom resource would have no way of looking up what the meaning of the resource or its elements were. While they could get some sense of meaning from XML or JSON tag names, this often isn't sufficient for safe healthcare interoperability.
  • Custom resource names would not be present in the FHIR schemas as allowed elements within the FHIR Bundle schema, would not be present in the enumeration of resources in the Reference type, and would not be supported by any of the autogenerated reference implementations and software interfaces. This would cause issues for any receiving system making use of the schemas directly or via code-generation.
  • There is no means of preventing two implementers from independently coming up with the same name for a resource but defining it differently in terms of meaning as well as allowed elements. This would also cause interoperability issues.

All of these concerns are mitigated when there's an assumption that the custom resource will only be used within a narrow constrained environment where all participants will be aware of the semantics, will be using the same custom schemas and there's no chance of collisions. However, HL7's experience is that closed implementation environments rarely remain that way over the long term. Eventually data will need to be shared with others outside the closed environment and all of the above issues will again come into play.

Therefore, use of 'custom' resources is NOT considered to be conformant with FHIR. While the use of extensions may make the Basic resource slightly more complex and less visually appealing, it is the only safe and approved mechanism for sharing resource concepts not representable using standard HL7-defined resources.

It is expected that future versions of the interface tooling will be able to generate object interfaces on the basis of profiles. Where this occurs, the complexity of custom resource elements being expressed as extensions should be transparent to the internal code of systems that support that particular variant of the Basic resource. This should further reduce the cost of using 'Basic' as opposed to custom resources.

NOTE: This position is subject to change based on implementation experience. Alternative mechanisms for handling custom resource requirements in a safe manner may be explored. Ideas around alternative technical strategies for managing this issue are welcome.

2.2.7 Documents and narrative-only resources

Documents are constructed of sections, where a key part of each section is the narrative. The narratives are stitched together to form the overall text of the document. Many document sections will correspond neatly to resources that are already defined - List, DiagnosticReport, FamilyMemberHistory, etc. However, oddly enough, alignment with FHIR resources isn't always in mind when clinicians and others design documents, and some sections won't neatly align with the boundaries of resources. Sometimes there's simply a need for a place where a document author can say "stuff" without any particular constraints on what they may choose to talk about. Basic is intended to provide a mechanism to handle those circumstances.

Wherever possible, the "standard" FHIR resources should be used, even for narrative-only content. That's because subsequent revisions of the narrative-only content might choose to encode pieces or even all of the narrative content. Encoding can occur with "Basic" as well. Extensions can point to other resources (contained or stand-alone) that fully encode pieces of the free-form narrative found in the Basic resource. If no appropriate other resource exists for the meaning of the content, extensions can also be used.

2.2.8 Best practices for using 'Basic'

There are several good practices to follow when making use of the Basic resource:

  1. Before using Basic, post a description of the desired resource type on chat.fhir.org icon or on Stack Overflow icon to see whether the use-case can be met by an existing resource. (Sometimes the intended scope of an existing resource won't be clear, even if the intent is to cover your space.) Using an existing resource is usually preferable to using Basic as it significantly increases the likelihood of interoperability.
  2. If an existing resource would normally be a good fit for your use-case but can't be used due to overly prescriptive constraints your implementation is unable to meet, again raise the problem on Stack Overflow icon so the problem with the specification can be addressed.
  3. If it is necessary to make use of the Basic resource, try to use one of the HL7-defined codes for resource type or submit your requirement for a new type for inclusion in the HL7 vocabulary (using the Propose a change icon link), as this will increase the likelihood of interoperability. Alternate code systems are conformant, but are less likely to be recognized or re-used across the healthcare implementation space.
  4. Architect your interface in a way that will make it less painful to swap your use of Basic with an 'official' resource in the event that a future release of FHIR formally defines a resource that encompasses your use-case.
  5. Use a StructureDefinition to define the extensions relevant to each type of other resource used. Profiles can also be used to define additional search criteria appropriate for the resource.
  6. When defining a profile on Basic, include mappings to the w5 categories to allow systems to easily manage AuditEvent and Provenance uses as well as other potential higher-level abstractions of the data.
  7. As well, profiles should consider how best to handle common notions such as "entered in error" status and alignment with common practices within similar resource families (other request resources, medication-related resources), etc.

2.2.9 Referencing Basic resources

None of the standard resources will have direct references to Basic, aside from those that allow linking to "Any" resource. As a result, most references to "Basic" will need to be performed using extensions.

2.2.10 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
author reference Who created Basic.author
(Practitioner, Organization, CareTeam, Device, Patient, PractitionerRole, RelatedPerson)
code token Kind of Resource Basic.code 21 Resources
created date When created Basic.created
identifier token Business identifier Basic.identifier 65 Resources
patient reference Identifies the focus of this resource Basic.subject.where(resolve() is Patient)
(Patient)		 65 Resources
subject reference Identifies the focus of this resource Basic.subject
(Any)