From 0dd8d82d5007b6b04628bb11dbebee0892965eca Mon Sep 17 00:00:00 2001 From: Chris Moesel Date: Thu, 26 Mar 2026 11:48:34 -0400 Subject: [PATCH 01/10] Use Zulip #shorthand instead of #fsh-courses --- fsh-seminar/README.md | 2 +- fsh-seminar/input/pagecontent/index.md | 4 ++-- index.html | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/fsh-seminar/README.md b/fsh-seminar/README.md index 7c46c68..9368719 100644 --- a/fsh-seminar/README.md +++ b/fsh-seminar/README.md @@ -20,4 +20,4 @@ Course authors include: - Max Masnick - May Terry -Questions/comments: [chat.fhir.org](https://chat.fhir.org/#narrow/stream/322131-fsh-courses) \ No newline at end of file +Questions/comments: [chat.fhir.org](https://chat.fhir.org/#narrow/channel/215610-shorthand) \ No newline at end of file diff --git a/fsh-seminar/input/pagecontent/index.md b/fsh-seminar/input/pagecontent/index.md index 4e4c623..67d6d2d 100644 --- a/fsh-seminar/input/pagecontent/index.md +++ b/fsh-seminar/input/pagecontent/index.md @@ -47,7 +47,7 @@ We recommend completing the course materials over two days as described below.
  • Complete the setup instructions
    • - ~1 hour; help available on chat.fhir.org + ~1 hour; help available on chat.fhir.org @@ -121,7 +121,7 @@ We recommend completing the course materials over two days as described below. - Chris Moesel (MITRE) - May Terry (MITRE) -If you have questions or comments, please contact us on chat.fhir.org. +If you have questions or comments, please contact us on chat.fhir.org. MITRE: Approved for Public Release. Distribution Unlimited. Case Number 19-3439. diff --git a/index.html b/index.html index d8f0b3e..d74da58 100644 --- a/index.html +++ b/index.html @@ -96,7 +96,7 @@

    - Questions? Ask on Zulip. + Questions? Ask on Zulip.

    From eed1cad0fb0fee600a6291efbab20e5c7ebf327b Mon Sep 17 00:00:00 2001 From: Chris Moesel Date: Thu, 26 Mar 2026 13:56:18 -0400 Subject: [PATCH 02/10] Update index.md - Replace Deep Dive TBD with real topics - Replace SMART Cards link w/ mCODE link - Minor grammar fixes --- fsh-seminar/Requirements-fromNarrative.json | 2 +- fsh-seminar/input/pagecontent/index.md | 18 ++++++++++++++---- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/fsh-seminar/Requirements-fromNarrative.json b/fsh-seminar/Requirements-fromNarrative.json index 2011cc2..b990b08 100644 --- a/fsh-seminar/Requirements-fromNarrative.json +++ b/fsh-seminar/Requirements-fromNarrative.json @@ -1,7 +1,7 @@ { "resourceType" : "Requirements", "id" : "fromNarrative", - "url" : "http://hl7.org/fhir/xver-extensions/Requirements/fromNarrative", + "url" : "https://fshschool.org/courses/fsh-seminar/Requirements/fromNarrative", "name" : "FromNarrative", "title" : "Narrative Conformance Statements", "status" : "active", diff --git a/fsh-seminar/input/pagecontent/index.md b/fsh-seminar/input/pagecontent/index.md index 67d6d2d..43eacd3 100644 --- a/fsh-seminar/input/pagecontent/index.md +++ b/fsh-seminar/input/pagecontent/index.md @@ -6,12 +6,12 @@ This course is a comprehensive overview of IG authoring for those interested in ### Learning objectives -1. Become familiar with the FHIR specification, and commonly used FHIR resources and element types. +1. Become familiar with the FHIR specification, and commonly used FHIR resources and element types 2. Learn the recommended process for successfully planning a new IG 3. Gain proficiency with the FHIR Shorthand ecosystem of tools (FSH, GoFSH, SUSHI) 4. Learn how to create the common components of an IG, including FHIR profiles, code systems, and value sets 5. Learn about key FHIR profiling concepts including value set binding, cardinality, MustSupport, slicing, and extensions -6. Awareness of common clinical code systems including LOINC, SNOMED, ICD10, and code systems in the HL7 terminology list +6. Understand the purpose of common clinical code systems including LOINC, SNOMED, ICD10, and code systems in the HL7 terminology list ### Prerequisites @@ -62,7 +62,7 @@ We recommend completing the course materials over two days as described below.
  • What's the purpose of an IG?
  • What are the common components of an IG?
  • How to approach reading an unfamiliar IG
    • -
  • Review of the SMART Health Cards: Vaccination & Testing IG
    • +
  • Review of the minimal Common Oncology Data Elements (mCODE) IG
    • ~1 hour @@ -106,7 +106,17 @@ We recommend completing the course materials over two days as described below. Deep Dive With FSH
      -
    1. TBD, but likely: slicing, extensions, invariants, CapabilityStatements and SearchParams
      2. +
    2. IG Overview: review purposes and processes for creating FHIR IGs
      3. +
    3. FSH Profiles: cardinality, flags, types, patterns, bindings, extensions, metadata
      4. +
    4. Slicing: defining slicing logic, creating slices, referencing slices
      5. +
    5. FHIRPath: path navigation, common expressions, testing and debugging
      6. +
    6. Invariants: defining and using invariants (a.k.a. constraints)
      7. +
    7. FSH Extensions: simple and complex extensions
      8. +
    8. FSH Terminology: value sets and code systems
      9. +
    9. FSH Instances: example and definition instances, rule sets, search parameters, operations, capability statements
      10. +
    10. Narrative: creating pages in your IG and inserting content into formal definition pages
      11. +
    11. Configuration: sushi-config.yaml and the ImplementationGuide resource
      12. +
    12. GoFSH: converting an existing project to FSH
    2-3 hours From 1a5c0114fcbeacd3781d943ff94956fe4b2eb441 Mon Sep 17 00:00:00 2001 From: Chris Moesel Date: Fri, 27 Mar 2026 09:59:34 -0400 Subject: [PATCH 03/10] Update setup page - Point to newer FHIR introduction video (2025 vs 2019) - Point to new FSH Plugin (now owned by HL7) - Use `_build` scripts instead of `_updatePublisher`/`_genonce` - Fix incorrect IG paths - Minor grammar / punctuation --- fsh-seminar/input/pagecontent/setup.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fsh-seminar/input/pagecontent/setup.md b/fsh-seminar/input/pagecontent/setup.md index 6c05916..b1bd467 100644 --- a/fsh-seminar/input/pagecontent/setup.md +++ b/fsh-seminar/input/pagecontent/setup.md @@ -1,20 +1,20 @@ ### FHIR Background -- [45 minute FHIR introduction video](https://www.youtube.com/watch?v=rJ_VEKiR55I) -- please consider viewing before the course begins +- [35 minute FHIR introduction video](https://youtu.be/Dz3HOaf6e-0?si=939LncJI5OKdPS_J) -- please consider viewing before the course begins ### Local environment As part of this course, you will edit and build a FHIR Implementation Guide on your computer. To do this, you will need the following: -1. Install [Visual Studio Code](https://code.visualstudio.com) and the [FSH language extension](https://marketplace.visualstudio.com/items?itemName=MITRE-Health.vscode-language-fsh) +1. Install [Visual Studio Code](https://code.visualstudio.com) and the [FSH language extension](https://marketplace.visualstudio.com/items?itemName=FHIR-Shorthand.vscode-fsh) 2. Install a Java runtime 3. Install Ruby and Jekyll using [these OS-specific instructions](https://jekyllrb.com/docs/installation/#guides) 4. Install SUSHI using [these directions](https://fshschool.org/docs/sushi/installation/) 5. Download the syllabus IG from `https://github.com/FSHSchool/courses-fsh-seminar-exercise/archive/refs/heads/main.zip` and unzip it, or `git clone https://github.com/FSHSchool/courses-fsh-seminar-exercise.git` -6. Open a Terminal/Command Prompt window inside the IG folder, and run `./_updatePublisher.sh` (Mac/Linux) or `_updatePublisher.bat` (Windows) from the command line. - - This will automatically download the latest `publisher.jar` release from and put it in the `input-cache/` folder inside the IG folder. - - The IG folder will be `courses-fsh-seminar-exercise-main/input-cache/` if you used the `.zip` download, or `courses-fsh-seminar-exercise/input-cache/` if you used `git clone`. -7. Run `./_genonce.sh` (Mac/Linux) or `_genonce.bat` (Windows) + - The IG folder will be `courses-fsh-seminar-exercise-main/` if you used the `.zip` download, or `courses-fsh-seminar-exercise/` if you used `git clone`. +6. Open a Terminal/Command Prompt window inside the IG folder, and run `./_build.sh update` (Mac/Linux) or `_build.bat update` (Windows) from the command line, answering `Y` to each of the prompts + - This will automatically download the latest `publisher.jar` release from and put it in the `input-cache/` folder inside the IG folder +7. Run `./_build.sh build` (Mac/Linux) or `_build.bat build` (Windows) 8. Open `output/index.html` from inside your IG folder. You should see a mostly-empty IG home page that says "FSHSeminarExercise" on it. ### JSON background From 7ba7851d690fa17d57475e55ef1e01eb5c6025ba Mon Sep 17 00:00:00 2001 From: Chris Moesel Date: Fri, 27 Mar 2026 12:07:54 -0400 Subject: [PATCH 04/10] Updates to Reading an IG - Replace mCODE GitHub links with IG links - Reference DaVinci CDex as an example of "community of implementation" IG - Indicate that OperationDefinition is also a good place to start for understanding APIs in an IG - When reviewing specific mCODE profiles, always link to mCODE STU2 - Fix link to FHIR core description of MustSupport (anchor changed in R5) - Grammar and spelling NOT DONE: I did not update mCODE discussions to STU4 or update screenshots, but we should probably do this. --- .../input/pagecontent/01-reading-an-ig.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/fsh-seminar/input/pagecontent/01-reading-an-ig.md b/fsh-seminar/input/pagecontent/01-reading-an-ig.md index aba634a..d28f709 100644 --- a/fsh-seminar/input/pagecontent/01-reading-an-ig.md +++ b/fsh-seminar/input/pagecontent/01-reading-an-ig.md @@ -24,13 +24,13 @@ FHIR Implementation Guides (IGs) fill in these gaps in different ways depending Describes how to represent a clinical or business concept, without defining an API for exchanging these data. - Example: [International Patient Summary](https://hl7.org/fhir/uv/ips/), [mCODE](https://github.com/HL7/fhir-mCODE-ig) + Example: [International Patient Summary](https://hl7.org/fhir/uv/ips/), [mCODE](https://hl7.org/fhir/us/mcode/) 3. **Community of Implementation** An agreement on how data are exchanged by a group of actors (i.e., contains an API). - Example: [mCODE](https://github.com/HL7/fhir-mCODE-ig), [US Core](https://www.hl7.org/fhir/us/core/) + Example: [DaVinci Clinical Data Exchange (CDex)](https://hl7.org/fhir/us/davinci-cdex/), [US Core](https://www.hl7.org/fhir/us/core/) 4. **Product IGs** @@ -90,7 +90,7 @@ Narrative conformance criteria typically use [RFC 2119](https://datatracker.ietf For example, if you are interested in gaining a general understanding of an IG, you may want to review all the computable content superficially (which can be done by clicking each link on the `artifacts.html` page of the IG). - Alternatively, you may be interested in an implementation for a specific actor or use case. In this case, the IG will hopefully provide some guidance on which resources are most important. If not, for content-related use cases, `Profiles` are likely the best entry point to the computable content. For API-driven use cases, `CapabilityStatements` are a logical starting point. + Alternatively, you may be interested in an implementation for a specific actor or use case. In this case, the IG will hopefully provide some guidance on which resources are most important. If not, for content-related use cases, `Profiles` are likely the best entry point to the computable content. For API-driven use cases, [CapabilityStatements](https://hl7.org/fhir/capabilitystatement.html) and [OperationDefinitions](https://hl7.org/fhir/operationdefinition.html) are logical starting points. The next few sections will provide an overview of common types of computable artifacts. @@ -187,10 +187,10 @@ Additionally, if a resource instance follows the rules defined by a FHIR profile [^meta-profile]: Resource instances can actually specify which profiles they intend to conform to using the `meta.profile` metadata element. But instances may also unintentionally conform to _many_ profiles -- this is actually beneficial to interoperability as in some cases, a FHIR server's default response may already conform to a given profile if that profile is relatively unconstrained. -**A note on FHIR jargon.** The FHIR spec defines a number of [resources](https://www.hl7.org/fhir/resourcelist.html), which are information models that are the building blocks of FHIR implementations. FHIR servers create an *instance* of a given resource (i.e., an instance of the Patient resource representing a specific patient). It is this _instance_ that may conform to a given FHIR profile, not the resource itself. But in casual conversation, you may hear that "resource X conforms to profile Y" -- this really means "*resource instance* X conforms to profile Y", but saying "resource instance" is cumbersome.

    You may also here "resource" used to refer to the FHIR specification's definition of a resource: e.g., "`name` is an element of the Patient resource" refers to the `name` element in [the FHIR spec's definition of the Patient resource](https://www.hl7.org/fhir/patient.html). +**A note on FHIR jargon.** The FHIR spec defines a number of [resources](https://www.hl7.org/fhir/resourcelist.html), which are information models that are the building blocks of FHIR implementations. FHIR servers create an *instance* of a given resource (i.e., an instance of the Patient resource representing a specific patient). It is this _instance_ that may conform to a given FHIR profile, not the resource itself. But in casual conversation, you may hear that "resource X conforms to profile Y" -- this really means "*resource instance* X conforms to profile Y", but saying "resource instance" is cumbersome.

    You may also hear "resource" used to refer to the FHIR specification's definition of a resource: e.g., "`name` is an element of the Patient resource" refers to the `name` element in [the FHIR spec's definition of the Patient resource](https://www.hl7.org/fhir/patient.html). {: .alert.alert-info } -Each profile has its own page in an IG build, and this is where you can find the conformance rules specified by that profile. [Here's an example of a profile page in an IG](https://hl7.org/fhir/us/mcode/StructureDefinition-mcode-cancer-patient.html). The next part of the course will talk about how these pages are generated. +Each profile has its own page in an IG build, and this is where you can find the conformance rules specified by that profile. [Here's an example of a profile page in an IG](https://hl7.org/fhir/us/mcode/STU2/StructureDefinition-mcode-cancer-patient.html). The next part of the course will talk about how these pages are generated. ---- @@ -216,13 +216,13 @@ Below is an annotated screenshot showing some of the key components of profiles 1. **Snapshot Table** shows _all_ the rules contained in the profile, including rules inherited from its parents. 1. **Snapshot Table (Must Support)** is the subset of the elements on the previous tab with a `MustSupport` flag. This is described later. -Typically the **differential** ("diff") table tab is the best place to start when trying to understand what a rules a profile is setting. Here's the diff table from [the example of profile](https://hl7.org/fhir/us/mcode/StructureDefinition-mcode-cancer-patient.html#tabs-diff) linked above: +Typically the **differential** ("diff") table tab is the best place to start when trying to understand what rules a profile is setting. Here's the diff table from [the example of a profile](https://hl7.org/fhir/us/mcode/STU2/StructureDefinition-mcode-cancer-patient.html#tabs-diff) linked above: ![Screenshot of diff table from the example profile](profile_diff.png){: .img-responsive } This shows that this profile adds two constrains: the addition of `MustSupport` flags for the root `Patient` element (indicating that the entire profile is `MustSupport` to implementers ), and `Patient.deceased[x]`. The meaning of `MustSupport` and the full set of possible element-level constraints are discussed in the [next part of the course](02-creating-an-ig.html). -The **snapshot** table tab is typically the best way to see all elements that may/should/must be populated for an instance of a resource to conform. This table is too long in the example profile to reproduce as a screenshot, but you can [see it here](https://hl7.org/fhir/us/mcode/StructureDefinition-mcode-cancer-patient.html#tabs-snap). +The **snapshot** table tab is typically the best way to see all elements that may/should/must be populated for an instance of a resource to conform. This table is too long in the example profile to reproduce as a screenshot, but you can [see it here](https://hl7.org/fhir/us/mcode/STU2/StructureDefinition-mcode-cancer-patient.html#tabs-snap). The table tabs have a high amount of information density: @@ -257,7 +257,7 @@ To see a practical application of the concepts discussed above, we will review p mCODE's home page also links to some other key concepts and resources specific to this IG, including the Data Dictionary, development history, credits, and author contact information. -- **"Content by Group" pages**: [Section 1.2 of the home page](https://hl7.org/fhir/us/mcode/STU2/index.html#overview) links to the different groups of profiles and other artifacts in the IG. Not all IGs have this structure (and many IGs don't have as many artifacts as the mCODE IG, making this kind of structure is unnecessary). +- **"Content by Group" pages**: [Section 1.2 of the home page](https://hl7.org/fhir/us/mcode/STU2/index.html#overview) links to the different groups of profiles and other artifacts in the IG. Not all IGs have this structure (and many IGs don't have as many artifacts as the mCODE IG, making this kind of structure unnecessary). Following the pattern described above of reading prominently linked narrative content before diving into the individual IG artifacts, consider reviewing these pages next after finishing the content on the home page. @@ -265,16 +265,16 @@ To see a practical application of the concepts discussed above, we will review p - **Conformance pages**: These appear third in the navigation bar, and are custom-written narrative pages specifically for the mCODE IG, broken into four sections by topic. - Reviewing the details of these is beyond the scope of this course, and not all IGs include this much information on conformance. However, one common item that you should be looking for is how the IG [defines MustSupport](https://hl7.org/fhir/us/mcode/stu2/conformance-profiles.html#must-implement-versus-must-support), as this is a key conformance concept and is [not defined in the base FHIR specification, but is instead left to profile authors to define](https://www.hl7.org/fhir/profiling.html#mustsupport) + Reviewing the details of these is beyond the scope of this course, and not all IGs include this much information on conformance. However, one common item that you should be looking for is how the IG [defines MustSupport](https://hl7.org/fhir/us/mcode/stu2/conformance-profiles.html#must-implement-versus-must-support), as this is a key conformance concept and is [not defined in the base FHIR specification, but is instead left to profile authors to define](https://www.hl7.org/fhir/profiling.html#obligations) - **FHIR Artifacts**: The fourth item in the navigation bar lists the various types of FHIR artifacts. These are custom pages made specifically for mCODE (except for "Complete Listing"; this is described below). Note that you likely have come across all the key artifacts as these are _also_ listed at the bottom of each "Content by Group" page. - **Standard navigation pages** - Every IG has an `artifacts.html` page, so if you find the IG's approach to organizing artifacts in the narrative confusing, you can always open that page to see a comprehensive list of all artifacts. [Here's that page for mCODE (found at `FHIR Artifacts > Complete Listing` in the nav bar)](https://hl7.org/fhir/us/mcode/STU2/artifacts.html). + Every IG has an `artifacts.html` page, so if you find the IG's approach to organizing artifacts in the narrative confusing, you can always open that page to see a comprehensive list of all artifacts. Here's the [artifacts.html page for mCODE](https://hl7.org/fhir/us/mcode/STU2/artifacts.html) (found at `FHIR Artifacts > Complete Listing` in the nav bar). - IGs also have a table of contents page (`toc.html`) that you can use to see a full list of all the web pages in the IG. [Here's that page for mCODE](https://hl7.org/fhir/us/mcode/STU2/toc.html). + IGs also have a table of contents page (`toc.html`) that you can use to see a full list of all the web pages in the IG. Here's the [table of contents page for mCODE](https://hl7.org/fhir/us/mcode/STU2/toc.html). Now that we (hopefully) understand the overall purpose of the IG and the general conformance criteria, let's look in detail at one of the key profiles in the IG: [Primary Cancer Condition](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-primary-cancer-condition.html). @@ -289,7 +289,7 @@ Now that we (hopefully) understand the overall purpose of the IG and the general 6. A required binding of `Condition.stage.type` to [Staging Type for Stage Group Value Set](https://hl7.org/fhir/us/mcode/stu2/ValueSet-mcode-observation-codes-stage-group-vs.html). - The [Snapshot Table](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-primary-cancer-condition.html#tabs-snap) lists all the elements that may appear in a conforming instance of Condition. -This information tells me as an implementer what sort of data and terminology I'll need to have available to create conforming instances of Condition. +This information tells implementers what sort of data and terminology they'll need to have available to create conforming instances of Condition. This is the first pass of the process needed to understand each profile in the IG. Depending on the use case, other resources may also need to be reviewed in detail. From 5349e5cedc9ace7785f6a06ae6190dbc015aecab Mon Sep 17 00:00:00 2001 From: Chris Moesel Date: Fri, 27 Mar 2026 12:28:11 -0400 Subject: [PATCH 05/10] Update cache action in GitHub Action --- .github/workflows/publish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 398c025..80080da 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -26,7 +26,7 @@ jobs: - name: Cache contents of ~/.fhir id: fhir-cache - uses: actions/cache@v3 + uses: actions/cache@v5 with: path: ~/.fhir key: ${{ runner.os }}-fhir From 44e8f13a12bf949556065fe6c5596a4ea80a4826 Mon Sep 17 00:00:00 2001 From: Chris Moesel Date: Mon, 30 Mar 2026 17:02:35 -0400 Subject: [PATCH 06/10] Updates to Creating an IG - Link to mCODE STU2 for mCODE example - Link to US Core STU 6 for US Core examples - Link to core extensions from Extensions pack - Add information about Mermaid diagrams - Add links to IG Guidance on adding Mermaid/PlantUML diagrams - Replace references to _updatePublisher / _genonce with _build - Add note about canonical vs documentation URLs - Use sushi init instead of sushi --init - Point to new FSH Plugin (now owned by HL7) - Grammar and spelling NOTE DONE: I did not update mCODE discussions to STU4 or update screenshots / videos, but we should probably do this. --- .../input/pagecontent/02-creating-an-ig.md | 110 +++++++++--------- 1 file changed, 58 insertions(+), 52 deletions(-) diff --git a/fsh-seminar/input/pagecontent/02-creating-an-ig.md b/fsh-seminar/input/pagecontent/02-creating-an-ig.md index 0c600f2..807d50f 100644 --- a/fsh-seminar/input/pagecontent/02-creating-an-ig.md +++ b/fsh-seminar/input/pagecontent/02-creating-an-ig.md @@ -4,7 +4,7 @@ The goal of this part of the course is to describe the thought process and mecha A FHIR IG is fundamentally an agreement among implementers on an approach to solve a specific problem. The effectiveness of this agreement depends on multiple factors including: -- The clarity of the definition of the problem the IG attempts to solves, and the specific use cases it addresses +- The clarity of the definition of the problem the IG attempts to solve, and the specific use cases it addresses - Appropriate selection, description, and involvement of the participants/stakeholders involved in the problem - Delineation of the necessary data elements and workflow to support the use cases - Suitable selection of terminology @@ -20,7 +20,7 @@ The **implementation guide** portion[^implementation-guide] is generated by the [^implementation-guide]: The "implementation guide" section of this diagram is somewhat simplified for the sake of clarity: for example, workflows are represented by [SearchParameter](https://www.hl7.org/fhir/R4/searchparameter.html) resources in addition to "FHIR Operations" ([OperationDefinition](https://www.hl7.org/fhir/R4/operationdefinition.html) resources). Likewise, in addition to "FHIR Value Sets" ([ValueSet](https://www.hl7.org/fhir/valueset.html) resources), there are other terminology-related resources like [CodeSystem](https://www.hl7.org/fhir/R4/codesystem.html) and [ConceptMap](https://www.hl7.org/fhir/R4/conceptmap.html). -Once the IG is created, additional **downstream work**, such as the creation of a reference implementation or test data may be support adoption by implementers. +Once the IG is created, additional **downstream work**, such as the creation of a reference implementation or test data may support adoption by implementers. Creating a new IG is an involved process that may take multiple years to complete. This is in part due to the complexity of the ecosystem FHIR inhabits, and the number of different stakeholders often need to be aligned for an IG to be successful. @@ -51,7 +51,7 @@ The typical workflow for working on an IG is: 1. Edit the IG content locally on your computer 1. Run `publisher.jar` to create a local build of the IG you can review -1. Use [git](https://git-scm.com) to push your changes to a collaboration space like GitHub or Gitlab, where a "continuous integration" (CI) service can create a publicly accessible copy of the IG build +1. Use [git](https://git-scm.com) to push your changes to a collaboration space like GitHub, BitBucket, or GitLab, where a "continuous integration" (CI) service can create a publicly accessible copy of the IG build This very website is built using the FHIR IG workflow and tools, including `publisher.jar`. @@ -59,16 +59,16 @@ This very website is built using the FHIR IG workflow and tools, including `publ Under the hood, computable rules in FHIR are defined by a set of [conformance-specific FHIR resources](https://www.hl7.org/fhir/resourcelist.html). The FHIR spec not only defines resources for representing health data (like the [Patient](http://hl7.org/fhir/patient.html) resource from [Part 1](01-reading-an-ig.html)), but also defines resources for many other uses including conformance. -[StructureDefinition](https://www.hl7.org/fhir/structuredefinition.html) is one of FHIR's conformance resources, which is how FHIR profiles are defined. Here's [an example of a `StructureDefinition` from the mCODE IG](http://hl7.org/fhir/us/mcode/2021May/StructureDefinition-mcode-cancer-patient.html): +[StructureDefinition](https://www.hl7.org/fhir/structuredefinition.html) is one of FHIR's conformance resources, which is how FHIR profiles are defined. An [example of a `StructureDefinition` from the mCODE IG](https://hl7.org/fhir/us/mcode/STU2/StructureDefinition-mcode-cancer-patient.html) is abbreviated below: ```json { "resourceType": "StructureDefinition", "id": "mcode-cancer-patient", "url": "http://hl7.org/fhir/us/mcode/StructureDefinition/mcode-cancer-patient", - "version": "1.17.1", + "version": "2.0.0", "name": "CancerPatient", - "title": "Cancer Patient", + "title": "Cancer Patient Profile", "status": "active", "description": "A patient who has...", "fhirVersion": "4.0.1", @@ -102,10 +102,10 @@ Here's the same `StructureDefinition` resource from above, but this time written Profile: CancerPatient Parent: USCorePatient Id: mcode-cancer-patient -Title: "Cancer Patient" +Title: "Cancer Patient Profile" Description: "A patient who has..." -* deceased[x] MS * . MS +* deceased[x] MS ``` An application called [SUSHI](https://fshschool.org/docs/sushi/) takes care of compiling FSH into FHIR resources represented in JSON. This is baked into the IG publisher workflow -- the workflow diagramed above really looks more like this: @@ -121,11 +121,15 @@ By default, SUSHI generates a placeholder `input/pagecontent/index.md` file that #### Recommended tools for IG authoring -The [prerequisites](index.html#prerequisites) for this course include installing [Visual Studio Code (VSCode)](https://code.visualstudio.com) and the [FSH language extension](https://marketplace.visualstudio.com/items?itemName=MITRE-Health.vscode-language-fsh). While you can use any text editor to edit FSH (`.fsh`) files, currently only VSCode has syntax highlighting and other language-specific features via the custom language extension. +The [prerequisites](index.html#prerequisites) for this course include installing [Visual Studio Code (VSCode)](https://code.visualstudio.com) and the [FSH language extension](https://marketplace.visualstudio.com/items?itemName=FHIR-Shorthand.vscode-fsh). While you can use any text editor to edit FSH (`.fsh`) files, currently only VSCode has syntax highlighting and other language-specific features via the custom language extension. VSCode also [supports editing Markdown out of the box](https://code.visualstudio.com/docs/languages/markdown) (Markdown is used very widely outside of the FHIR/HL7 world), and if you follow that link you will see some additional Markdown extensions that are available if you want additional functionality (like "linting", which will warn you of syntax errors as you type). One of the most useful VSCode features is [built-in Markdown previewing](https://code.visualstudio.com/docs/languages/markdown#_markdown-preview). -IGs also often include diagrams. There is native support in the IG Publisher for [PlantUML](https://plantuml.com), which is used to make the diagrams on this page. However, PlantUML has a much steeper learning curve than other diagramming tools ([this is a good PlantUML resource](https://crashedmind.github.io/PlantUMLHitchhikersGuide/layout/layout.html) if you are interested). You may find it easier to embed images exported from other tools like Microsoft Visio or [diagrams.net](https://www.diagrams.net), which can be done by placing them within the `input/images/` folder and then using Markdown syntax for images. For example, `input/images/something.png` could be embedded in a Markdown page with `![](something.png)`. (Note that the path is different between the input location and the Markdown syntax -- this is because `publisher.jar` moves the images as part of the build process. This means a Markdown preview of a `pagecontent/` file in a FHIR IG won't properly display images.) +IGs also often include diagrams. The IG Publisher supports diagrams using Mermaid, PlantUML, and image files. + +* [Mermaid](https://mermaid.ai) allows authors to quickly create a variety of diagrams using a simple text format. Learn more by experimenting in the [Mermaid Playground](https://mermaid.ai/play#pako:eNqrVkrOT0lVslJSqgUAFW4DVg) and then learn about [adding Mermaid diagrams to your IG](https://build.fhir.org/ig/FHIR/ig-guidance/diagrams-mermaid.html). +* [PlantUML](https://plantuml.com), which is used to make the diagrams on this page, has a steeper learning curve than Mermaid but also provides more control over the diagrams. To learn more about PlantUML, check out [The Hitchhiker's Guide to PlantUML](https://crashedmind.github.io/PlantUMLHitchhikersGuide/index.html) and the documentation for [adding PlantUML diagrams to your IG](https://build.fhir.org/ig/FHIR/ig-guidance/diagrams-plantuml.html). +* If you prefer using other tools, like Microsoft Visio or [diagrams.net](https://www.diagrams.net), you can place exported image files into your IG's `input/images/` folder and then refer to them using Markdown syntax for images. For example, `input/images/something.png` could be embedded in a Markdown page with `![](something.png)`. (Note that the path is different between the input location and the Markdown syntax -- this is because `publisher.jar` moves the images as part of the build process. This means a Markdown preview of a `pagecontent/` file in a FHIR IG won't properly display images.) #### Starting a new IG @@ -138,10 +142,8 @@ After you run this command, you will have a new folder with a structure of subfo ```text 📂 SomeIgNameHere ├─ .gitignore - ├─ _genonce.bat - ├─ _genonce.sh - ├─ _updatePublisher.bat - ├─ _updatePublisher.sh + ├─ _build.bat + ├─ _build.sh ├─ ig.ini ├─📂 input │ ├─📂 fsh @@ -162,9 +164,7 @@ git add -A git commit -m "Initial commit" ``` -You can see the contents of the IG at this point [here](#TBD). - -We will be "forking" this repository to use as an example in the rest of this part of the course, and to use as the basis for the exercise in [Part 3](03-exercise.html). +We will use this initialized repository as an example in the rest of this part of the course and as the basis for the exercise in [Part 3](03-exercise.html).

    How do you create an IG?

    @@ -178,7 +178,7 @@ We will use the process from the workflow diagram at the top of this page, repro **Hypothetical problem:** -> The Obstructive Sleep Apnea Association (OSAA - a fictitious clinical organization based in the U.S.) is looking to evaluate the impact of obesity as a risk > for Obstructive Sleep Apnea (OSA). OSAA needs a way to ensure the relevant clinical data are collected in a standard, interoperable format from participating member sites. +> The Obstructive Sleep Apnea Association (OSAA - a fictitious clinical organization based in the U.S.) is looking to evaluate the impact of obesity as a risk for Obstructive Sleep Apnea (OSA). OSAA needs a way to ensure the relevant clinical data are collected in a standard, interoperable format from participating member sites. **Participants:** @@ -268,11 +268,11 @@ High-level information models like this (i.e., not FHIR-specific) are helpful fo ##### Mapping high-level information model to FHIR resources -We will need to pick a version of FHIR to base the IG off of. As of May 2022 [FHIR 4.0.1](http://hl7.org/fhir/R4/) is the stable release, which is usually the correct choice. However, you can [see all release here](http://hl7.org/fhir/directory.html), and if an upcoming release is close to being ready you may want to use that instead. Currently both R4B and R5 are in progress. +We will need to pick a version of FHIR to base the IG off of. As of March 2026, [FHIR 4.0.1 (R4)](http://hl7.org/fhir/R4/) is usually the best choice, as it enjoys the highest adoption rates despite the availability of newer releases. If you're interested in targeting a different release, however, you can [see all FHIR releases here](http://hl7.org/fhir/directory.html), including ballot releases of the upcoming FHIR R6. -IG authors should take care to align with existing specifications in the relevant jurisdiction. In our case, we will align with [FHIR U.S. Core 3.2](http://hl7.org/fhir/us/core/2021Jan/) profiles where possible.[^USCore] +IG authors should take care to align with existing specifications in the relevant jurisdiction. In our case, we will align with [FHIR US Core 6.1 (R6)](https://hl7.org/fhir/us/core/STU6.1/) profiles where possible.[^USCore] -[^USCore]: Note that [US Core 4.0.0](http://hl7.org/fhir/us/core/STU4/) has subsequently been released. +[^USCore]: Note that [US Core R7](https://hl7.org/fhir/us/core/STU7/) and [US Core R8](https://hl7.org/fhir/us/core/STU8.0.1/) have subsequently been released, but US Core R6 is currently specified in U.S. regulations. The [IG creation stream on chat.fhir.org](https://chat.fhir.org/#narrow/stream/179252-IG-creation) is a good place to ask for advice on alignment with existing specifications for a given use case. @@ -283,7 +283,7 @@ We will now create a **Resources Model**, which [David Hay](https://fhirblog.com Determining which FHIR resources are the best fit for mapping with the information model may be quite challenging due to the number of FHIR resources and conventions about which resources to use when. Some good places to start when trying to figure this out: - Look at the [FHIR resource list](https://www.hl7.org/fhir/resourcelist.html) and read the "Scope and Usage" section on each resource that seems potentially applicable. -- Look at existing established IGs. For example, [US Core](http://hl7.org/fhir/us/core/2021Jan/) has a [number of profiles](http://hl7.org/fhir/us/core/2021Jan/profiles-and-extensions.html), so looking through these to see if any elements of your information model map cleanly onto one may be helpful. +- Look at existing established IGs. For example, [US Core](https://hl7.org/fhir/us/core/STU6.1) has a [number of profiles](https://hl7.org/fhir/us/core/STU6.1/profiles-and-extensions.html), so it might be helpful to look through these to see if any elements of your information model map cleanly onto one. - Ask for help on [chat.fhir.org](https://chat.fhir.org/#narrow/stream/179252-IG-creation). A structural mapping of our information elements to FHIR resource elements is shown in the table below. In this table, each row represents a data element, which are grouped into profiles of FHIR resources based on the "Profile Name" column. You can see which FHIR resource is being used for a given data element by looking at the first part of the "FHIR element name / Path" column (i.e., the patient's name is represented by `Patient.name`, indicating that the [Patient](https://www.hl7.org/fhir/R4/patient.html) resource is used). @@ -304,15 +304,15 @@ A structural mapping of our information elements to FHIR resource elements is sh | `OSABodyMassIndex` | `Observation.valueQuantity` | BMI measurement | | {: .grid } -[patient-birthPlace]: http://hl7.org/fhir/extension-patient-birthplace.html -[bmi]: http://hl7.org/fhir/us/core/2021Jan/StructureDefinition-us-core-bmi.html +[patient-birthPlace]: https://hl7.org/fhir/extensions/StructureDefinition-patient-birthPlace.html +[bmi]: https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-bmi.html [^pt3]: Note that the mapping to FHIR elements for `OSAPractitioner` and `OSACondition` will be defined in [Part 3 (hands-on exercise)][Part 3]. When creating structural mappings to FHIR data elements, consider the following: - Does an appropriate element exist in the FHIR resource? -- Is there a [FHIR standard extension](http://hl7.org/fhir/extensibility-registry.html) that can be used? +- Is there a [FHIR standard extension](https://hl7.org/fhir/extensions/extension-registry.html) that can be used? - Could this be addressed through a FHIR query or operation instead of using an extension? - Could the data element be derived by the receiving application, rather than generating it in the sending application? @@ -322,17 +322,17 @@ At this point you should have already identified target terminology, and now nee The two most common terminology-related conformance resources are: -1. [CodeSystem](https://www.hl7.org/fhir/codesystem.html) -- "declares the existence of and describes a code system or code system supplement and its key properties, and optionally defines a part or all of its content. Also known as Ontology, Terminology, or Enumeration" -2. [ValueSet](https://www.hl7.org/fhir/R4/valueset.html) -- "specifies a set of codes drawn from one or more code systems, intended for use in a particular context. Value sets link between CodeSystem definitions and their use in coded elements" +1. [CodeSystem](https://www.hl7.org/fhir/codesystem.html) -- "declares the existence of and describes a code system or code system supplement and its key properties, and optionally defines a part or all of its content." Also known as Ontology, Terminology, or Enumeration" +2. [ValueSet](https://www.hl7.org/fhir/valueset.html) -- "specifies a set of codes drawn from one or more code systems, intended for use in a particular context. Value sets link between CodeSystem definitions and their use in coded elements" You should **avoid creating a new CodeSystem if possible**. Instead, use one of the existing HL7 or external code systems [defined here](https://terminology.hl7.org/). More information on code systems may also be found at the [HL7 Health Terminology Authority (HTA) Confluence site](https://confluence.hl7.org/display/TA/External+Terminologies+-+Information). Creating a new CodeSystem will likely increase implementer burden and harms interoperability across Implementation Guides. CodeSystems in FHIR are identified by a canonical URL or [OID](https://en.wikipedia.org/wiki/Object_identifier). You will need to identify this to reference an existing CodeSystem in a ValueSet. -The ValueSet (not the CodeSystem) is [bound](https://www.hl7.org/fhir/R4/profiling.html#binding) to a FHIR element. When considering ValueSet bindings, keep the following in mind: +The ValueSet (not the CodeSystem) is [bound](https://www.hl7.org/fhir/profiling.html#binding) to a FHIR element. When considering ValueSet bindings, keep the following in mind: - Is there an existing value set that can be used (e.g., from [VSAC](https://vsac.nlm.nih.gov/))? If not, should you create a new ValueSet resource in your IG, or create it externally to your IG? (The [Terminology stream on chat.fhir.org](https://chat.fhir.org/#narrow/stream/179202-terminology) may be a good place to ask questions about the specifics of your use case.) -- Are there value set constraints assigned to the FHIR resource element already? If so, what is the [binding strength](https://www.hl7.org/fhir/R4/profiling.html#binding) (example, preferred, extensible, required)? +- Are there value set constraints assigned to the FHIR resource element already? If so, what is the [binding strength](https://www.hl7.org/fhir/profiling.html#binding) (example, preferred, extensible, required)? - What is the best binding strength for your use case? (Note that profiles can only _increase_ the strength of a binding, not decrease it.) #### Step 5: Construct the Implementation Guide @@ -354,7 +354,9 @@ If you have a simple IG, it's reasonable to have a single `.fsh` file for each s The mCODE IG approaches this problem in a fairly structured way, using 2-3 letter prefixes for its `.fsh` files to group them by resource type (e.g., `SD` for StructureDefinition, indicating a FSH file that defines profiles) and subject (whatever comes after the prefix). You can [see this in action here](https://github.com/HL7/fhir-mCODE-ig/tree/master/input/fsh). This is a reasonable approach assuming you don't find the prefixes too cryptic: - Profiles - `SD_.fsh` (SD = StructureDefintion) +- Extensions - `SD_Extensions.fsh` - Value sets - `VS_.fsh` +- Concept maps - `CM_.fsh` - Aliases to code systems and external profiles - `AL_.fsh` - Examples - `EX_.fsh` - Other definitions (e.g., FHIR CapabilityStatements, FSH RuleSets) - `DEF_.fsh` @@ -364,10 +366,8 @@ We will take a simpler approach in the example IG for this seminar: ```text 📂 fsh-seminar-exercise ├─ .gitignore - ├─ _genonce.bat - ├─ _genonce.sh - ├─ _updatePublisher.bat - ├─ _updatePublisher.sh + ├─ _build.bat + ├─ _build_.sh ├─ ig.ini ├─📂 input │ ├─📂 fsh @@ -383,7 +383,7 @@ We will take a simpler approach in the example IG for this seminar: └─ sushi-config.yaml ``` -Recall that the FHIR IG Publisher and FHIR Shorthand compiler (SUSHI) define the folder structure above, and that SUSHI will actually generate this for you when you initialize a new project with `sushi -- init`. +Recall that the FHIR IG Publisher and FHIR Shorthand compiler (SUSHI) define the folder structure above, and that SUSHI will actually generate this for you when you initialize a new project with `sushi init`. For the purposes of this course, you can either run `sushi init` yourself to get this folder structure and add in the IG content by following the directions below, or get a pre-created copy of the folder structure and files above that includes everything discussed in Part 2 [from GitHub](https://github.com/FSHSchool/courses-fsh-seminar-exercise). This will also form the basis of the exercise in [Part 3]. @@ -391,19 +391,22 @@ We will now go through the content needed to construct the IG for our example us ##### SUSHI configuration -We know that the IG needs to use FHIR 4.0.1, and depends on US Core 3.2. This configuration is done in `sushi-config.yaml`: +We know that the IG needs to use FHIR 4.0.1, and depends on US Core 6.1. This configuration is done in `sushi-config.yaml`. First note the declaration of the `fhirVersion`, which should have already been set by `sushi init`: + +```yaml +fhirVersion: 4.0.1 +``` + +Then find the `dependencies` declaration (which will likely be commented out using `#`). Uncomment the `dependencies` declaration and add the US Core 6.1.0 dependency indented below it: ```yaml -... -fhirVersion: 4.0.1 # Should already be set by SUSHI -- just check to make sure it's the correct version dependencies: - hl7.fhir.us.core: 3.2.0 -... + hl7.fhir.us.core: 6.1.0 ``` The rest of this file should be auto-generated by SUSHI and won't need modification, other than to add in additional narrative pages and navigation bar items. -Now is a good time to try building the IG. To do this, go to the IG's folder in your command prompt and run `_genonce` (`./_genonce.sh` for Mac/Linux, `_genonce` for Windows). If the IG builds successfully, you should be able to open `output/index.html` in your web browser see the boilerplate IG home page. +Now is a good time to try building the IG. To do this, go to the IG's folder in your command prompt and use the build script to update your local IG Publisher jar (`./_build.sh update` for Mac/Linux, `_build update` for Windows). Then use the build script to build your project (`./_build.sh build` for Mac/Linux, `_build build` for Windows). If the IG builds successfully, you should be able to open `output/index.html` in your web browser to see the boilerplate IG home page. ##### Aliases @@ -424,6 +427,8 @@ Alias: $USCoreBodyMassIndex = http://hl7.org/fhir/us/core/StructureDefinition/ This will allow us to refer to ICD codes with `ICD10CM#G47.33` when creating our ValueSet, and to US Core profiles with their aliases rather than their much longer canonical URIs. +Note Identifying URLs in FHIR are called _canonical_ (or _official_) URLs. These URLs are often _not_ the same as the URL for viewing that resource's documentation in your browser. For example, the URL to view the US Core 6.1 Patient profile in your browser is [https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-patient.html](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-patient.html), but its canonical URL is `http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient`. Always use the _canonical_ URL in formal FHIR (and FSH) definitions. + ##### ValueSet: Obstructive Sleep Apnea ICD-10-CM codes In `input/fsh/value_set_osa.fsh`, [define a ValueSet](http://hl7.org/fhir/uv/shorthand/reference.html#defining-value-sets) for the ICD codes listed in the use case: @@ -461,9 +466,9 @@ Here's what the human-readable version of the `MyPatient` profile looks like fro
    Differential of minimal patient profile
    -In the example above, a two constraints are added to the `name` element: `1..*` cardinality ("one or more") and a MustSupport (`MS`; will be discussed below). +In the example above, two constraints are added to the `name` element: `1..*` cardinality ("one or more") and a MustSupport (`MS`; will be discussed below). -We will discard this example and create our own profile in `input/fsh/profile_patient.fsh`, [define a profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's Patient profile](http://hl7.org/fhir/us/core/2021Jan/StructureDefinition-us-core-patient.html): +We will discard this example and [define a new profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's Patient profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-patient.html) in `input/fsh/profile_patient.fsh`: ``` Profile: OSAPatient @@ -477,7 +482,7 @@ Description: "An example Patient profile" This FSH does the following: 1. `* birthDate 1..1` makes this element required (it inherits a MustSupport flag from `USCorePatient`). -1. The `patient-birthPlace` extension is added as optional (`0..1` cardinality) and MustSupport. We are using an extension because birth place is not supported by a standard element in the base Patient resource. The [birthPlace extension](https://www.hl7.org/fhir/R4/extension-patient-birthplace.html) is actually part of FHIR R4, so it's better from an interoperability perspective to use this extension vs. defining our own custom extension. +1. The `patient-birthPlace` extension is added as optional (`0..1` cardinality) and MustSupport. We are using an extension because birth place is not supported by a standard element in the base Patient resource. The [birthPlace extension](https://hl7.org/fhir/extensions/StructureDefinition-patient-birthPlace.html) is actually part of FHIR core, so it's better from an interoperability perspective to use this extension vs. defining our own custom extension. 1. The `generalPractitioner` reference is restricted to only reference [Practitioner](https://www.hl7.org/fhir/R4/practitioner.html) instances that conform to the `OSAPractitioner` profile (to be defined below). This makes it clear to implementers how the `OSAPatient` and `OSAPractitioner` profiles are related. Name, age (i.e., `birthDate`), and birth place are all required based on the use case. It's reasonable to assume that name and age are known, so these elements are marked as required (minimum cardinality `1`; note that `name` inherits this from `USCorePatient`). @@ -486,20 +491,20 @@ We do not set the `patient-birthPlace` extension to be required (minimum cardina The required elements (`name`, `birthDate`) are also marked as MustSupport. This is redundant for the system producing the FHIR resource instances as the cardinality constraint ensures they are populated even without the MustSupport flag. However, for the receiving system, the MustSupport flag still has meaning -- it typically would indicate that the receiving system would need to "meaningfully process" the MustSupport elements; without the MustSupport flag, the receiving system could discard these elements. The narrative of the IG should provide a definition of MustSupport to clarify its meaning to all participants (in our case OSAA as the receiver of FHIR resource instances, and the participating study sites as the producers of these instances). -At this point it's a good idea to run `_genonce` again to see the changes you've made to the IG. If you see an error related to `OSAPractitioner`, that is because you haven't defined this profile yet (see below) but you have referenced it. You can comment out the relevant line (`// * generalPractitioner only Reference(OSAPractitioner)` in `OSAPatient` to temporarily avoid this error. +At this point it's a good idea to run `_build` again to see the changes you've made to the IG. If you see an error related to `OSAPractitioner`, that is because you haven't defined this profile yet (see below) but you have referenced it. You can comment out the relevant line (`// * generalPractitioner only Reference(OSAPractitioner)` in `OSAPatient` to temporarily avoid this error. -If you do have `OSAPractitioner` defined so `_genonce` can run to completion, you should see something like this for the differential of `OSAPatient`: +If you do have `OSAPractitioner` defined so `_build` can run to completion, you should see something like this for the differential of `OSAPatient`:
    Differential of OSAPatient
    -If you made a mistake with your FSH syntax, you will see an error from SUSHI at the beginning of the `_genonce` process. It may be easier to debug this error by running SUSHI directly with `sushi`. The SUSHI command also runs a lot faster than the entire `_genonce` command, so you may find it useful to run `sushi` while writing FSH to check for syntax errors or other warnings. +If you made a mistake with your FSH syntax, you will see an error from SUSHI at the beginning of the `_build` process. It may be easier to debug this error by running SUSHI directly with `sushi build`. The SUSHI command also runs a lot faster than the entire `_build` command, so you may find it useful to run `sushi build` while writing FSH to check for syntax errors or other warnings. ##### Profile: Practitioner This is part of the [Part 3] exercise, so the solution is hidden ().
    -In `input/fsh/profile_practitioner.fsh`, [define a profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's Practitioner profile](http://hl7.org/fhir/us/core/2021Jan/StructureDefinition-us-core-practitioner.html): +In `input/fsh/profile_practitioner.fsh`, [define a profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's Practitioner profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitioner.html): ``` Profile: OSAPractitioner @@ -518,7 +523,7 @@ Note that you will need to add the `$USCorePractitioner` alias to `aliases.fsh`. This is part of the [Part 3] exercise, so the solution is hidden ().
    -In `input/fsh/profile_clinical.fsh`, [define a profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's Condition profile](http://hl7.org/fhir/us/core/2021Jan/StructureDefinition-us-core-condition.html): +In `input/fsh/profile_clinical.fsh`, [define a profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's Condition profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition.html): ``` Profile: OSACondition @@ -541,13 +546,14 @@ You should now be familiar with most of the contents of this profile, with a few - The `Description` declaration includes Markdown syntax, which will be converted to HTML by the IG publisher pipeline. - The `onset[x] ^short` rule provides a short narrative description of the element. This will be covered more in [Part 4]. +- The `Extension` declaration is used to start an extension definition (which generally follows the same approach as profile definitions). Note that you will need to add the `$USCoreCondition` alias to `aliases.fsh`.
    ##### Profile: Observation -In `input/fsh/profile_clinical.fsh`, [define a profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's BMI profile](http://hl7.org/fhir/us/core/2021Jan/StructureDefinition-us-core-bmi.html): +In `input/fsh/profile_clinical.fsh`, [define a profile](http://hl7.org/fhir/uv/shorthand/reference.html#defining-profiles) based on [US Core's BMI profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-bmi.html): ``` Profile: OSABodyMassIndex @@ -561,9 +567,9 @@ Description: "Body mass index, or BMI, is a measure of body size. It combines a ##### Creating examples -When creating examples, note that if you are basing your profile on another profile rather than the base FHIR resource, there could be additional required elements and constraints that are inherited from those parent profiles. For example, the [US Core Condition Profile](http://hl7.org/fhir/us/core/2021Jan/StructureDefinition-us-core-Condition.html) requires [Condition.category](http://hl7.org/fhir/us/core/2021Jan/StructureDefinition-us-core-Condition.html). +When creating examples, note that if you are basing your profile on another profile rather than the base FHIR resource, there could be additional required elements and constraints that are inherited from those parent profiles. For example, the [US Core Condition Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-Condition.html) requires [Condition.category](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-Condition.html). -Examples also go in `input/fsh/` just like profile definitions. You can actually put them in the same file as a profile definition, which can get messy for a large IG but is fine for this example. +Examples also go in `input/fsh/` just like profile definitions. You can actually put them in the same file as a profile definition, but this can get messy in large IGs. Create a new file called `input/fsh/examples.fsh` and append the following FSH: @@ -582,7 +588,7 @@ Description: "Example OSA Patient." * extension[birthPlace].valueAddress.state = "MA" ``` -Run `_genonce` again and you should then see an "Examples" tab appearing on the page for your `OSAPatient` profile. You should also be able to open `output/Patient-osa-patient-jane-doe.html` by following the links in the built IG. +Run `_build` again and you should then see an "Examples" tab appearing on the page for your `OSAPatient` profile. You should also be able to open `output/Patient-osa-patient-jane-doe.html` by following the links in the built IG. The human-readable "Narrative Content" view of examples in the IG publisher is often missing a lot of data. Use the JSON view as an alternative to see all the data: From 070ffbeb29dbbe9de292e25f0e1c24973b77c562 Mon Sep 17 00:00:00 2001 From: Chris Moesel Date: Fri, 3 Apr 2026 12:02:46 -0400 Subject: [PATCH 07/10] Updates to Hands-On Exercise - Reference and link to US Core STU 6 - Fix broken link in premise - Use `_build` instead of `_genonce` - Note that FSH Online may need US Core dependency set in config - Fix link to VS Code extension - Grammar / typos --- fsh-seminar/input/pagecontent/03-exercise.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/fsh-seminar/input/pagecontent/03-exercise.md b/fsh-seminar/input/pagecontent/03-exercise.md index 0cdb497..542453f 100644 --- a/fsh-seminar/input/pagecontent/03-exercise.md +++ b/fsh-seminar/input/pagecontent/03-exercise.md @@ -4,12 +4,12 @@ The goal of this hands-on exercise is to provide experience working with the con ### Premise -As a FHIR implementation modeler, author a FHIR Implementation Guide (IG) based on [FHIR 4.0.1](http://hl7.org/fhir) for the fictitious use case scenario [described in Part 2](http://localhost:4321/fshschool-ig-authoring/02-creating-an-ig.html#how-do-you-create-an-ig%E2%8F%AF-video-versionto-view-this-v), and reproduced below for convenience: +As a FHIR implementation modeler, author a FHIR Implementation Guide (IG) based on [FHIR 4.0.1](https://hl7.org/fhir/R4/index.html) for the fictitious use case scenario [described in Part 2](02-creating-an-ig.html#how-do-you-create-an-ig), and reproduced below for convenience: