Skip to content

FHIR 101 for Polaris Developers

Welcome! If you're an experienced Java or JavaScript developer joining the Polaris 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 Polaris project.

Goal: To help you understand the structure, files, and basic principles of the Polaris 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 Polaris heavily uses).

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

Core FHIR Concepts You'll Encounter in Polaris

Here are the key FHIR terms and ideas, and where you'll see them in the Polaris 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 Polaris:
    • You'll see examples of these as JSON files in src/examples/ (e.g., PolarisCorePatient-example.json).
    • The base definitions of these resources come from the official HL7 FHIR specification. Polaris 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 Polaris: See docs/PolarisIdentifiersAndReferences.md. The identifier element is crucial in Polaris 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 Polaris: * subject only Reference(PolarisCorePatient) in FSH means the subject must point to a patient conforming to the PolarisCorePatient profile.

4. Profiles (The Core of Polaris FSH files)

  • What they are: The most important concept for understanding Polaris! 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 Polaris: This is what most of the .fsh files in src/fsh/resources/ define. For example, StructureDefinition-Polaris-patient.fsh defines the PolarisCorePatient profile, which constrains the base Patient resource for Polaris 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 Polaris: This is the "source code" for our FHIR specifications. You'll see files like PolarisCorePatient.fsh.
    • Profile: PolarisCorePatient 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 Polaris:
    • Defined in FSH (e.g., PolarisCoreAppState.fsh defines extensions like AppStateStringValue).
    • Used within other profiles when needed (e.g., PolarisCoreRosterPanel.fsh uses several CPAR-specific extensions).
    • 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 Polaris: 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 Polaris: Defined in FSH (e.g., PolarisConditionCodesVS in PolarisCoreCondition.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 Polaris:
    • Defined in FSH: Alias: $PolarisCorePatient = https://fhir.apps.health/StructureDefinition/polaris-core-patient.
    • Seen in JSON examples: "meta": { "profile": ["https://fhir.apps.health/StructureDefinition/polaris-core-patient"] }.
    • Referenced in docs/PolarisCanonicalUrls.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 Polaris: 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 Polaris).
  • 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 Polaris:
    • The _01preprocess.js script prepares documentation and FSH into the input/ directory.
    • ImplementationGuide-polaris.fsh (in input/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 Polaris Uses These Concepts

  1. Defines Data Standards: Polaris uses FSH to create Profiles (e.g., PolarisCorePatient, PolarisCoreObservation) that constrain base FHIR resources for consistent data representation from various EMRs.
  2. Handles Terminology: It defines ValueSets (e.g., PolarisConditionCodesVS) 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 Polaris 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 Polaris to Note

  • src/fsh/resources/: This is where the primary FSH definitions (Profiles, Extensions, ValueSets) live. This is the "source 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.
  • input/fsh/resources/ImplementationGuide-polaris.fsh: Defines the structure and pages of the published Implementation Guide. This is largely generated by _01preprocess.js.
  • 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-Polaris-patient.fsh, and its corresponding example, src/examples/PolarisCorePatient-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. Polaris 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!