FHIR CI-Build

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

5.3 Resource CapabilityStatement - Content

FHIR Infrastructure icon Work GroupMaturity Level: N Normative (from v4.0.0)Security Category: Anonymous Compartments: No defined compartments

A Capability Statement documents a set of capabilities (behaviors) of a FHIR Server or Client for a particular version of FHIR that may be used as a statement of actual server functionality or a statement of required or desired server implementation.

5.3.1 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:

Instance implementation must be present and software may be present
Capability implementation must be absent, software must be present
Requirements implementation and software must be absent

5.3.1.1 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.

5.3.1.2 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.

5.3.1.3 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.

5.3.2 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.

5.3.2.1 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.

5.3.2.2 Mixed Normative Content

While the core of the CapabilityStatement resource is Normative, many of the flags that indicate exactly how the system operates are marked as trial-use. Roughly, the portions of the resource that correspond to OpenAPI document icon elements are normative.

Applications looking for normative stability should only use the normative parts of the resource, and not populate or ignore the portions labelled trial-use. To assist with this, clients can ask for the server to return a 'Normative content only' CapabilityStatement using the mode parameter on /metadata.

Community discussion regarding more capable, efficient and computable representations of an applications capabilities may lead to change to the trial-use parts of this resource or the creation of new resources and/or functionality in future versions of this specification.

5.3.3 References to this Resource

5.3.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CapabilityStatement N DomainResource A statement of system capabilities
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
+ Rule: A Capability Statement SHALL have at least one of REST, messaging or document element.
+ Rule: A Capability Statement SHALL have at least one of description, software, or implementation element.
+ Rule: Messaging end-point is only permitted when a capability statement is for an implementation.
+ Rule: There should only be one CapabilityStatement.rest per mode.
+ Rule: The set of documents must be unique by the combination of profile and mode.
+ Rule: If kind = instance, implementation must be present and software may be present
+ Rule: If kind = capability, implementation must be absent, software must be present
+ Rule: If kind = requirements, implementation and software must be absent

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

