Skip to content

FHIR 101 for Nexus EMR Developers

Welcome! If you're an experienced Java or JavaScript developer joining the Nexus EMR project, you'll find many familiar software engineering concepts here. However, FHIR (Fast Healthcare Interoperability Resources) has its own specific terminology and a distinct approach to data modeling and exchange. This guide provides a brief introduction to the core FHIR concepts you'll encounter most frequently within the Nexus EMR project.

Goal: To help you understand the structure, files, and basic principles of the Nexus EMR FHIR specification, so you can navigate the codebase and contribute effectively.

What is FHIR? (The 30-Second Version)

FHIR (pronounced "fire") is a standard from HL7 (Health Level Seven International) for exchanging healthcare information electronically. It defines:

  1. Data "Resources": Building blocks for healthcare data (like Patient, Observation, MedicationRequest).
  2. APIs: How to request and send these resources.
  3. Conformance Mechanisms: How to adapt the base standard for specific needs (this is what Nexus EMR heavily uses).

Its primary goal is interoperability – allowing different healthcare systems to share and understand data meaningfully.

Core FHIR Concepts You'll Encounter in Nexus EMR

Here are the key FHIR terms and ideas, and where you'll see them in the Nexus EMR project:

1. Resources

  • What they are: The fundamental building blocks of FHIR data. Think of them like "classes" or "data objects" representing specific healthcare concepts.
  • Examples: Patient, Observation (for lab results, vitals), AllergyIntolerance, MedicationRequest.
  • In Nexus EMR: * You'll see examples of these as JSON files in src/examples/ (e.g., NexusEmrCorePatient-example.json). * The base definitions of these resources come from the official HL7 FHIR specification. Nexus EMR profiles these base resources.
  • Key Field: Every FHIR resource instance has a resourceType field (e.g., "resourceType": "Patient").

2. Elements

  • What they are: The "fields" or "properties" of a Resource.
  • Examples: A Patient resource has elements like name, birthDate, gender, identifier. An Observation has status, code, valueQuantity.
  • Data Types: Elements have specific data types (e.g., string, boolean, date, dateTime, Identifier, CodeableConcept, Reference). You'll see these in the FSH definitions.
  • Cardinality: How many times an element can appear (e.g., 0..1 for optional, 1..1 for mandatory, 0..* for optional repeating, 1..* for mandatory repeating).

3. Identifiers & References

  • Identifiers: FHIR uses structured identifiers for many things, especially resources. An identifier typically has a system (a URL indicating the type of identifier, like a provincial health number system) and a value. * In Nexus EMR: See docs/NexusEmrIdentifiersAndReferences.md. The identifier element is crucial in Nexus EMR profiles.
  • References: How resources link to each other. Instead of direct database-style foreign keys, FHIR often uses logical references that can include identifiers. * Example: An Observation will have a subject element that references a Patient resource. * In Nexus EMR: * subject only Reference(NexusEmrCorePatient) in FSH means the subject must point to a patient conforming to the NexusEmrCorePatient profile.

4. Profiles (The Core of Nexus EMR FSH files)

  • What they are: The most important concept for understanding Nexus EMR! Base FHIR resources are often very broad to cover many international use cases. A Profile is a set of constraints and/or extensions applied to a base FHIR Resource (or data type) to adapt it for a specific context or use case.
  • Purpose: * To make elements mandatory (1..1). * To restrict the allowed data types of an element. * To fix the value of an element (e.g., status must be active). * To bind an element to a specific set of codes (see ValueSets below). * To add new elements (see Extensions below).
  • In Nexus EMR: This is what most of the .fsh files in src/fsh/resources/ define. For example, StructureDefinition-Nexus EMR-patient.fsh defines the NexusEmrCorePatient profile, which constrains the base Patient resource for Nexus EMR needs.
  • Result: A Profile is itself a FHIR resource called a StructureDefinition.

5. FHIR Shorthand (FSH - .fsh files)

  • What it is: A human-readable language specifically designed for defining FHIR Profiles, Extensions, ValueSets, and other conformance artifacts. It's much more concise than editing complex FHIR StructureDefinition JSON directly.
  • In Nexus EMR: This is the "raw code" for our FHIR specifications. You'll see files like NexusEmrCorePatient.fsh. * Profile: NexusEmrCorePatient declares a new profile. * Parent: Patient specifies it's based on the Patient resource. * * identifier 1..* MS is a rule constraining the identifier element.
  • SUSHI: The tool that compiles FSH files (.fsh) into FHIR StructureDefinition JSON resources (which then go into the fsh-generated/resources/ directory and are used by the IG Publisher).

6. Extensions

  • What they are: Sometimes, a base FHIR resource or an existing profile doesn't have an element to capture a piece of information needed for a specific use case. Extensions allow you to add new elements in a standardized way.
  • In Nexus EMR: * Defined in FSH (e.g., NexusEmrCoreAppState.fsh defines extensions like AppStateStringValue). * In JSON examples, they appear in an extension array.

