Written and maintained by CASRAI Editorial Board
Last updated
The HL7 FHIR CapabilityStatement resource (known as the Conformance resource in FHIR DSTU2 and normative since FHIR Release 4) is a machine-readable metadata document that declares the exact RESTful interactions, resource types, profiles, search parameters, custom operations, and security mechanisms supported by a FHIR server or required by a clinical implementation guide. Every conformant FHIR R4 server is required by the base specification to expose a dynamic CapabilityStatement so client applications can programmatically discover server functionality before issuing clinical data queries.
What Is a FHIR CapabilityStatement and How Is It Retrieved from GET [base]/metadata?
In the HL7 FHIR RESTful API architecture, a client discovers a server’s capabilities by issuing an HTTP GET request to the server’s base URL appended with /metadata:
GET https://fhir.example.org/r4/metadata HTTP/1.1
Accept: application/fhir+json; fhirVersion=4.0Key architectural rules governing the FHIR metadata endpoint include:
- Unauthenticated Public Access Recommended: Because client applications frequently inspect `/metadata` prior to initiating OAuth 2.0 login flows, HL7 and the ONC 21st Century Cures Act certification rules expect `GET [base]/metadata` to return HTTP `200 OK` without requiring an OAuth bearer token.
- Mode Query Parameter (`mode=full | normative | terminology`): By default (`mode=full`), the endpoint returns a complete `CapabilityStatement` resource. Clients may also request `GET [base]/metadata?mode=terminology` to retrieve a `TerminologyCapabilities` resource detailing supported code systems and value set expansion operations, or `mode=normative` to inspect only normative resource capabilities.
- Core Structural Declarations inside `CapabilityStatement.rest[]`: For a server (`rest.mode = “server”`), the `rest.resource[]` array enumerates every supported FHIR resource type (e.g., `Patient`, `Observation`, `Condition`) along with:
profile(canonical URL of the base system-wide profile) andsupportedProfile[](canonical URLs of specific profiles supported for individual records, such as US Core FHIRVital Signs profiles).interaction[].code: Supported RESTful verbs, such asread,vread,update,patch,delete,history-instance,create, andsearch-type.searchParam[],searchInclude[], andsearchRevInclude[]: Explicitly lists supported FHIR search parameters (name, canonical definition URL, and data type such as `token`, `date`, or `reference`).operation[]: Custom `$` operations supported on the resource or server root (such as `Patient/$match`, `Patient/$everything`, or Group `$export`).
What Is the Difference Between a CapabilityStatement Kind of Instance, Capability, and Requirements?
The mandatory CapabilityStatement.kind element (`code`: `instance | capability | requirements`) defines whether the resource describes a live deployed server, a generic software product, or an implementation specification:
CapabilityStatement.kind |
Semantic Definition | Required Element Constraints | Real-World Clinical Example |
|---|---|---|---|
instance |
Describes the actual, live capabilities and endpoint URLs of a specific deployed system instance. | MUST populate CapabilityStatement.implementation (including implementation.url base endpoint and description); usually also populates software. |
The JSON payload returned live by a hospital’s production Epic or HAPI FHIR endpoint at GET https://fhir.hospital.org/r4/metadata. |
capability |
Describes the generic capabilities of a software application or product release independent of any single customer installation. | MUST populate CapabilityStatement.software (name and version) and MUST NOT populate CapabilityStatement.implementation. |
A published capability artifact documenting what HAPI FHIR JPA Server v7.2.0 or Smile CDR supports out of the box. |
requirements |
Defines the normative expectations (SHALL / SHOULD / MAY conformance rules) that a server or client must satisfy to claim compliance with a standard. | MUST NOT populate implementation or software; uses HL7 Conformance Expectation extensions (`SHALL`, `SHOULD`, `MAY`) on interactions and search parameters. |
The `CapabilityStatement-us-core-server` artifact published inside the HL7 US Core FHIR Implementation Guide. |
CapabilityStatement.rest.security vs. .well-known/smart-configuration
In SMART on FHIR (HL7 SMART App Launch Framework STU 1.0 and STU 2.0+), client apps must dynamically discover the EHR’s OAuth 2.0 `authorize` and `token` endpoints. Modern FHIR servers expose security discovery in two ways:
- Primary Modern Standard — `GET [base]/.well-known/smart-configuration`: Required by SMART App Launch STU 2.0+ and ONC `(g)(10)` certification, requesting `[base]/.well-known/smart-configuration` returns a lightweight JSON document containing `authorization_endpoint`, `token_endpoint`, `introspection_endpoint`, `revocation_endpoint`, `jwks_uri`, `grant_types_supported`, `code_challenge_methods_supported` (requiring `S256` for PKCE), and an array of SMART `capabilities` (such as `launch-ehr`, `launch-standalone`, `client-public`, `client-confidential-symmetric`, `client-confidential-asymmetric`, `sso-openid-connect`, and `context-ehr-patient`).
- Legacy / Fallback Extension — `CapabilityStatement.rest.security`: For backward compatibility with SMART STU 1.0 clients, servers also populate `CapabilityStatement.rest[0].security.service` with code `SMART-on-FHIR` and attach the `http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris` extension holding `authorize` and `token` valueUri sub-extensions. When both exist, SMART STU 2.0 specifies that values in `.well-known/smart-configuration` take precedence.
How Do ONC (g)(10) Inferno Tests Validate CapabilityStatement and .well-known/smart-configuration?
Under the ONC Health IT Certification Program criterion 45 CFR § 170.315(g)(10) (Standardized API for Patient and Population Services), EHR vendors must pass automated testing using the open-source Inferno Framework (`inferno.healthit.gov`). Inferno executes rigorous structural and cross-endpoint checks against both discovery documents:
- FHIR Version & JSON Support Verification: Inferno queries `GET [base]/metadata` and verifies that the server returns a valid `CapabilityStatement` resource with `status = “active”`, `kind = “instance”`, `fhirVersion = “4.0.1”`, and `format` declaring support for `json` or `application/fhir+json`.
- US Core Profile & Interaction Auditing: For every USCDI clinical resource class required by US Core (such as `Patient`, `AllergyIntolerance`, `CarePlan`, `CareTeam`, `Condition`, `Device`, `DiagnosticReport`, `DocumentReference`, `Encounter`, `Goal`, `Immunization`, `MedicationRequest`, `Observation`, `Procedure`, `Provenance`), Inferno parses `CapabilityStatement.rest.resource[]` and verifies that the canonical URL of each required US Core Profile is listed in `profile` or `supportedProfile[]`. Note that for `Observation`, where US Core defines multiple distinct profiles (Laboratory Result, Pediatric BMI, Pulse Oximetry, Blood Pressure, etc.), declaring them in `supportedProfile[]` is mandatory.
- Dynamic Search Parameter Execution against Declared Capabilities: Inferno compares the `searchParam[]` declarations inside `CapabilityStatement.rest.resource[]` against the US Core Server CapabilityStatement (`SHALL` support single and composite search parameters) and then dynamically executes live `GET` and `POST _search` queries to prove the server actually implements what its `CapabilityStatement` advertises.
- SMART Discovery Endpoint Consistency: Inferno fetches `GET [base]/.well-known/smart-configuration`, validates all required JSON keys and HTTPS TLS 1.2+ transport, and—if OAuth URIs are also declared in `CapabilityStatement.rest.security`—verifies that the `authorize` and `token` URLs match identically across both endpoints without contradiction.
Frequently Asked Questions
What is a FHIR CapabilityStatement and how is it retrieved from GET [base]/metadata?
A FHIR CapabilityStatement is a normative HL7 FHIR metadata resource that documents the resource types, profiles, RESTful interactions (`read`, `search-type`, `create`), search parameters, and operations supported by a FHIR server. Client applications retrieve it by sending an HTTP GET [base]/metadata request with header Accept: application/fhir+json.
What is the difference between a CapabilityStatement kind of instance, capability, and requirements?
A kind of instance describes a specific live deployed server at a concrete base URL (requiring the implementation element); capability describes the generic features of a software product release independent of any specific deployment (requiring software and prohibiting implementation); and requirements specifies the normative SHALL/SHOULD conformance rules of an Implementation Guide such as US Core.
How do ONC (g)(10) Inferno tests validate CapabilityStatement and .well-known/smart-configuration?
The ONC Inferno `(g)(10)` Standardized API test kit queries both `GET [base]/metadata` and `GET [base]/.well-known/smart-configuration` to verify FHIR R4 (`4.0.1`) compliance, confirm that all mandatory US Core profiles are declared in `profile` or `supportedProfile[]`, verify that all required single and composite search parameters are advertised and functional, and ensure that OAuth 2.0 endpoints and PKCE (`S256`) capabilities match across both discovery documents.
