Capability Statement (FHIR Capability Statement)

fhir technical technical fhirinteroperabilityhealthcare
Source: HL7 System: http://hl7.org/fhir Code: CapabilityStatement Reviewed: 17/12/2025 License: CC-BY-4.0

Capability Statement (FHIR Capability Statement)

One-sentence definition: A FHIR Capability Statement is a machine-readable document published by a FHIR server or client that declares which resource types, interactions, search parameters, operations, and profiles it supports, providing the formal specification of that system’s FHIR API surface.

Full Definition

Every FHIR server is required to publish a Capability Statement at a standard endpoint (GET [base]/metadata). It is a FHIR resource of type CapabilityStatement that describes, in computable terms, what that server does and does not support. Think of it as the API contract made explicit: rather than reading documentation or trial-and-error testing, a client can programmatically read the Capability Statement to discover exactly what the server supports before sending requests.

A Capability Statement answers questions like: Can I create Patient resources on this server? Does it support the $member-match operation? Does it index the birthdate search parameter? Which profiles does it claim to support? What FHIR version does it implement? This information is structured as a FHIR resource with defined element paths, making it machine-parseable by any FHIR-aware client.

The CapabilityStatement resource was called “Conformance” in FHIR DSTU2 and STU3. The rename in R4 to “CapabilityStatement” better reflects its purpose — describing capability rather than asserting conformance (which must be verified, not merely declared).

For how Capability Statements are used in practice for profile conformance assertions, server validation, and implementation guide compliance, see FHIR Profiling.

Context and Usage

Where This Term Appears

Capability Statements appear in several integration contexts:

  • GET [base]/metadata — the standard FHIR endpoint every server must support; returns the server’s CapabilityStatement
  • ONC certification testing: Inferno test suites parse CapabilityStatements to verify US Core compliance before running interaction tests
  • SMART App Launch discovery: smart-capabilities extensions in the CapabilityStatement advertise which SMART launch flows the server supports
  • API documentation: Implementation Guides (US Core, Da Vinci, UK Core) specify CapabilityStatement requirements for compliant servers
  • Client library initialization: many FHIR client libraries fetch the CapabilityStatement on startup to configure which operations and search parameters to use
  • Integration contracts: procurement and integration specifications often reference CapabilityStatement requirements

Common Usage Examples

In conversation: “Before we onboard a new data source, we pull their metadata endpoint and check the CapabilityStatement — if they don’t support the search parameters we need, we know upfront.”

In documentation: “Servers SHALL include a CapabilityStatement that declares support for the us-core-patient profile in rest.resource[type=Patient].supportedProfile.”

In technical contexts — fetching a server’s capability statement:

GET https://fhir.example.org/r4/metadata
Accept: application/fhir+json

Returns a CapabilityStatement that includes entries like:

{
  "resourceType": "CapabilityStatement",
  "fhirVersion": "4.0.1",
  "rest": [
    {
      "mode": "server",
      "resource": [
        {
          "type": "Patient",
          "supportedProfile": [
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
          ],
          "interaction": [
            { "code": "read" },
            { "code": "search-type" }
          ],
          "searchParam": [
            { "name": "identifier", "type": "token" },
            { "name": "family", "type": "string" },
            { "name": "birthdate", "type": "date" }
          ]
        }
      ]
    }
  ]
}

Why Capability Statements Exist

Before CapabilityStatement existed, discovering what a FHIR server supported required reading narrative documentation (when it existed and was current) or probing the API experimentally. As the FHIR ecosystem matured and servers diverged in their supported profiles, search parameters, and operations, the cost of integration discovery grew.

CapabilityStatement solves this by making capability declaration computable and standardized. Automated test suites like Inferno can parse a CapabilityStatement and derive a test plan: what to test, which profiles to validate against, which search parameters to use. Clients can adapt their behavior based on what a server declares. Procurement teams can require CapabilityStatement evidence for claimed conformance.

Key Components

Server metadata

The outer level of a CapabilityStatement declares server-level properties: FHIR version, format support (JSON, XML), implementation URL, software name and version, and contact information. This metadata helps integrators understand the context before examining resource-level capabilities.

