Speaker notes version
Links:
-
-
- FHIR Doc: https://bit.ly/3zHNiusFHIR +
- FHIR Doc: https://bit.ly/3zHNius -
- SearchAPI: https://bit.ly/3zKXaDUFHIR +
- FHIR SearchAPI: https://bit.ly/3zKXaDU -
- Search Parameter Registry: https://bit.ly/3ESpdF5 +
- FHIR Search Parameter Registry: https://bit.ly/3ESpdF5 @@ -2011,11 +2023,11 @@
- FHIR Doc: https://bit.ly/3o3KFHIR +
- FHIR Doc: https://bit.ly/3o3Kdmx -
- OperationsAPI: https://bit.ly/2XRlwPD +
- FHIR OperationsAPI: https://bit.ly/2XRlwPD -
- Operations Registry: https://bit.ly/3ES0hxG +
- FHIR Operations Registry: https://bit.ly/3ES0hxG @@ -2089,8 +2101,9 @@
- Insert it anywhere you want those rules applied, passing in the parameter values to use.
-
-
- Parameters in the rules will be replaces with the specified parameter values as-is. +
- Parameters in the rules will be replaced with the specified parameter values as-is.
- Precede literal
,and)with\to "escape" them, since they are a part of theinsertsyntax.
+ - FSH 3.0 added support for surrounding parameter values in double square brackets
[[]]to avoid the need to escape,and).
- Think of it like an advanced macro.
- GoFSH: https://bit.ly/2YckXjj -
- VS Code Ext: https://bit.ly/3fUsIk7 +
- VS Code Ext: https://bit.ly/4sdab4o
- FSH Online: https://bit.ly/2Y0Ptfu 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/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/images-source/ig_venn.graffle b/fsh-seminar/input/images-source/ig_venn.graffle new file mode 100644 index 0000000..2722735 Binary files /dev/null and b/fsh-seminar/input/images-source/ig_venn.graffle differ diff --git a/fsh-seminar/input/images-source/ig_workflow.graffle b/fsh-seminar/input/images-source/ig_workflow.graffle new file mode 100644 index 0000000..bb88cc3 Binary files /dev/null and b/fsh-seminar/input/images-source/ig_workflow.graffle differ diff --git a/fsh-seminar/input/images-source/pie.graffle b/fsh-seminar/input/images-source/pie.graffle new file mode 100644 index 0000000..af28eb5 Binary files /dev/null and b/fsh-seminar/input/images-source/pie.graffle differ diff --git a/fsh-seminar/input/images-source/profile_anatomy.graffle b/fsh-seminar/input/images-source/profile_anatomy.graffle new file mode 100644 index 0000000..6dcd780 Binary files /dev/null and b/fsh-seminar/input/images-source/profile_anatomy.graffle differ diff --git a/fsh-seminar/input/images-source/profile_snapshot_annotated.graffle b/fsh-seminar/input/images-source/profile_snapshot_annotated.graffle new file mode 100644 index 0000000..1790ef2 Binary files /dev/null and b/fsh-seminar/input/images-source/profile_snapshot_annotated.graffle differ diff --git a/fsh-seminar/input/images/osa_patient.png b/fsh-seminar/input/images/osa_patient.png index 0d9c6a1..fd51bad 100644 Binary files a/fsh-seminar/input/images/osa_patient.png and b/fsh-seminar/input/images/osa_patient.png differ diff --git a/fsh-seminar/input/images/patient_1.png b/fsh-seminar/input/images/patient_1.png index fe33492..fb07e38 100644 Binary files a/fsh-seminar/input/images/patient_1.png and b/fsh-seminar/input/images/patient_1.png differ diff --git a/fsh-seminar/input/images/patient_ex.png b/fsh-seminar/input/images/patient_ex.png index 91bb1d9..34ad80c 100644 Binary files a/fsh-seminar/input/images/patient_ex.png and b/fsh-seminar/input/images/patient_ex.png differ diff --git a/fsh-seminar/input/images/profile_anatomy.png b/fsh-seminar/input/images/profile_anatomy.png index ab41613..845ba8d 100644 Binary files a/fsh-seminar/input/images/profile_anatomy.png and b/fsh-seminar/input/images/profile_anatomy.png differ diff --git a/fsh-seminar/input/images/profile_diff.png b/fsh-seminar/input/images/profile_diff.png index 9f4c7b5..5307321 100644 Binary files a/fsh-seminar/input/images/profile_diff.png and b/fsh-seminar/input/images/profile_diff.png differ diff --git a/fsh-seminar/input/images/profile_snapshot_annotated.png b/fsh-seminar/input/images/profile_snapshot_annotated.png index 28b3798..bbcbf13 100644 Binary files a/fsh-seminar/input/images/profile_snapshot_annotated.png and b/fsh-seminar/input/images/profile_snapshot_annotated.png differ diff --git a/fsh-seminar/input/images/sushi_init.gif b/fsh-seminar/input/images/sushi_init.gif index c13ad65..b80d515 100644 Binary files a/fsh-seminar/input/images/sushi_init.gif and b/fsh-seminar/input/images/sushi_init.gif differ diff --git a/fsh-seminar/input/pagecontent/01-reading-an-ig.md b/fsh-seminar/input/pagecontent/01-reading-an-ig.md index aba634a..3a3fe8a 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.
- Complete the setup instructions -
- 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
- TBD, but likely: slicing, extensions, invariants, CapabilityStatements and SearchParams +
- IG Overview: review purposes and processes for creating FHIR IGs +
- FSH Profiles: cardinality, flags, types, patterns, bindings, extensions, metadata +
- Slicing: defining slicing logic, creating slices, referencing slices +
- FHIRPath: path navigation, common expressions, testing and debugging +
- Invariants: defining and using invariants (a.k.a. constraints) +
- FSH Extensions: simple and complex extensions +
- FSH Terminology: value sets and code systems +
- FSH Instances: example and definition instances, rule sets, search parameters, operations, capability statements +
- Narrative: creating pages in your IG and inserting content into formal definition pages +
- Configuration: sushi-config.yaml and the ImplementationGuide resource +
- GoFSH: converting an existing project to FSH
Speaker notes version
Links:
-
-
Speaker notes version
Speaker notes version
FSH authors can maintain an ImplementationGuide JSON file manually, but most choose to have SUSHI generate it.
NOTE: No matter what version of FHIR your IG supports, IG Publisher uses the latest R5 ImplementationGuide internally. As a result, you may see some values or parameters that are not technically supported in R4.
+NOTE: No matter what version of FHIR your IG supports, IG Publisher uses the latest ImplementationGuide internally. As a result, you may see some values or parameters that are not technically supported in R4.
Links:
@@ -2413,7 +2426,7 @@Speaker notes version
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/STU4/StructureDefinition-mcode-cancer-patient.html). The next part of the course will talk about how these pages are generated. ---- @@ -200,29 +200,34 @@ Below is an annotated screenshot showing some of the key components of profiles 1. The **Content** tab is the entry point to the profile, and contains the majority of the key information you'll need to understand the profile. 2. The **Detailed Descriptions** tab lists all the information for each element in the resource being profiled. -3. The **Examples** tab lists example instances provided by the authors that conform to the profile. -4. The **XML**, **JSON**, and (optionally) **TTL** tabs show the computable version of the profile in the respective format. (TTL stands for [Turtle format](https://www.w3.org/TR/turtle/), which is not widely used.) -5. The **yellow box** at the top of the page indicates which version of the IG you are viewing. This is important so you can tell if you are on the most up-to-date published version of an IG -- sometimes Google searches or other links will land you on an old version. -6. This section contains **profile metadata** including the defining URL, computable `Name`, human-readable `Title`, and the narrative `Definition`. -7. Under the profile metadata is the **narrative** portion of the profile. -8. Finally, the **formal views of profile content** appears at the bottom of the page. This is the human-readable version of the computable version of the profile. We will discuss this in detail below. +3. The **Mappings** tab shows how elements of the profile map to other domain models and patterns. +4. The **Examples** tab lists example instances provided by the authors that conform to the profile. +5. The **XML**, **JSON**, and (optionally) **TTL** tabs show the computable version of the profile in the respective format. (TTL stands for [Turtle format](https://www.w3.org/TR/turtle/), which is not widely used.) +6. The **yellow box** at the top of the page indicates which version of the IG you are viewing. This is important so you can tell if you are on the most up-to-date published version of an IG -- sometimes Google searches or other links will land you on an old version. +7. This section contains **profile metadata** including the human-readable title, official URL, version, status, maturity level, computable name, other identifiers, and the narrative description. +8. Under the profile metadata is the **narrative** portion of the profile. +9. Beneath the narrative is generated information about the profile and its use throughout the IG. +10. Finally, the **formal views of profile content** appears at the bottom of the page. This is the human-readable version of the computable version of the profile. We will discuss this in detail below. ---- -#### Formal View of Profile Content Tabs +#### Formal Views of Profile Content Tabs -1. **Text Summary** provides a brief auto-generated narrative description of the profile. +The formal views of profile content table contains tabs corresponding to the following : + +1. **Key Elements Table** shows the _subset_ of rules that must be considered by anyone implementing the profile. The [model 'views'](https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#model-views) documentation describes the approach for identifying the "key elements" of a profile. 1. **Differential Table** shows _only_ the rules added by this specific profile. In other words, it compares the Profile you are viewing to its parent (either a base FHIR resource or another profile). 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. +1. **Statistics/Reference** provides a summary of generated profile statistics, such as the number of must-support elements. +1. **All** lists the content of the other four views in a single tab. -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/STU4/StructureDefinition-mcode-cancer-patient.html#tabs-diff) linked above: {: .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). +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 ), `Patient.extension:birthsex`, 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/STU4/StructureDefinition-mcode-cancer-patient.html#tabs-snap). The table tabs have a high amount of information density: @@ -245,51 +250,53 @@ There are _many_ more artifacts that can be defined by IGs. These will be enumer
Reviewing an Example IG
-To see a practical application of the concepts discussed above, we will review portions of the [minimal Common Oncology Data Elements (mCODE) Implementation Guide](http://hl7.org/fhir/us/mcode/STU2/) (specifically the STU2 version), which is primarily a Domain of Knowledge IG but also has some Community of Implementation content:[^mcode-versions] +To see a practical application of the concepts discussed above, we will review portions of the [minimal Common Oncology Data Elements (mCODE) Implementation Guide](https://hl7.org/fhir/us/mcode/STU4/) (specifically the STU4 version), which is primarily a Domain of Knowledge IG but also has some Community of Implementation content:[^mcode-versions] [^mcode-versions]: STU refers to Standard for Trial Use, which is a [HL7 ballot level](https://confluence.hl7.org/display/HL7/HL7+Balloting) indicating the maturity of the implementation guide. This is the most recent balloted version of mCODE as of writing. More information about the HL7 ballot process [can be found here](https://confluence.hl7.org/display/HL7/Jira+Ballot+Process). -- **[Home page](http://hl7.org/fhir/us/mcode/STU2/index.html)**: This is the entry point to the IG, and typically describes the background, scope, and general structure of the IG. Ideally the home page of an IG should be the single point of entry for all key content: by following links in the navigation bar or in the narrative of the home page, all the key IG content should be easily accessible. +- **[Home page](https://hl7.org/fhir/us/mcode/STU4/index.html)**: This is the entry point to the IG, and typically describes the background, scope, and general structure of the IG. Ideally the home page of an IG should be the single point of entry for all key content: by following links in the navigation bar or in the narrative of the home page, all the key IG content should be easily accessible. The IG home page should also help guide the reader through the key content within the IG. Some IGs do a better job of this than others, and if the authors' intent is not clear for a given IG you can fall back onto some standard navigation pages (discussed below). - The key information on the mCODE home page is related to the Content by Group pages (see next bullet point), and the diagram showing the structure of mCODE STU2. + The key information on the mCODE home page is related to the Content by Group pages (see next bullet point), and the diagram showing the structure of mCODE STU4. 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/STU4/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. Note that the Content by Group Pages are also linked second in the navigation bar, another indication of their level of importance. -- **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. +- **Conformance pages**: These appear third in the navigation bar, and are custom-written narrative pages specifically for the mCODE IG, broken into five 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/STU4/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). - - 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). - -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). - -- The [**Usage** and **Conformance** sections](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-primary-cancer-condition.html#usage) are additional narrative specific for this profile. -- We see in the Text Summary tab that the profile is based on [USCoreCondition](http://hl7.org/fhir/us/core/STU4/StructureDefinition-us-core-condition.html). -- The [Differential Table](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-primary-cancer-condition.html#tabs-diff) shows the addition of a number of constraints: - 1. MustSupport extensions: `Condition.extension:assertedDate` and `Condition.extension:histologyMorphologyBehavior`. Clicking the names in the diff table brings you to the [detailed definitions](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-primary-cancer-condition-definitions.html#Condition.extension:assertedDate), which provide additional information on these extensions. You may notice these are [slices](https://www.hl7.org/fhir/profiling.html#slicing) of `Condition.extension`, which is a topic we'll cover later in the course. - 2. An extensible value set binding of `Condition.code` to the [Primary Cancer Disorder Value Set](https://hl7.org/fhir/us/mcode/stu2/ValueSet-mcode-primary-cancer-disorder-vs.html). Clicking on [`extensible`](http://hl7.org/fhir/R4/terminologies.html#extensible) in the diff table gives you more information about what this binding strength means. - 3. A required binding of `Condition.bodySite` to [Body Location Qualifier Value Set](https://hl7.org/fhir/us/mcode/stu2/ValueSet-mcode-body-location-qualifier-vs.html), and a MustSupport flag for this element. - 4. Two MustSupport extensions to `Condition.bodySite`: [`Condition.bodySite.extension:locationQualifier`](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-primary-cancer-condition-definitions.html#Condition.bodySite.extension:locationQualifier) and [`Condition.bodySite.extension:lateralityQualifier`](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-primary-cancer-condition-definitions.html#Condition.bodySite.extension:lateralityQualifier). - 5. Constrained `Condition.stage.assessment` to refer to an Observation conforming to [Cancer Stage Group Profile](https://hl7.org/fhir/us/mcode/stu2/StructureDefinition-mcode-cancer-stage-group.html), and added MustSupport flags to this element and its parent. - 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. + 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/STU4/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 the [table of contents page for mCODE](https://hl7.org/fhir/us/mcode/STU4/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/STU4/StructureDefinition-mcode-primary-cancer-condition.html). + +- The [**Usage** and **Conformance** sections](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition.html#usage) are additional narrative specific for this profile. +- We see in the [Statistics/References](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition.html#tabs-summ) tab that the profile is derived from [USCoreConditionProblemsHealthConcernsProfile](http://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-problems-health-concerns.html). +- The [Differential Table](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition.html#tabs-diff) shows the addition of a number of constraints: + 1. MustSupport extension: `Condition.extension:histologyMorphologyBehavior`. Clicking the name in the diff table brings you to the [detailed definition](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition-definitions.html#key_Condition.extension:histologyMorphologyBehavior), which provides additional information on this extension. You may notice that this is a [slice](https://www.hl7.org/fhir/profiling.html#slicing) of `Condition.extension`, which is a topic we'll cover later in the course. + 2. An extensible value set binding of `Condition.code` to the [Primary Cancer Disorder Value Set](https://hl7.org/fhir/us/mcode/STU4/ValueSet-mcode-primary-cancer-disorder-vs.html). Clicking on [`extensible`](http://hl7.org/fhir/R4/terminologies.html#extensible) in the diff table gives you more information about what this binding strength means. + 3. A required binding of `Condition.bodySite` to [Cancer Body Location Value Set](https://hl7.org/fhir/us/mcode/STU4/ValueSet-mcode-cancer-body-location-vs.html), and a MustSupport flag for this element. + 4. Two MustSupport extensions to `Condition.bodySite`: [`Condition.bodySite.extension:locationQualifier`](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition-definitions.html#key_Condition.bodySite.extension:locationQualifier) and [`Condition.bodySite.extension:lateralityQualifier`](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition-definitions.html#key_Condition.bodySite.extension:lateralityQualifier). + 5. New short and detailed descriptions for [Condition.stage.summary](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition-definitions.html#key_Condition.stage.summary) to provide specific guidance regarding cancer staging. + 6. Constrained `Condition.stage.assessment` to refer to an Observation conforming to [Cancer Stage Profile](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-cancer-stage.html), and added MustSupport flags to this element and its parent. + 7. A required binding of `Condition.stage.type` to [Cancer Staging Method Value Set](https://hl7.org/fhir/us/mcode/STU4/ValueSet-mcode-cancer-staging-method-vs.html). + 8. A required binding of `Condition.evidence.code` to [Cancer Disease Status Evidence Type Value Set](https://hl7.org/fhir/us/mcode/STU4/ValueSet-mcode-cancer-disease-status-evidence-type-vs.html). +- The [Snapshot Table](https://hl7.org/fhir/us/mcode/STU4/StructureDefinition-mcode-primary-cancer-condition.html#tabs-snap) lists all the elements that may appear in a conforming instance 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. diff --git a/fsh-seminar/input/pagecontent/02-creating-an-ig.md b/fsh-seminar/input/pagecontent/02-creating-an-ig.md index 0c600f2..a821846 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/STU4/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": "4.0.0", "name": "CancerPatient", - "title": "Cancer Patient", + "title": "Cancer Patient Profile", "status": "active", "description": "A patient who has...", "fhirVersion": "4.0.1", @@ -84,6 +84,12 @@ Under the hood, computable rules in FHIR are defined by a set of [conformance-sp "path": "Patient", "mustSupport": true }, + { + "id": "Patient.extension:birthsex", + "path": "Patient.extension", + "sliceName": "birthsex", + "mustSupport": true + }, { "id": "Patient.deceased[x]", "path": "Patient.deceased[x]", @@ -102,10 +108,11 @@ 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 +* extension[birthsex] 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 +128,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 ``. (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 ``. (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 +149,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 +171,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 +185,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 +275,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 +290,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 +311,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 +329,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 +361,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_
-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 +530,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 (show solution).
-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 +553,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 +574,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 +595,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:
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:
**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:**
@@ -45,7 +45,7 @@ The use case for this work is as follows:
### Tasks
-1. Add remaining FHIR profiles based on the [Resources Model from Part 2](02-creating-an-ig.html#mapping-high-level-information-model-to-fhir-resources), aligning with with [FHIR U.S. Core 3.2](http://hl7.org/fhir/us/core/2021Jan/) profiles where possible:
+1. Add remaining FHIR profiles based on the [Resources Model from Part 2](02-creating-an-ig.html#mapping-high-level-information-model-to-fhir-resources), aligning with with [FHIR US Core 6.1](https://hl7.org/fhir/us/core/STU6.1/) profiles where possible:
1. Practitioner profile (`OSAPractitioner`) ([solution](02-creating-an-ig.html#profile-practitioner))
2. OSA Condition profile (`OSACondition`) ([solution](02-creating-an-ig.html#profile-condition))
2. Create an example of `OSAPractitioner` (solution at bottom of [this section of Part 2](02-creating-an-ig.html#creating-examples))
@@ -53,7 +53,7 @@ The use case for this work is as follows:
> Were there any FHIR limitations in what is needed to create a representative model that addresses this use case? If yes, what were they and what changes or workarounds would you propose?
-4. Successfully build your IG locally with `_genonce` and attempt to resolve any errors on the `output/qa.html` page.
+4. Successfully build your IG locally with `_build` and attempt to resolve any errors on the `output/qa.html` page. _NOTE: You may also see some warning, but just focus on resolving the errors for now._
### Additional notes
@@ -64,11 +64,12 @@ The use case for this work is as follows:
### Helpful tips, tools, and references
-- Check the QA report (`output/qa.html`) as you build the IG with `_genonce` to identify any FHIR validation issues that aren't caught by SUSHI.
-- If you just want to quickly test how to represent and validate a contained construct in FSH without having to run the IG publisher, try it using [FSHOnline](https://fshschool.org/FSHOnline/#/)
+- Check the QA report (`output/qa.html`) as you build the IG with `_build` to identify any FHIR validation issues that aren't caught by SUSHI.
+- If you just want to quickly test how to represent and validate a contained construct in FSH without having to run the IG publisher, try it using [FSHOnline](https://fshschool.org/FSHOnline/#/).
+ - If your FSH references US Core profiles or extensions, you'll need to add `hl7.fhir.us.core#6.1.0` as a dependency in the FSH Online configuration.
- Want to see more FSH examples? Go to [FSHOnline](https://fshschool.org/FSHOnline/#/) and click on the "FSH Examples".
- Want to see how another IG's StructureDefinitions in JSON could be represented in FSH? Also try it using [FSHOnline](https://fshschool.org/FSHOnline/#/). Cut and paste your JSON into the right column and click on _Convert to FSH_ to see the syntax.
-- Try using some of the nice perks in the [vscode-language-fsh](https://marketplace.visualstudio.com/items?itemName=MITRE-Health.vscode-language-fsh) extension to help navigate references between your authored FHIR constructs (profiles, value sets, extensions, etc.)
+- Try using some of the nice perks in the [vscode-fsh](https://marketplace.visualstudio.com/items?itemName=FHIR-Shorthand.vscode-fsh) extension to help navigate references between your authored FHIR constructs (profiles, value sets, extensions, etc.)
- Other neat VSCode extensions to help create a more authoring-friendly VSCode environment:
- [Markdown Preview Github Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) - provides a basic dynamic rendering of your markdown page while you type (but note that embedded images won't be rendered in the preview due to the directory structure).
- [Draw.io integration](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) - integrates Draw.io/diagrams.net into VSCode so that you can create nice diagrams directly inside your IG authoring environment
@@ -94,7 +95,7 @@ In addition to the elements of the solution embedded in Part 2, the full solutio
| `OSAPractitioner` | `Practitioner.identifier.type` | Practitioner NPI | Fix identifier type = NPI |
| `OSACondition` | `Condition.code` | OSA diagnosis code | Fix to `OSADiagnosisVS` containing provided ICD-10-CM codes |
| `OSACondition` | `Condition.extension[AgeAtOSADiagnosis]` | OSA onset date | |
-| `OSACondition` | `Condition.asserter` | managing provider who diagnosed OSA | |
+| `OSACondition` | `Condition.asserter` | Managing provider who diagnosed OSA | |
| `OSABodyMassIndex` | `Observation.code` | Body Mass Index (BMI) | Fix code to `39156-5 "Body mass index (BMI)"` |
| `OSABodyMassIndex` | `Observation.effectiveDateTime` | Body Mass Index (BMI) | |
| `OSABodyMassIndex` | `Observation.valueQuantity` | BMI measurement | BMI Measurement |
diff --git a/fsh-seminar/input/pagecontent/fhir-resources.md b/fsh-seminar/input/pagecontent/fhir-resources.md
index 31822fb..314983c 100644
--- a/fsh-seminar/input/pagecontent/fhir-resources.md
+++ b/fsh-seminar/input/pagecontent/fhir-resources.md
@@ -5,6 +5,7 @@
- [Architecture overview](http://hl7.org/fhir/overview-arch.html)
- [IG best practices](https://build.fhir.org/ig/FHIR/ig-guidance/branches/master/best-practice.html) (note that this has not officially been published yet, but [the authors are some of the FHIR-I leaders](https://github.com/FHIR/ig-guidance/))
- Intro to FHIR videos
- - [45 minutes, from 2023](https://www.youtube.com/watch?v=6PkDXAEmkbE)
- - [90 minutes, from 2020](https://www.youtube.com/watch?v=YbQcJj1GqH0)
-- The FHIR Confluence site, e.g., [Guide to Designing Resources](https://confluence.hl7.org/display/FHIR/Guide+to+Designing+Resources), but there are many other pages that may be of interest
\ No newline at end of file
+ - [45 minutes, from 2025](https://youtu.be/Dz3HOaf6e-0)
+ - [90 minutes, from 2020](https://youtu.be/YbQcJj1GqH0)
+- The FHIR Confluence site, e.g., [Guide to Designing Resources](https://confluence.hl7.org/display/FHIR/Guide+to+Designing+Resources), but there are many other pages that may be of interest
+- Search the archives or ask for help at [chat.fhir.org (a.k.a. Zulip)](https://chat.fhir.org/)
\ No newline at end of file
diff --git a/fsh-seminar/input/pagecontent/index.md b/fsh-seminar/input/pagecontent/index.md
index 4e4c623..3ae6109 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
@@ -47,7 +47,7 @@ We recommend completing the course materials over two days as described below.
~1 hour; help available on chat.fhir.org
+ ~1 hour; help available on chat.fhir.org
@@ -62,7 +62,7 @@ We recommend completing the course materials over two days as described below.
~1 hour
@@ -106,7 +106,17 @@ We recommend completing the course materials over two days as described below.
Deep Dive With FSH
2-3 hours
@@ -121,7 +131,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/fsh-seminar/input/pagecontent/setup.md b/fsh-seminar/input/pagecontent/setup.md
index 6c05916..2f3b63c 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) -- 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
diff --git a/index.html b/index.html
index d8f0b3e..d74da58 100644
--- a/index.html
+++ b/index.html
@@ -96,7 +96,7 @@
-
-