... version Σ 0..1 string Business version of the capability statement
... versionAlgorithm[x] ΣTU 0..1 How to compare versions
Binding: Version Algorithm (Extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 0..1 string Name for this capability statement (computer friendly)
... title ΣT 0..1 string Name for this capability statement (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (Required)
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 1..1 dateTime Date last changed
... publisher ΣT 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher

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

... actorDefinition ΣTU 0..* canonical(ActorDefinition) ActorDefinitions the CapabilityStatement supports

... jurisdiction ΣXD 0..* CodeableConcept Intended jurisdiction for capability statement (if applicable)
Binding: Jurisdiction ValueSet (Extensible)

... purpose T 0..1 markdown Why this capability statement is defined
... copyright T 0..1 markdown Use and/or publishing restrictions
... copyrightLabel TTU 0..1 string Copyright holder and year(s)
... kind ΣC 1..1 code instance | capability | requirements
Binding: Capability Statement Kind (Required)
... instantiates Σ 0..* canonical(CapabilityStatement) Canonical URL of another capability statement this implements

... imports ΣTU 0..* canonical(CapabilityStatement) Canonical URL of another capability statement this adds to

... software ΣC 0..1 BackboneElement Software that is covered by this capability statement
.... name Σ 1..1 string A name the software is known by
.... version Σ 0..1 string Version covered by this statement
.... releaseDate Σ 0..1 dateTime Date this version was released
... implementation ΣC 0..1 BackboneElement If this describes a specific instance
.... description Σ 1..1 markdown Describes this specific instance
.... url Σ 0..1 url Base URL for the installation
.... custodian ΣTU 0..1 Reference(Organization) Organization that manages the data
... fhirVersion Σ 1..1 code FHIR Version the system supports
Binding: FHIRVersion (Required)
... format Σ 1..* code formats supported (xml | json | ttl | mime type)
Binding: Supplemented Mime Types (Required)
Additional BindingsPurpose
Capability Format Type Starter Set


... patchFormat Σ 0..* code Patch formats supported (Mime types for FHIR and JSON And XML Patch)
Binding: Patch Mime Types (Required)

... acceptLanguage ΣTU 0..* code Languages supported
Binding: All Languages (Required)
Additional BindingsPurpose
Common Languages Starter Set


... implementationGuide Σ 0..* canonical(ImplementationGuide) Implementation guides supported

... rest ΣC 0..* BackboneElement If the endpoint is a RESTful one
+ Rule: A given resource can only be described once per RESTful mode.

.... mode ΣC 1..1 code client | server
Binding: Restful Capability Mode (Required)
.... documentation T 0..1 markdown General description of implementation
.... security ΣTU 0..1 BackboneElement Information about security of implementation
..... cors Σ 0..1 boolean Adds CORS Headers (http://enable-cors.org/)
..... service Σ 0..* CodeableConcept OAuth | SMART-on-FHIR | NTLM | Basic | Kerberos | Certificates
Binding: Restful Security Service (Extensible)

..... description T 0..1 markdown General description of how security works
.... resource ΣC 0..* BackboneElement Resource served on the REST interface
+ Rule: Search parameter names must be unique in the context of a resource.

..... type ΣC 1..1 code A resource type that is supported
Binding: Extended Resource Types (Required)
..... definition Σ 0..1 canonical(StructureDefinition) The definition for an additional resource
..... profile Σ 0..1 canonical(StructureDefinition) System-wide profile
..... supportedProfile ΣTU 0..* canonical(StructureDefinition) Use-case specific profiles

..... documentation T 0..1 markdown Additional information about the use of the resource type
..... interaction 0..* BackboneElement What operations are supported?

...... code 1..1 code read | vread | update | update-conditional | patch | patch-conditional | delete | delete-conditional-single | delete-conditional-multiple | delete-history | delete-history-version | history-instance | history-type | create | create-conditional | search-type
Binding: Type Restful Interaction (Required)
...... documentation T 0..1 markdown Anything special about operation behavior
..... versioning TU 0..1 code no-version | versioned | versioned-update
Binding: Resource Version Policy (Required)
..... readHistory 0..1 boolean Whether vRead can return past versions
..... updateCreate 0..1 boolean If update can commit to a new identity
..... conditionalCreate 0..1 boolean If allows/uses conditional create
..... conditionalRead 0..1 code not-supported | modified-since | not-match | full-support
Binding: Conditional Read Status (Required)
..... conditionalUpdate 0..1 boolean If allows/uses conditional update
..... conditionalPatch 0..1 boolean If allows/uses conditional patch
..... conditionalDelete 0..1 code not-supported | single | multiple - how conditional delete is supported
Binding: Conditional Delete Status (Required)
..... referencePolicy TU 0..* code literal | logical | resolves | enforced | local
Binding: Reference Handling Policy (Required)

..... searchInclude TU 0..* string _include values supported by the server

..... searchRevInclude TU 0..* string _revinclude values supported by the server

..... searchParam C 0..* BackboneElement Search parameters supported by implementation

...... name C 1..1 string Name for parameter in search url
...... definition 0..1 canonical(SearchParameter) Source of definition for parameter
...... type 1..1 code number | date | string | token | reference | composite | quantity | uri | special
Binding: SearchParamType (Required)
...... documentation 0..1 markdown Server-specific usage
..... operation Σ 0..* BackboneElement Definition of a resource operation

...... name Σ 1..1 string Name by which the operation/query is invoked
...... definition Σ 1..1 canonical(OperationDefinition) The defined operation/query
...... documentation T 0..1 markdown Specific details about operation behavior
.... interaction 0..* BackboneElement What operations are supported?

..... code 1..1 code transaction | batch | search-system | history-system
Binding: System Restful Interaction (Required)
..... documentation T 0..1 markdown Anything special about operation behavior
.... searchParam 0..* see searchParam Search parameters for searching all resources

.... operation Σ 0..* see operation Definition of a system level operation

.... compartment 0..* canonical(CompartmentDefinition) Compartments served/used by system

... messaging ΣCTU 0..* BackboneElement If messaging is supported

.... endpoint C 0..* BackboneElement Where messages should be sent

..... protocol 1..1 Coding http | ftp | mllp +
Binding: Message Transport (Extensible)
..... address 1..1 url Network address or identifier of the end-point
.... reliableCache 0..1 unsignedInt Reliable Message Cache Length (min)
.... documentation T 0..1 markdown Messaging interface behavior details
.... supportedMessage Σ 0..* BackboneElement Messages supported by this system

..... mode Σ 1..1 code sender | receiver
Binding: Event Capability Mode (Required)
..... definition Σ 1..1 canonical(MessageDefinition) Message supported by this system
... document ΣCTU 0..* BackboneElement Document definition

.... mode ΣC 1..1 code producer | consumer
Binding: Document Mode (Required)
.... documentation T 0..1 markdown Description of document support
.... profile ΣC 1..1 canonical(StructureDefinition) Constraint on the resources used in the document

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

5.3.4.1 Terminology Bindings

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

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

The lifecycle status of an artifact.
CapabilityStatement.jurisdiction JurisdictionValueSet Extensible

This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used.

Note: The codes for countries and country subdivisions are taken from ISO 3166 icon while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) icon.
CapabilityStatement.kind CapabilityStatementKind Required

How a capability statement is intended to be used.
CapabilityStatement.fhirVersion FHIRVersion Required

All published FHIR Versions.
CapabilityStatement.format SupplementedMimeTypes Required

This value set includes all possible codes from BCP-13 (see http://tools.ietf.org/html/bcp13), and xml, json, and ttl
  Capability Format Type starter
CapabilityStatement.patchFormat PatchMimeTypes Required

This value set includes the possible codes from BCP-13 icon that are valid for Patch formats
CapabilityStatement.acceptLanguage AllLanguages (a valid code from Tags for the Identification of Languages icon) Required

This value set includes all possible codes from BCP-47 (see http://tools.ietf.org/html/bcp47)
  Common Languages starter
CapabilityStatement.rest.mode RestfulCapabilityMode Required

The mode of a RESTful capability statement.
CapabilityStatement.rest.security.service RestfulSecurityService Extensible

Types of security services used with FHIR.
CapabilityStatement.rest.resource.type ExtendedResourceTypes Required

Current and past FHIR resource types (deleted or renamed), and additional resource types. Note that the binding to additional resources is not version fixed, and will change over time
CapabilityStatement.rest.resource.interaction.code TypeRestfulInteraction Required

Operations supported by REST at the type or instance level.
CapabilityStatement.rest.resource.versioning ResourceVersionPolicy Required

How the system supports versioning for a resource.
CapabilityStatement.rest.resource.conditionalRead ConditionalReadStatus Required

A code that indicates how the server supports conditional read.
CapabilityStatement.rest.resource.conditionalDelete ConditionalDeleteStatus Required

A code that indicates how the server supports conditional delete.
CapabilityStatement.rest.resource.referencePolicy ReferenceHandlingPolicy Required

A set of flags that defines how references are supported.
CapabilityStatement.rest.resource.searchParam.type SearchParamType Required

Data types allowed to be used for search parameters.
CapabilityStatement.rest.interaction.code SystemRestfulInteraction Required

Operations supported by REST at the system level.
CapabilityStatement.messaging.endpoint.protocol MessageTransport Extensible

The protocol used for message transport.
CapabilityStatement.messaging.supportedMessage.mode EventCapabilityMode Required

The mode of a message capability statement.
CapabilityStatement.document.mode DocumentMode Required

Whether the application produces or consumes documents.

5.3.4.2 Constraints

UniqueKeyLevelLocationDescriptionExpression
img cnl-0Warning (base)Name should be usable as an identifier for the module by machine processing applications such as code generationname.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
img cnl-1Warning CapabilityStatement.urlURL should not contain | or # - these characters make processing canonical references problematicexists() implies matches('^[^|# ]+$')
img cpb-1Rule (base)A Capability Statement SHALL have at least one of REST, messaging or document element.rest.exists() or messaging.exists() or document.exists()
img cpb-2Rule (base)A Capability Statement SHALL have at least one of description, software, or implementation element.(description.count() + software.count() + implementation.count()) > 0
img cpb-3Rule (base)Messaging end-point is only permitted when a capability statement is for an implementation.messaging.endpoint.empty() or kind = 'instance'
img cpb-4Rule (base)There should only be one CapabilityStatement.rest per mode.rest.mode.isDistinct()
img cpb-7Rule (base)The set of documents must be unique by the combination of profile and mode.document.select(profile&mode).isDistinct()
img cpb-9Rule CapabilityStatement.restA given resource can only be described once per RESTful mode.resource.select(type).isDistinct()
img cpb-12Rule CapabilityStatement.rest.resourceSearch parameter names must be unique in the context of a resource.searchParam.select(name).isDistinct()
img cpb-14Rule (base)If kind = instance, implementation must be present and software may be present(kind != 'instance') or implementation.exists()
img cpb-15Rule (base)If kind = capability, implementation must be absent, software must be present(kind != 'capability') or (implementation.exists().not() and software.exists())
img cpb-16Rule (base)If kind = requirements, implementation and software must be absent(kind!='requirements') or (implementation.exists().not() and software.exists().not())

5.3.5 Notes:

  • The CapabilityStatement resource provides for an application to describe its use of the RESTful paradigm, messaging events, or FHIR documents. Usually an application would only describe one, but more than one may be described.
  • RESTful CapabilityStatement rules:
    • RESTful servers are required to provide this resource on demand. Servers SHALL specify what resource types and operations are supported, and SHOULD also specify profiles for each resource type.
    • The CapabilityStatement returned in the capabilities interaction may represent the specific capabilities granted to a specific user if retrieved with that specific user's credentials, if one is in context. Servers that require authentication SHOULD still return a CapabilityStatement before authentication/authorization is performed
    • RESTful clients SHOULD publish a capability statement
    • The search parameters that a server supports (or a client makes use of) are specified in the resource profile that the capability statement references
    • Resource Types or operations that are not listed are not supported
  • Messaging CapabilityStatement rules:
    • The interpretation of request and response depends on the mode. If the mode is sender, then request specifies what the application sends, and response specifies what it accepts. If the mode is "receiver", then this is reversed
    • If a request or response is not specified for an event, then no rules are made for it
    • Events that are not listed are not supported
    • The MessageDefinition resource is newly proposed and is still considered 'draft'. The supportedMessage element can be used in place of the event and the work group believes it may meet implementer needs better, however because the new mechanism has not yet been reviewed by ballot, the older 'event' mechanism has been retained. Implementers may use one or the other to define their capabilities. Feedback is welcome.
  • Document CapabilityStatement rules:
    • Document profiles should directly constrain the Document.information.class & type elements so that there is no ambiguity concerning which profile any given document conforms to.
  • Other service-based use of resources: Due to the variability of these services, the CapabilityStatement resource does not attempt to describe service-based use of resources. The various service specifications will need to describe this usage in their own way.

5.3.5.1 Timezone Discovery

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

5.3.5.2 Supporting Search

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:

  • What resource types search is supported on, or used on
  • What search parameters are supported, and what their names are on this server (the server can use alternative names). Note that clients can also choose to use alternative names for search parameters, but there is no expectation that servers will adapt for the client in this regard
  • Servers can define their own search parameters that are not sourced from elsewhere, and often to define searches on extensions (see example)
  • What include and reverse includes a server supports, or a client uses
  • The Capability Statement does not support saying anything about modifiers or chaining directly, but these kind of statements can be made in the referenced search parameter resources (using SearchParameter.derivedFrom to establish traceability to the original definition of the search parameter)
  • Systems can also make statements about their use or support for system wide search (not associated with a particular resource type)

Note to Implementers: 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?

Note to Implementers: 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.

5.3.5.3 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.

5.3.5.4 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 icon, 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.

See general note to balloters about Additional resources

5.3.6 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
context token A use context assigned to the capability statement (CapabilityStatement.useContext.value.ofType(CodeableConcept)) 30 Resources
context-quantity quantity A quantity- or range-valued use context assigned to the capability statement (CapabilityStatement.useContext.value.ofType(Quantity)) | (CapabilityStatement.useContext.value.ofType(Range)) 30 Resources
context-type TU token A type of use context assigned to the capability statement CapabilityStatement.useContext.code 30 Resources
context-type-quantity TU composite A use context type and quantity- or range-based value assigned to the capability statement On CapabilityStatement.useContext:
  context-type: code
  context-quantity: value.ofType(Quantity) | value.ofType(Range)		 30 Resources
context-type-value TU composite A use context type and value assigned to the capability statement On CapabilityStatement.useContext:
  context-type: code
  context: value.ofType(CodeableConcept)		 30 Resources
date date The capability statement publication date CapabilityStatement.date 31 Resources
description string The description of the capability statement CapabilityStatement.description 29 Resources
fhirversion token The version of FHIR CapabilityStatement.fhirVersion
format token formats supported (xml | json | ttl | mime type) CapabilityStatement.format
guide reference Implementation guides supported CapabilityStatement.implementationGuide
(ImplementationGuide)
identifier token External identifier for the capability statement CapabilityStatement.identifier 35 Resources
jurisdiction token Intended jurisdiction for the capability statement CapabilityStatement.jurisdiction 27 Resources
mode token Mode - restful (server/client) or messaging (sender/receiver) CapabilityStatement.rest.mode
name string Computationally friendly name of the capability statement CapabilityStatement.name 28 Resources
publisher string Name of the publisher of the capability statement CapabilityStatement.publisher 31 Resources
resource token Name of a resource mentioned in a capability statement CapabilityStatement.rest.resource.type
resource-profile reference A profile id invoked in a capability statement CapabilityStatement.rest.resource.profile
(StructureDefinition)
security-service token OAuth | SMART-on-FHIR | NTLM | Basic | Kerberos | Certificates CapabilityStatement.rest.security.service
software string Part of the name of a software application CapabilityStatement.software.name
status token The current status of the capability statement CapabilityStatement.status 35 Resources
supported-profile TU reference Profiles for use cases supported CapabilityStatement.rest.resource.supportedProfile
(StructureDefinition)
title string The human-friendly name of the capability statement CapabilityStatement.title 28 Resources
url uri The uri that identifies the capability statement CapabilityStatement.url 34 Resources
version token The business version of the capability statement CapabilityStatement.version 32 Resources