ediverse

Type to search across standards, messages, tools and glossary.

ediverse Explore the platform

Spotlight PEPPOL BIS Billing 3.0 The EU e-invoicing mandate is here — France Sept 2026, Belgium Jan 2026, Germany 2025.

— 01

Foundations

— 02

Standards

— 03

Flagship messages

— 04

Tools

ActorDefinition — Formal definition of an actor

A new resource type introduced in FHIR R5. Formally describes a conceptual actor inside an implementation guide: consumer system, patient app, EHR, identity provider. The cornerstone of IHE and SMART on FHIR scenarios.

Purpose of the resource

A FHIR implementation guide does not only describe resources and constraints — it also describes interaction scenarios between systems. To formalise these scenarios, FHIR R5 adds the actor concept, long absent from the standard core.

An ActorDefinition can represent a consumer system ("SMART on FHIR patient-facing app"), a producer system ("EHR Order Placer"), a person in a workflow ("Dispensing pharmacist"), or an agentic chain ("Clinical Decision Support"). Each ActorDefinition is referenced by the guide's ExampleScenario and CapabilityStatement.

Key fields

FieldTypeCardinalityRole
urluri0..1Canonical URL.
versionstring0..1Semantic version.
namestring0..1Machine name (PascalCase).
titlestring0..1Readable title.
statuscode1..1draft, active, retired, unknown.
experimentalboolean0..1Experimental flag.
datedateTime0..1Publication date.
publisherstring0..1Publishing entity.
contactContactDetail[]0..*Technical contact.
descriptionmarkdown0..1Rich description.
typecode1..1person, system.
documentationmarkdown0..1Associated documentation.
referenceurl[]0..*External links (RFCs, industry specifications).
capabilitiescanonical(CapabilityStatement)0..1Expected / provided REST capabilities.
derivedFromcanonical(ActorDefinition)[]0..*Parent actor (capability inheritance).

JSON example

A patient-facing SMART on FHIR app, derived from an OAuth2 confidential client profile:

json actordefinition-example.json 
{
  "resourceType": "ActorDefinition",
  "id": "smart-on-fhir-client",
  "url": "http://hl7.org/fhir/smart-app-launch/ActorDefinition/smart-on-fhir-client",
  "version": "2.2.0",
  "name": "SmartOnFhirClient",
  "title": "SMART on FHIR Patient-Facing App",
  "status": "active",
  "experimental": false,
  "date": "2026-05-16",
  "publisher": "HL7 International — FHIR Infrastructure",
  "contact": [{
    "name": "FHIR Infrastructure",
    "telecom": [{ "system": "url", "value": "http://hl7.org/Special/committees/fiwg" }]
  }],
  "description": "A patient-facing SMART on FHIR app that authenticates with OAuth 2 + OpenID Connect and consumes /Patient, /Observation, /Condition data from a SMART-enabled EHR.",
  "type": "system",
  "documentation": "https://hl7.org/fhir/smart-app-launch/STU2/app-launch.html",
  "reference": [
    "https://hl7.org/fhir/smart-app-launch/STU2/scopes-and-launch-context.html"
  ],
  "capabilities": "CapabilityStatement/smart-on-fhir-client",
  "derivedFrom": [
    "http://hl7.org/fhir/smart-app-launch/ActorDefinition/oauth2-confidential-client"
  ]
}

Typical use cases

  • IHE Profiles: every IHE actor (Document Source, Document Consumer, Patient Source, Identity Source…) can be modelled as an ActorDefinition.
  • SMART App Launch IG: defines Patient App, Provider App, EHR, Authorisation Server.
  • US Core IG: describes the ONC-compliant EHR actor, the Patient App actor, the Public Health Authority actor.
  • FR Core / FHIR France: DMP Source, DMP Consumer, INS Source actors.
  • HSPC, FHIR at Scale Taskforce scenarios: describes the roles of components inside a regional Health Information Exchange (HIE).

Common pitfalls

  • Conceptual actor vs real system confusion: ActorDefinition describes an abstract role inside an IG, not a deployed instance. Real systems are represented by Endpoint, Device or Organization.
  • Wrong type: person for a human (pharmacist, prescriber), system for software. Mixing them up breaks scenario visualisation tools.
  • Unbound capabilities: an ActorDefinition without capabilities has no verifiable technical contract. Always point to a CapabilityStatement when possible.
  • No derivedFrom: inheriting from a base actor avoids redefining 200 lines of OAuth2 capabilities. Use inheritance.
  • References to stale documentation: external URLs must be stable (versioned) — otherwise the guide rots over time.
  • ExampleScenario — uses several ActorDefinition to describe a workflow.
  • CapabilityStatement — describes an actor's REST capabilities.
  • ImplementationGuide — references ActorDefinitions in its table of contents.
  • Requirements — functional requirements satisfied by an actor.

See also: ExampleScenario — interaction scenarios and CapabilityStatement — REST capabilities.