CapabilityStatement — Métadonnées d'un serveur FHIR

La fiche d'identité d'une implémentation FHIR : ressources gérées, interactions permises, paramètres de recherche, sécurité. Le point d'entrée de toute découverte.

Objet de la ressource

CapabilityStatement déclare les capacités d'une implémentation FHIR — serveur ou client. C'est la première ressource lue par tout client FHIR qui découvre un serveur, via l'endpoint normatif GET /metadata.

Trois usages distincts (kind) :

• instance — décrit ce que fait cette instance précise (le serveur tournant sur tel domaine, à telle date).
• capability — décrit ce qu'une famille d'implémentations peut faire (ex : un logiciel FHIR commercialisé).
• requirements — décrit ce qu'un déploiement doit supporter (ex : exigences ONC pour les EHR certifiés).

En 2026, tout EHR ONC-certifié aux États-Unis doit exposer une CapabilityStatement SMART on FHIR avec les profils US Core. C'est sur cette CapabilityStatement que les apps tierces (SMART apps) s'appuient pour découvrir les endpoints OAuth, scopes disponibles, et ressources accessibles.

Champs clés

Endpoint /metadata

Tout serveur FHIR conforme doit exposer GET /metadata retournant la CapabilityStatement de l'instance. C'est l'équivalent du OPTIONS HTTP côté FHIR : découverte sans authentification (selon implémentation).

Variantes :

• GET /metadata — full CapabilityStatement.
• GET /metadata?mode=terminology — capacités terminologiques (pour les serveurs de terminology).
• GET /.well-known/smart-configuration — configuration SMART (endpoints OAuth, scopes), complète mais distincte de /metadata.

Exemple JSON

CapabilityStatement d'un serveur FHIR R5 supportant Patient et Observation, avec 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 avec implementation.url pour ce serveur précis.
• fhirVersion=5.0.0.
• Mode REST serveur, sécurité SMART on FHIR avec les trois endpoints OAuth.
• Resource Patient : 4 interactions (read, search, create, update), profil US Core, 4 paramètres de recherche.
• Resource Observation : 2 interactions (read, search), 3 paramètres.

API REST

• GET /metadata — endpoint normatif, retourne la CapabilityStatement.
• GET /metadata?_format=json — force le format JSON.
• GET /CapabilityStatement?_id=...&url=... — recherche par URL canonique (sur un serveur de registre).
• POST /CapabilityStatement — créer (sur les serveurs registry).
• GET /CapabilityStatement/$conforms?left=...&right=... — opération composite de comparaison.

Profils

Pièges courants

• Endpoint /metadata protégé — beaucoup d'implémentations exigent un OAuth pour /metadata. La spec dit clairement : /metadata doit être public, sinon la découverte SMART est impossible.
• Liste de searchParam mensongère — si la CapabilityStatement annonce un paramètre que le serveur ne supporte pas, les apps tierces casseront silencieusement. Toujours auto-générer cette liste depuis le code, jamais à la main.
• Manque de profile — pour les ressources contraintes (US Core, FR Core), oublier la déclaration resource.profile empêche les validateurs côté client.
• fhirVersion inconsistant — le serveur dit supporter 5.0.0 mais retourne du JSON 4.0.1. Toujours synchroniser via les types générés.
• kind incorrect — utiliser capability pour un produit logiciel et instance pour un déploiement précis. Un EHR vendeur publie une capability, chaque hôpital qui déploie publie une instance.

Ressources liées

• ImplementationGuide — IG référencé par implementationGuide.
• StructureDefinition — profil référencé par resource.profile.
• OperationDefinition — opérations supportées.
• SearchParameter — paramètres de recherche custom.
• MessageDefinition / GraphDefinition — pour les messages et graphes supportés.
• TerminologyCapabilities — variante spécifique pour les serveurs de terminology.