CapabilityStatement — FHIR server metadata

The identity card of a FHIR implementation: managed resources, allowed interactions, search parameters, security. The entry point for any discovery.

Purpose of the resource

CapabilityStatement declares the capabilities of a FHIR implementation — server or client. It is the first resource read by any FHIR client discovering a server, via the normative GET /metadata endpoint.

Three distinct usages (kind):

• instance — describes what this specific instance does (the server running on a given domain, at a given date).
• capability — describes what a family of implementations can do (e.g. a commercial FHIR product).
• requirements — describes what a deployment must support (e.g. ONC EHR requirements).

In 2026, every ONC-certified EHR in the US must expose a SMART on FHIR CapabilityStatement with US Core profiles. Third-party SMART apps rely on this CapabilityStatement to discover OAuth endpoints, available scopes, and accessible resources.

Key fields

/metadata endpoint

Every conformant FHIR server must expose GET /metadata returning the instance's CapabilityStatement. It's the FHIR equivalent of HTTP OPTIONS: discovery without authentication (implementation dependent).

Variants:

• GET /metadata — full CapabilityStatement.
• GET /metadata?mode=terminology — terminology capabilities (for terminology servers).
• GET /.well-known/smart-configuration — SMART configuration (OAuth endpoints, scopes), complete but distinct from /metadata.

JSON example

CapabilityStatement of a FHIR R5 server supporting Patient and Observation, with SMART on FHIR:

{
  "resourceType": "CapabilityStatement",
  "id": "ediverse-fhir-server",
  "url": "https://api.ediverse.io/fhir/metadata",
  "version": "1.0.0",
  "name": "EdiverseFhirServer",
  "title": "Ediverse FHIR R5 Server CapabilityStatement",
  "status": "active",
  "experimental": false,
  "date": "2026-05-14",
  "publisher": "Ediverse",
  "contact": [{
    "telecom": [{ "system": "url", "value": "https://ediverse.io" }]
  }],
  "kind": "instance",
  "implementation": {
    "description": "Production FHIR R5 server for Ediverse demo",
    "url": "https://api.ediverse.io/fhir"
  },
  "fhirVersion": "5.0.0",
  "format": ["application/fhir+json", "application/fhir+xml"],
  "rest": [{
    "mode": "server",
    "security": {
      "cors": true,
      "service": [{
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/restful-security-service",
          "code": "SMART-on-FHIR"
        }]
      }],
      "extension": [{
        "url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris",
        "extension": [
          { "url": "authorize", "valueUri": "https://api.ediverse.io/oauth2/authorize" },
          { "url": "token", "valueUri": "https://api.ediverse.io/oauth2/token" },
          { "url": "introspect", "valueUri": "https://api.ediverse.io/oauth2/introspect" }
        ]
      }]
    },
    "resource": [{
      "type": "Patient",
      "profile": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
      "interaction": [
        { "code": "read" },
        { "code": "search-type" },
        { "code": "create" },
        { "code": "update" }
      ],
      "searchParam": [
        { "name": "_id", "type": "token" },
        { "name": "identifier", "type": "token" },
        { "name": "name", "type": "string" },
        { "name": "birthdate", "type": "date" }
      ]
    }, {
      "type": "Observation",
      "interaction": [
        { "code": "read" },
        { "code": "search-type" }
      ],
      "searchParam": [
        { "name": "patient", "type": "reference" },
        { "name": "code", "type": "token" },
        { "name": "date", "type": "date" }
      ]
    }]
  }]
}

• kind=instance with implementation.url for this specific server.
• fhirVersion=5.0.0.
• REST server mode, SMART on FHIR security with three OAuth endpoints.
• Patient resource: 4 interactions (read, search, create, update), US Core profile, 4 search parameters.
• Observation resource: 2 interactions (read, search), 3 parameters.

REST API

• GET /metadata — normative endpoint, returns CapabilityStatement.
• GET /metadata?_format=json — force JSON format.
• GET /CapabilityStatement?_id=...&url=... — search by canonical URL (on a registry server).
• POST /CapabilityStatement — create (on registry servers).
• GET /CapabilityStatement/$conforms?left=...&right=... — composite comparison operation.

Profiles

Common pitfalls

• Protected /metadata endpoint — many implementations require OAuth on /metadata. The spec is clear: /metadata must be public, otherwise SMART discovery is impossible.
• Lying searchParam list — if the CapabilityStatement advertises a parameter the server doesn't support, third-party apps will silently break. Always auto-generate from code, never by hand.
• Missing profile — for constrained resources (US Core, FR Core), omitting resource.profile prevents client-side validators from working.
• Inconsistent fhirVersion — server claims 5.0.0 but returns 4.0.1 JSON. Always sync via generated types.
• Wrong kind — use capability for a software product and instance for a specific deployment. An EHR vendor publishes a capability; each hospital deploying it publishes an instance.

Related resources

• ImplementationGuide — IG referenced by implementationGuide.
• StructureDefinition — profile referenced by resource.profile.
• OperationDefinition — supported operations.
• SearchParameter — custom search parameters.
• MessageDefinition / GraphDefinition — for supported messages and graphs.
• TerminologyCapabilities — specific variant for terminology servers.