7. Terminology: ValueSets & CodeSystems

  • The Need: Many FHIR elements are "coded," meaning their value comes from a defined set of codes (e.g., Observation.status can be "registered", "preliminary", "final", "amended", etc.).
  • CodeSystem: A set of codes with their meanings (e.g., SNOMED CT, LOINC, or simpler ones like "male", "female", "other"). * In Nexus EMR: Some local CodeSystems might be defined, but often we refer to external ones like $SCT (SNOMED CT) or $LNC (LOINC) using aliases in FSH.
  • ValueSet: A curated collection of codes from one or more CodeSystems, selected to represent the allowed values for a particular element in a specific context. * In Nexus EMR: Defined in FSH (e.g., NexusEmrConditionCodesVS in NexusEmrCoreCondition.fsh). * Profiles bind elements to ValueSets using rules like * clinicalStatus from <ValueSetURI> (required).

8. Canonical URLs

  • What they are: Globally unique, versionable web addresses (URLs) that identify FHIR conformance resources (Profiles, Extensions, ValueSets, CodeSystems, NamingSystems, etc.).
  • Importance: They are the definitive way to refer to a specific definition.
  • In Nexus EMR: * Defined in FSH: Alias: $NexusEmrCorePatient = https://fhir.apps.health/StructureDefinition/nexus-emr-core-patient. * Seen in JSON examples: "meta": { "profile": ["https://fhir.apps.health/StructureDefinition/nexus-emr-core-patient"] }. * Referenced in docs/NexusEmrCanonicalUrls.md.

9. Must Support (MS flag)

  • What it is: A flag in a Profile (FSH: * identifier 1..* MS) indicating that implementers of the profile must support this element. "Support" means they must be ableto process it meaningfully (store, display, query, etc.), though not necessarily populate it in every instance.
  • In Nexus EMR: Used to highlight key elements that downstream systems should expect and be able to handle.

10. Implementation Guides (IGs)

  • What they are: A published set of FHIR profiles, extensions, value sets, examples, and narrative documentation that describes how FHIR should be used for a specific purpose or in a particular realm (like Nexus EMR).
  • IG Publisher: The HL7 tool (which requires Java and Ruby) that takes FSH, FHIR JSON definitions, markdown documentation, and templates, and generates a human-readable website (the IG).
  • In Nexus EMR: * The _01preprocess.js script prepares documentation and FSH into the input/ directory. * ImplementationGuide-nexus-emr.fsh (in src/fsh/resources/) defines the structure of our IG. * The _genonce.sh script (called by _02build.js) likely runs the IG Publisher. * The final IG website is generated into the output/ directory.

How Nexus EMR Uses These Concepts

  1. Defines Data Standards: Nexus EMR uses FSH to create Profiles (e.g., NexusEmrCorePatient, NexusEmrCoreObservation) that constrain base FHIR resources for consistent data representation from various EMRs.
  2. Handles Terminology: It defines ValueSets (e.g., NexusEmrConditionCodesVS) to specify allowed codes for certain elements.
  3. Extends FHIR: It creates Extensions (e.g., AppStateStringValue) for data not covered by base FHIR.
  4. Provides Examples: JSON files in src/examples/ show how data conforming to Nexus EMR profiles looks.
  5. Publishes an IG: All these artifacts, along with documentation from docs/, are compiled into a web-based Implementation Guide.

Key Files/Folders in Nexus EMR to Note

  • src/fsh/resources/: This is where the primary FSH definitions (Profiles, Extensions, ValueSets) live. This is the "raw code" of the FHIR specification.
  • src/fsh/aliases.fsh: Common aliases for URLs used across FSH files.
  • src/examples/: JSON example instances corresponding to the profiles.
  • src/fsh/resources/ImplementationGuide-nexus-emr.fsh: Defines the structure and pages of the published Implementation Guide.
  • docs/: Markdown documentation that becomes part of the IG and explains concepts, mappings (like CII/CPAR), etc.
  • _01preprocess.js, _02build.js: Key scripts for the build process.

Next Steps & Further Learning

  1. Explore: Open a simple profile, like src/fsh/resources/StructureDefinition-Nexus EMR-patient.fsh, and its corresponding example, src/examples/NexusEmrCorePatient-example.json. Try to see how the FSH rules translate to the structure of the JSON.
  2. Read the README.md and docs/: These provide project-specific context.
  3. Official FHIR Documentation: For deeper dives, hl7.org/fhir/ is the ultimate reference. Start with the "Key Concepts" and "Developer's Intro."
  4. FHIR Shorthand (FSH) School: fshschool.org offers excellent tutorials on FSH.
  5. Nexus EMR FHIR Modelling Guidelines: Review the philosophy and required sections in the persona prompt to understand the specific rules Fire Blackwell (and thus, you) must follow.

This should give you a solid foundation. Don't hesitate to ask questions as you encounter new concepts!