HL7 FHIR Architecture in Sparx EA: Modeling Healthcare Interoperability

FHIR is not only a technical specification — it is an architectural commitment. Sparx EA gives healthcare architects one governed model for the whole integration landscape: resource definitions, API contracts, capability statements, and the clinical systems that produce and consume health data, with approved profiles enforced through MDG Technology.

HL7 FHIR (Fast Healthcare Interoperability Resources) is now the dominant standard for health data exchange — mandated by US regulation, embedded in UK NHS frameworks, and central to Australian digital health programs. Every FHIR-enabled system publishes a capability statement, conforms to one or more profiles, and joins an integration topology that has to be governed, documented, and evolved. Left undocumented, that topology drifts. This article walks through how to model FHIR resources, API contracts, and capability statements in Sparx EA, and how to keep approved profiles under control so non-conformance is visible rather than discovered in production.

What HL7 FHIR is, and why it needs architectural governance

FHIR is the HL7 standard for health data exchange, built on RESTful APIs and ordinary web conventions. Where its predecessors struggled — HL7 v2 still drives legacy lab and ADT feeds, and HL7 v3 drew sustained criticism for its complexity — FHIR was deliberately designed for developer accessibility. Clinical and administrative information is structured into discrete resources, each a self-contained unit: Patient holds demographics, Observation carries lab results and vital signs, DiagnosticReport assembles a set of Observations into a completed result, and Encounter records the visit or episode.

Each resource has a defined structure in the specification, but profiles let implementers constrain or extend it for a given context. US Core defines how Patient and Observation must be populated for US health information exchange; NHS England has published profiles for the NHS Number, GP practice data, and national clinical coding. Profiles are where FHIR turns from a universal standard into an implementation reality — and where architectural governance stops being optional.

Without that governance, FHIR deployments fragment. Teams implement incompatible profiles, systems that claim conformance cannot actually exchange data, and the capability statement — the machine-readable declaration of what a server supports — becomes a critical artifact that nobody owns. The point of modeling FHIR in an EA repository is to give that artifact, and everything around it, a single owned home.

Modeling FHIR resources at the Information layer

In Sparx EA, FHIR resources sit at the Information layer — the conceptual level where data structures are defined independently of how they are stored or transported. The practical approach is a UML class diagram (or an ArchiMate Data Object view) with a «FHIR Resource» stereotype applied through MDG. Each resource becomes a stereotyped class whose attributes represent the key FHIR elements.

FHIR resource	Sparx EA modeling element	Key elements to capture as attributes
Patient	Data Object / UML Class, «FHIR Resource»	identifier, name, birthDate, gender, address
Observation	Data Object / UML Class, «FHIR Resource»	code (LOINC/SNOMED), value[x], subject, encounter
DiagnosticReport	Data Object / UML Class, «FHIR Resource»	code, result (→ Observation), subject, issued
Encounter	Data Object / UML Class, «FHIR Resource»	status, class, subject, period
Approved profile	Specialization of base resource, «FHIR Profile»	canonical URL, governing body, approval status

FHIR profiles are modeled as specializations of their base resource classes, with a «FHIR Profile» stereotype to distinguish an approved profile from the base specification. Tagged values on the profile element record the canonical URL, the governing body (US Core, NHS, or a local authority), and the approval status — which is what gives a governance committee one view of every profile cleared for use across the program.

References between resources — Observation.subject pointing to Patient, or DiagnosticReport.result pointing to Observation — are modeled as associations. That lets an architect trace data lineage end to end: from a measurement captured in an Observation, through the DiagnosticReport that presents it, to the patient whose record it belongs to.

FHIR API contracts at the Application layer

FHIR's REST API is the transport for resource exchange, so in application architecture terms each server endpoint is an Application Interface. The interface takes a name matching the FHIR base URL (for example https://fhir.hospital.org/R4), with sub-interfaces for specific resource endpoints such as GET /Patient or POST /Observation.

Each interface links to the Data Objects it exposes via Access relationships, and the FHIR server itself — an Application Component — realizes those interfaces and reaches the underlying data store. The capability statement is then represented as a Constraint or Principle element linked to that component, recording the supported FHIR version (R4 / R4B / R5), the supported resource types, the permitted interactions (read, search, create, update), and the supported search parameters. Modeled this way, the capability statement becomes an auditable part of the architecture rather than a document drifting in a separate wiki.

A worked example: a FHIR interoperability hub

Take a hospital standing up a FHIR-based interoperability hub that connects its EPR to consumer-facing patient apps and a regional data-sharing platform.

As-is. The EPR (Epic, Cerner, or similar) exposes a proprietary API, legacy HL7 v2 ADT feeds connect to the Patient Administration System, and no FHIR capability exists yet.

Target state, modeled in Sparx EA.

1. The EPR exposes a FHIR R4 endpoint — an Application Component (Epic FHIR Server) with interfaces for Patient, Observation, Appointment, and MedicationRequest.
2. A FHIR integration hub (middleware such as Azure Health Data Services or AWS HealthLake) sits between the EPR and consumers, modeled as an Application Component serving consumer interfaces and using the EPR's FHIR server.
3. Consumer applications — the NHS App, a patient portal, a third-party care-coordination platform — are Application Components that use the hub's interfaces, each linked through Access relationships to the resource types it actually consumes.
4. The data flow is traced at the Information layer: a Patient Observation created in the EPR moves through the hub and is read by the patient portal, with the ArchiMate Flow relationship labeled with the FHIR resource type being exchanged.

