Page Status: draft updated 2024-12-11

Resources

Page index

• Introduction
• General rules for all resources
  • Profiles
  • Must support
  • Constraining elements
    • Cardinality
    • Invariants
    • Fixed values
    • Slices
  • Identifiers
  • Resource version
  • References
  • Extensions
• Supported FHIR resources
• Profile versions

Introduction

FHIR is based on "Resources" which are the common building blocks for all exchanges. Resources are an instance-level representation of some kind of healthcare entity.

This section of the implementation guide lists the resources used by Swedish National Medication List and the common rules used when profiling those resources.

General rules for all resources

Profiles

The FHIR specification describes a set of base resources, frameworks and APIs that are used in many different contexts within healthcare. The FHIR specification is a "platform specification" - it creates a common platform, or foundation, on which a variety of different solutions are implemented. As a consequence, this specification usually requires further adaptation to particular contexts of use. For this reason FHIR includes the possibility to create profiles. A profile is a structure definition with constraints on the resource it represents, i.e. a profile is a description of an implementation of a resource in a specific context.

It is possible/mandatory (utveckla baserat på vad vi väljer) to include a reference to one or more profiles in a resource by the element meta.profile. The meta.profile element is always included in a response from the Swedish National Catalog of Organization, Offerings and Contracts.

"Must support" property

The general approach of customizing FHIR resources for the Swedish National Catalog of Organization, Offerings and Contracts has been to mark elements that are used within a resource with the FHIR must support flag rather than excluding elements by cardinality, i.e. 0..0, to facilitate interoperability.

The must-support flag indicates that the element is expected in some use cases, and a missing flag that the element is never used. However there may be exceptions to the second rule for non essential data, e.g the element meta.profile.

Data sent to the Swedish National Catalog of Organization, Offerings and Contracts in elements not marked as must-support will be ignored.

Constraining elements

Elements can be profiled to be constrained in different ways. The following section describes the methods in which the Swedish National Catalog of Organization, Offerings and Contracts constrain elements in order to ensure correct data input.

Note that another type of constraint is binding an element to a value set. See Terminologies for more information.

Cardinality

FHIR generally supports a cardinality of 'zero to many' in a majority of the elements. This is in order to have a flexible structure to cater for different scenarios.

In the profiles, the cardinalities of the used elements (marked with 'must support') is narrowed to support the use cases in which the element is used. This means that the cardinality defined in a profile in some cases is more open than the actual use case allows.

Invariants

An element can have constraints, also called "invariants", that specify rules which the element has to follow. In this guide they are found by hovering over an element in a resource tree, under the title "Constraints". If a constraint is not followed, the server might return a warning or an error. The constraints can come from the base specification of the resource or from the profiles. Those that are defined by the Swedish National Catalog of Organization, Offerings and Contracts are prefixed with "hvo" and are listed in the table below.

Fixed values

Another way in which an element might be constrained is if it has a fixed value. This means that the fixed value has to be used. This applies if the element has a label of "pattern" or "fixed value" next to it. Hovering on the element will show the fixed value in question under the same label.

Slices

Some profiles might contain different alternatives for certain elements. It can be either mandatory or not to choose one of the alternatives. These alternatives are called slices in FHIR. Slices of an element are always distinguished by a discriminator, for example a value of a subelement, and have names that represent the alternatives. They might be used to express different constraints of the element, for example different cardinalities, invariants, value set bindings, etc, depending on this discriminator. It is not expressed in the body of a request which slice is being adapted, it is understood from the discriminator.

An example of slicing is found in the HVOOrganization profile, which defines two slices for the identifier element. They are determined by the system subelement. One slice profiles the identifier element if the system is "urn:oid:1.2.752.29.4.19", named "hsaid", and the other if the system is "urn:oid:2.5.4.97", named "organizationIdentifier" (note the "fixed value" label (see the section above) by the system elements). The two slices can then define different invariants (see the section above) on the value element, in order to make sure that the value is entered correctly depending on the system. As previously stated, it is not expressed in the JSON body of a request which slice has been chosen, it is solely inferred by which value is provided of the identifier.system element in this case.