Supported resources

For each resource type the server supports, the CapabilityStatement lists the supported interactions (read, vread, update, create, delete, search-type), the supported profiles (supportedProfile), and the declared conformance profile (profile). This is how a server says “I support Patients, and I claim they conform to US Core Patient.”

Supported search parameters

For each resource, the CapabilityStatement lists which search parameters are indexed and available. This is critical for integration: a client attempting to search Patient?birthdate=1980-01-01 on a server that doesn’t index birthdate will get an error or an empty result without explanation. Checking the CapabilityStatement first reveals the gap before wasting an API call.

Supported operations

Custom FHIR operations (like $member-match, $export, $validate) must be declared in rest.operation and rest.resource.operation to signal availability. A client checking for bulk export support looks for $export in the CapabilityStatement before sending a bulk request.

Supported profiles

rest.resource.supportedProfile lists the profiles a server claims to support for a given resource type. This is a declaration, not a guarantee — see Misconceptions. But it is the starting point for conformance validation.

Capability Statement Types

Server capability statements (mode: server)

The most common type. Published at /metadata, describes what a FHIR server accepts and returns. Every FHIR server is expected to publish one.

Client capability statements (mode: client)

Describes what a FHIR client can consume — useful for provider registration, onboarding flows, and SMART App Launch. A SMART app might publish a client CapabilityStatement describing which resource types and scopes it needs, allowing the server to verify it supports the requested capabilities before authorizing.

Requirements capability statements (mode: requirements)

Used in Implementation Guides to describe what a conformant implementation must support — not what a specific server does, but what any server claiming IG conformance must do. Regulators and certification programs use requirements CapabilityStatements to define the floor for compliance testing.

How to Access

/metadata endpoint

GET [base]/metadata returns the server’s CapabilityStatement. No authentication is required for the metadata endpoint — it is intentionally public so clients can discover capabilities before authenticating.

GET https://fhir.example.org/r4/metadata
Accept: application/fhir+json

CapabilityStatement resource

A server may also expose its CapabilityStatement as a storable resource via GET [base]/CapabilityStatement/[id], enabling versioning and comparison of capability snapshots over time.

Relationship to Other Terms

  • FHIR — the standard that defines the CapabilityStatement resource and the /metadata endpoint
  • Profile — profiles are declared in CapabilityStatements; the relationship between declared and actual profile support is key to conformance
  • Resource — CapabilityStatement is itself a FHIR resource, and it enumerates which other resources a server supports

Common Misconceptions

Misconception 1: Capability Statements are optional

  • Incorrect belief: Publishing a CapabilityStatement is nice-to-have; a working FHIR API doesn’t need one.
  • Reality: The FHIR specification requires that servers support the GET [base]/metadata endpoint. ONC certification testing (Inferno) begins by fetching the CapabilityStatement — a server that doesn’t publish one fails the first test. CMS API mandates expect CapabilityStatements that declare specific profile support.
  • Why it matters: A FHIR server without a CapabilityStatement is not a compliant FHIR server, regardless of how well it handles other requests. It also prevents automated testing and integration discovery.

Misconception 2: Capability Statements are always accurate

  • Incorrect belief: If a server’s CapabilityStatement says it supports a profile or search parameter, it actually does.
  • Reality: CapabilityStatements are declarations, not test results. Servers frequently over-claim (listing profiles they partially support) or under-claim (not listing search parameters they actually implement). Treat the CapabilityStatement as a starting point, then validate through actual API testing.
  • Why it matters: Integration failures attributed to “the server said it was supported” are common. The CapabilityStatement reduces discovery cost but does not replace end-to-end testing. ONC’s Inferno test suite exists precisely because CapabilityStatement declarations are not sufficient evidence of conformance.

Cross-References

  • FHIR — the standard that defines CapabilityStatement
  • Profile — profiles are declared in CapabilityStatements
  • Resource — CapabilityStatement is itself a FHIR resource

Last reviewed: December 17, 2025 Definition authority: HL7 International Content status: Canonical reference