That single view becomes the canonical reference for integration decisions — which systems can exchange which data, which profiles are required, and which capability statements have been validated.

Profile governance as an MDG concern

Profiles are the core governance challenge in any multi-system FHIR architecture: vendors implement different versions of the same profile, clinical teams request custom extensions, and regulation mandates specific profiles for particular exchange scenarios. MDG Technology in Sparx EA is the natural home for keeping order. A «FHIR Profile» stereotype carries the tagged values that make conformance explicit and reportable.

Tagged value	What it records	Example
Profile URL	The canonical HL7/FHIR URL	hl7.org/fhir/us/core/...
Base Resource	The FHIR resource this profile constrains	Patient
Governing Body	Who owns and maintains the profile	US Core / NHS / Local
Approval Status	Lifecycle state for governance	Draft / Approved / Deprecated
Mandatory For	Exchange scenarios that require it	Regional data sharing
Conformance Level	Strength of the requirement	SHALL / SHOULD / MAY

When an architect models a new integration, the MDG toolbox surfaces approved profiles as selectable elements, and a model validation rule can flag any non-approved profile. From there a standard reporting layer can publish the profile inventory — how many approved, how many deprecated, how many pending review — so architecture governance runs off live model data rather than a spreadsheet that goes stale the week after it is written.

Making the FHIR architecture queryable

A large healthcare organization may run dozens of FHIR-enabled systems, hundreds of in-scope resource types, and several overlapping profiles. Reviewing diagrams by hand does not scale as an operational governance method, so the modeled architecture has to be queryable by the people who act on it.

Once FHIR resources, interfaces, and profiles are modeled consistently in Sparx EA, the repository can drive reporting and lookups for the questions that come up in practice:

• Which systems are FHIR-enabled, and what resources do they expose?
• Which systems consume the Observation resource?
• Which profiles are approved for the regional data-sharing program?
• Which integrations still run on HL7 v2, and do they have a FHIR migration date?

Answered from the live model rather than a stale document, these let program managers and clinical informatics leads get what they need without opening the modeling tool, and let the governance team spot drift between the approved architecture and what is actually deployed. For teams who want those answers delivered through the everyday business tools their stakeholders already use, that is exactly the gap AI Augmented Architecture is built to close.

Common questions

Do I need a special MDG extension to model FHIR?

Sparx EA does not ship a FHIR-specific MDG, but one is straightforward to configure using the built-in MDG Technology framework. Sparx Services can supply a pre-built FHIR MDG with stereotypes for resources, profiles, capability statements, and API interfaces — saving several days of setup.

Should I model FHIR as UML classes or ArchiMate Data Objects?

For a high-level interoperability architecture, ArchiMate Data Objects at the Information layer keep the model at the right abstraction for stakeholder communication. When you need detailed resource element structures for developer reference or governance, UML class diagrams with FHIR stereotypes give greater fidelity. Most organizations use both — ArchiMate at the architecture level, UML for detailed data design.

How do I handle FHIR R4 and R4B in the same model?

Put a tagged value on each FHIR server Application Component recording its supported version, then let a validation rule or report surface mismatches — for example a consumer requiring R4B connected to a server that only supports R4.

Where do capability statements live in the model?

Best represented as Constraint or Principle elements linked to the FHIR server Application Component via an Association. You can also attach the actual JSON capability statement as a linked document. The point is that it stays traceable to the server it describes.

How does FHIR modeling connect to broader clinical system governance?

FHIR sits at the integration layer of a wider clinical system architecture. In Sparx EA the FHIR view is one part of a larger model that also captures the EPR/EHR application landscape, clinical workflows at the Business layer, and infrastructure at the Technology layer. ArchiMate relationships trace the connections, so an architect can answer questions like: if this FHIR server goes down, which clinical workflows are affected?

Can Sparx EA help us prepare for a CMS interoperability audit?

Yes. The CMS Interoperability and Patient Access Rule requires payers and providers to expose specific FHIR APIs (Patient Access, Provider Directory, Drug Formulary). Modeling those APIs and their resource coverage in Sparx EA creates an auditable record — which systems expose which APIs, which profiles are implemented, and which capability statements have been validated.

How is profile governance different from standard data governance?

Standard data governance focuses on ownership, lineage, and quality. FHIR profile governance adds a conformance dimension — not just who owns a data element, but which profiles constrain how it is exchanged and which systems have been validated against them. The MDG stereotype approach lets both concerns live on the same model element.

Work with Sparx Services

Your FHIR integration architecture deserves more than a diagram in a wiki. Sparx Services helps healthcare teams build a Sparx EA environment where resources, profiles, API contracts, and capability statements are modeled, governed, and ready for the people who have to act on them. If you are also planning the systems underneath, our work on data architecture and solution architecture connects the FHIR layer to the broader landscape.