Slices can either be open, meaning that the element can be filled in without choosing an alternative, or closed, meaning that one of the slices has to be adapted.

Identifiers

All resources have a logical identifier. The logical identifier is assigned by the server and is unique on that server. A resource can be fetched by referring to its logical ID in the form [base]/[resource-type]/[id] e.g. [base]/Organization/123 where 123 is the logical ID. Most resources in the Swedish National Catalog of Organization, Offerings and Contracts use an UUID as logical ID. A logical ID will never change after it has been assigned to a resource. Se more information about the ID element in the section references.

Resources can also have a business identifier. A business identifier is a well known inter system identifier like a personal identification number, organization number, GLN ID etc. It is in many cases possible to perform search operations on business identifiers, e.g. GET [base]/Organization?identifier=urn:oid:2.5.4.97|1111111111.

A common way to find resources is to use business identifiers in a search operation. See the documentation for each resource to find out what search operations the resorce supports.

In the case that a resource does not have a business identifier, the logical identifier created by the Swedish eHealth Agency can be used as a business identifier in the connecting systems. One example is when the returned id of an Organization is saved in the system doing the POST Organization request.

Resource version

All persistent resources are conceptually versioned and the version information is found in the meta element.

  "meta": {
    "versionId": "2"
  }

A previous version of a resource can be found by requesting it through the _history operation [base]/[resource-type]/[id]/_history/[vid], e.g. [base]/Organization/81a98656-4cec-442d-a82a-6a0476e0f3a0/_history/2, will fetch the second version of the Organization with logical id 81a98656-4cec-442d-a82a-6a0476e0f3a0.

References

A reference to another resource is usually done as a literal reference, i.e. by an URL pointing at the resource. The referenced resource can then be fetched via the URL in a separate request. A literal reference can be either absolute or relative. An absolute reference is a complete URL, i.e. https://domain.org/fhir/Patient/123. A relative reference omits the service base URL, i.e. Patient/123. In the Swedish National Catalog of Organization, Offerings and Contracts very few references are absolute as the service base URL vary depending on the entry point used by different actors.

In some cases it is not possible to reference another resource because the other resource has no identifier. One reason for this is if the resource is not persistent. Another case is when the resource exists only in the context of the referencer, e.g. an Organizational Unit includes a Business resource with no identifier. References to inline resources is in FHIR called contained resources and such references starts with a #, e.g. #p1. If the inline resource has to reference its containing resource, it is done using a single #. See FHIR contained resources for more information.

It is important that systems interacting with the Swedish National Catalog of Organization, Offerings and Contracts can handle all of the above types of references. The way a resource references other resources may change over time if it doesn't break any other implicit or explicit rules regarding the information transmitted.

The snippet below includes both a literal relative reference and a reference from a contained resource to its containing resource.

{
  "resourceType": "Organization",
  "contained": [
    {
      "resourceType": "HealthcareService",
      "id": "p1",
      "providedBy":
        {
          "reference": "#"
        }
    }
  ],
  "partOf": {
    "reference": "Organization/aa9e5f2b-a906-4312-9d13-61fd46d63f58"
  }
}

Extensions

The HL7 FHIR specification covers the most common resource types and the most common elements within those resources for the healthcare industry. Concepts that are of less common use can be added to the generic resources by adding so called FHIR extensions.

The Swedish National Catalog of Organization, Offerings and Contracts relies on extensions to extend the generic and international FHIR specification with concepts specific to Sweden and the purpose of the Swedish National Catalog of Organization, Offerings and Contracts.

In the Swedish National Catalog of Organization, Offerings and Contracts all incoming resources are interpreted as its base resource with the constraints and extensions specified in the profile and in other documentation, e.g. use cases (sv: tillämpningsanvisningar).

It is important to understand that extensions are mutable. A profile may evolve by adding new extensions. Systems must be able to handle this as long as the new data is not vital for existing use cases. This applies to standard FHIR elements also. Elements not used in one version may come to use in a later version.

Supported FHIR resources

The following table is an overview of all resource types used within the Swedish National Catalog of Organization, Offerings and Contracts, with a brief description of how each resource is used. A more detailed description can be found by navigating to each resource in the menu.

List of Resource profile versions