View raw Markdown
type: resourceresource: CapabilityStatement

CapabilityStatement

Introduction

Scope and Usage

The capability statement is a key part of the overall conformance framework in FHIR. It is used as a statement of the features of actual software, or of a set of rules for an application to provide. This statement connects to all the detailed statements of functionality, such as StructureDefinitions and ValueSets. This composite statement of application capability may be used for system compatibility testing, code generation, or as the basis for a conformance assessment. For further information about Conformance testing, see Conformance Rules and Profiling FHIR.

Specifically, capability statements are used in one of three ways:

Instanceimplementation must be present and software may be present
Capabilityimplementation must be absent, software must be present
Requirementsimplementation and software must be absent

Instance: Describe an actual implementation

In this scenario, the capability statement describes the capabilities of a deployed and configured solution available at a particular access point or set of access points. The statement describes exactly how to interface with that deployed solution and thus provides for a degree of self-configuration of software solutions.

This is the type of statement that FHIR restful solutions are expected to make available on invocation of the capabilities operation. It is also the type of statement that forms a basis for the testing, certification or commissioning of specific software installations.

Capability: Describe software solution capabilities

In this scenario, the capability statement describes generic capabilities of a software application or component solution. The solution might be available for purchase or other acquisition and might be deployed and configured at any number of independent sites. Because it is not dependent on any particular implementation, the profile cannot provide specific details such as endpoint addresses. It may also need to document various configurations in which the application can be set up or describe the degree of customizability associated with the solution.

This type of statement may be used as a marketing tool by software and system developers to formally describe their capabilities. It can also be used as the basis for conformance testing of software solutions independent of a particular installation.

Requirements: Describe a desired solution

In this scenario, the capability statement describes the capabilities of a desired system. It might be used as part of an architectural design process to document needed system capabilities, or might be used as part of an RFP process to formally document the requirements of a requested solution and to document the criteria by which proposals will be evaluated.

These three types of profiles can be used together. A requirements statement can be compared against the solution statements proffered by respondents to an RFP. A solution statement for a software package forms the starting point for the implementation statement associated with a particular installation of that software package.

CapabilityStatements of type "requirement" describe what capabilities are potentially relevant; additional documentation or extensions (see capabilitystatement-expectation) within the CapabilityStatement are expected to make more explicit statements of degree of expectation associated with each capability.

Background and Context

Capability Statements provide for a degree of automatic configuration and adaptation. However, capturing absolutely every variation that could impact the interoperability of two systems, let alone keeping that detailed information up-to-date as systems evolve through maintenance and upgrades, is rarely practical. Therefore, capability statements should be seen as an interim step. They provide a degree of automation. However, they also provide a great deal of human-readable content that can minimize the need for direct communication between the operators of the systems being configured to interoperate.

Supporting Multiple Versions

Applications may implement multiple versions. If they do, then a CapabilityStatement describes the system's support for a particular version of FHIR, and the system will have multiple statements, one for each version it supports. For further information, see Managing Multiple Versions, and the $versions operation.

Notes

Notes:

Timezone Discovery

If a server has a default timezone, it should be indicated via the timezone code extension on CapabilityStatement.meta.

One of the most important parts of the CapabilityStatement is indicating what search functionality a server supports or a client uses. The search can specify the following things:

[%stu-note reverse%] It is useful to support discovery of which reverse chaining values a server supports. Clients should not assume that servers support reverse chaining everywhere they support forward chaining. This will require a new field somewhere (e.g., in CapabilityStatement or in SearchParameter). Will review with FHIR-I, re: the best place to put this.

The most important use of support for reverse (or forward!) chaining might be in establishing conformance requirements for a server, rather than in supporting "live" discovery of a server's capabilities. (The latter could simply be tested by a client, rather than relying on possibly-incomplete or possibly-incorrect discovery data.)

Open question #1 would we want a way for servers to advertise which specific pairs of (searched resource + reverse chained search params) it support. For example, a server might need to say that the following is supported:

GET [base]/Patient?_has:Observation:subject:code=1234-5

... even though the following is not:

GET [base]/Group?_has:Observation:subject:code=1234-5

Open question #2: concern is that the possibility space is so broad that it might not be worth capturing all of this in such detail. Where to draw the line? [%end-note%] [%stu-note search%] There is no way for a server to communicate how it supports search at this time. FHIR-I plans to address this and other search issues for R6. [%end-note%]

Supporting Profiles

A CapabilityStatement declares two different kinds of profiles for the functionality it describes. For a discussion of the use of these two types of resources, see two uses for profiles.

Using additional resources in CapabilityStatements

CapabilityStatements may represent the use of additional resource. When doing so, CapabilityStatement.rest.resource.type contains the type of the resource as defined in the HL7 registry, along with a reference to the definition of the resource in CapabilityStatement.rest.resource.definition. The definition SHALL contain a version specific reference to the definition. The definition SHALL NOT be present if the resource type is one defined in this specification.

CapabilityStatements using additional resources can refer to these directly; when the additional resource moves to become a part of the core Specification, the search parameter canonical URLs do not change, though the versions might. But there's no change to the codes, whether the server uses the assigned code or it's own.

StructureDefinition

Elements (Simplified)

Mappings

Implementation Guide

implementationguide-CapabilityStatement-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="CapabilityStatement-core"/>
  <identifier>
    <system value="urn:ietf:rfc:3986"/>
    <value value="urn:oid:2.16.840.1.113883.4.642.30.4"/>
  </identifier>
  <name value="CommonCapabilityStatementExtensions"/>
  <title value="Common  Capability Statement extensions"/>
  <status value="draft"/>
  <date value="2014-04-12T00:00:00.000"/>
  <publisher value="Health Level Seven, Inc. - [WG Name] WG"/>
  <description value="Common extensions for use with the CapabilityStatement resource"/>
</ImplementationGuide>

Operations

Full Operations

Resource Packs

list-CapabilityStatement-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="CapabilityStatement-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/CapabilityStatement-core"/>
    </item>
  </entry>
</List>

Search Parameters

Full Search Parameters

Examples

Full Examples

Mapping Exceptions

capabilitystatement-definition-mapping-exceptions.xml

Divergent Elements

Unmapped Elements

capabilitystatement-fivews-mapping-exceptions.xml

Unmapped Elements