SUSHI 2.7.0

SUSHI 2.7.0 includes the following enhancements and bug fixes:

• Update to support the current R5 ballot version of the Implementation Guide resource (details below)
• Properly validate elements on Instances that are children of slices (#1089)
• No longer include Instances of custom resources in the ImplementationGuide JSON to support IG Publisher requirement (#1090)
• Correct the grammar in an error message (#1142) thank you to @vadi2 for contributing this fix!

NOTE: At the time of this release, the HL7 IG Publisher crashes when attempting to process R5 IGs. This is a known issue and is expected to be fixed soon. As a result, you will not be able to do a full build of an R5 IG until the HL7 IG Publisher is fixed.

FHIR R5 Ballot ImplementationGuide Support

In a recent update, the IG Publisher now requires that any Implementation Guide published with a FHIR R5 version include an ImplementationGuide resource that is compliant to the current resource definition. If an Implementation Guide still uses FHIR R4, the R4 version of the ImplementationGuide can and should be used, as documented on chat.fhir.org here.

Because SUSHI generates this resource and there are breaking changes in the new version, this release updates the ImplementationGuide resource SUSHI generates. The following changes were made:

• Support for the new ImplementationGuide.definition.page.name element, which replaces the R4 ImplementationGuide.definition.page.nameUrl.
• Support for setting the new ImplementationGuide.definition.page.source[x] directly in the sushi-config.yaml file using sourceString, sourceUrl, or sourceMarkdown on an entry in pages.
• Support for representing ImplementationGuide.definition.parameter.code as a Coding.
  • If a parameter key in sushi-config.yaml's parameters entry is in FSH code format (i.e., {system}#{code}), SUSHI will use the provided system and code as the ImplementationGuide.definition.parameter.code. For example, the following parameter could be specified:

    parameters:
        http://example.org/parameters#new-parameter: true

  • Otherwise, if the parameter key is in the GuideParameterCode system, SUSHI will set that system automatically.
  • Otherwise, SUSHI will set the system to http://hl7.org/fhir/tools/CodeSystem/ig-parameters, as documented on chat.fhir.org here.
• Support for the new ImplementationGuide.definition.resource.isExample and ImplementationGuide.definition.resource.profile elements, which replace the R4 exampleBoolean and exampleCanonical elements.
• Support for setting the new ImplementationGuide.definition.resource.isExample directly in the sushi-config.yaml file.
• Support for setting the new ImplementationGuide.definition.resource.profile directly in the sushi-config.yaml file.
• Support for setting the new ImplementationGuide.copyrightLabel directly in the sushi-config.yaml file.
• Support for setting the new ImplementationGuide.versionAlgorithm[x] directly in the sushi-config.yaml file using versionAlgorithmString or versionAlgorithmCoding.
• Support for setting the new ImplementationGuide.dependsOn.reason directly in the sushi-config.yaml file in an entry in dependencies.

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation and/or the FSH Specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 3.0.0 Beta 1

SUSHI 3.0.0 Beta 1 is the first beta release for SUSHI 3.0. This release significantly changes SUSHI output in certain scenarios. It also requires a later version of Node.js. As such, this release is considered to have breaking changes.

SUSHI 3.0.0 Beta 1 Overview

SUSHI 3.0.0 Beta 1 introduces the following changes from the SUSHI 2.x releases:

• Require Node.js 16 or Node.js 18 (details below)
• Do not use choice type renaming in element ids or paths (#954) (details below)
• Do not slice choice elements when they have been restricted to a single type (#1088) (details below)
• Automatically assign title and description for Instances that support them (#1003) (details below)
• Use separate FHIR Package Loader library for handling dependencies (#1026)
• Update parser/lexer library to support more current versions of Node (#933)

NOTE: This is a beta release and may not be as stable as previous production releases. Additional beta releases with additional features and breaking changes are expected in the near future. Please be aware that functionality in this release is subject to change before the final release. We value user feedback, so please let us know your thoughts or concerns about this release.

SUSHI 3.0.0 Beta 1 Details

Require Node.js 16 or Node.js 18

Node.js 12 has reached its end-of-life and Node.js 14 is currently in its maintenance-only phase (see Node.js Releases). In order to ensure that SUSHI remains performant and secure, it now requires Node.js 16 (LTS) or 18 (Current). Although Node.js 12 (EOL) and 14 (Maintenance) currently work with this release of SUSHI, they are not officially supported (and may stop working in the future).

To download a more recent version of Node.js go to: https://nodejs.org/en/download/.

Do not use choice type renaming in element ids or paths

SUSHI 1.x and 2.x utilized an approach to choice types that simplified their element ids and paths. For example, Observation.value[x]:valueQuantity could be simplified to Observation.valueQuantity in the profile's differential and the IG Publisher would convert it to the "long form" during the snapshot generation process. This was referred to as choice type renaming.

While this was once considered an acceptable (and even recommended) approach, it is no longer considered good practice. In fact, in some cases this approach has caused problems in tooling and validation. As a result, SUSHI 3.0.0 no longer supports choice type renaming.

Consider the following rule on an Observation profile:

* valueQuantity MS

In SUSHI 2.x, this results in the following profile differential element:

{
  "id": "Observation.valueQuantity",
  "path": "Observation.valueQuantity",
  "min": 0,
  "max": "1",
  "type": [{ "code": "Quantity" }],
  "mustSupport": true
}

In SUSHI 3.0.0, this results in the following instead:

{
  "id": "Observation.value[x]:valueQuantity",
  "path": "Observation.value[x]",
  "sliceName": "valueQuantity",
  "min": 0,
  "max": "1",
  "type": [{ "code": "Quantity" }],
  "mustSupport": true
}

This provides a more consistent representation of choice type elements without changing their meaning.

Do not slice choice elements when they have been restricted to a single type

In SUSHI 2.x, whenever an author uses a type-specific path (such as valueCodeableConcept), it uses the standard type slicing mechanism to represent it. While this is necessary to distinguish types when there are multiple types to choose from, it is not necessary when a choice element has already been constrained to a single type.

For example, consider the following FSH definition:

Profile: MyObservation
Parent: Observation
* value[x] only CodeableConcept
* valueCodeableConcept from MyValueSet

Given the definition above, SUSHI 2.x will produce a differential that slices value[x] by type and introduces a specific choice type slice for valueCodeableConcept:

Given the same definition, SUSHI 3.0.0 will recognize that value[x] can only be a CodeableConcept and will simplify the differential by applying the constraint directly to value[x] instead of slicing it:

This maintains the intent of the profile while simplifying its representation by avoiding unnecessary slices when possible.

Note: If a choice element has already been sliced (i.e., by a parent profile), then SUSHI 3.0.0 will maintain consistency by using choice type slicing even if the choice element has already been reduced to a single type.

Automatically assign title and description for Instances that support them

To define conformance resources other than profiles, extensions, code systems, and value sets, authors must define an Instance of the resource. Although conformance resources often have a title and description, SUSHI 2.x requires authors to set those using assignment rules (e.g., * title = "My Operation Definition"), even when the author already specified a title using the Title: keyword.

In SUSHI 3.0.0, if an author specifies a Title: on an Instance, and that instance type supports a title element, SUSHI 3.0.0 will automatically assign the Title: keyword value to the instance's title element. Similarly, if an author specifies a Description: on an Instance, and that instance type supports a description element, SUSHI 3.0.0 will automatically assign the Description: keyword value to the instance's description element.

For example, consider the following FSH definition:

Instance: MyBlankConceptMap
InstanceOf: ConceptMap
Title: "My Blank ConceptMap"
Description: "A blank ConceptMap (for example purposes)."
Usage: #definition
* status = #draft

In SUSHI 2.x, the Title: and Description: values will be used for generating documentation in the IG, but the actual instance will not contain them:

{
  "resourceType": "ConceptMap",
  "id": "MyBlankConceptMap",
  "url": "http://example.org/ConceptMap/MyBlankConceptMap",
  "status": "draft"
}

In SUSHI 3.0.0, however, the Title: and Description: values will be automatically applied to the instance:

{
  "resourceType": "ConceptMap",
  "id": "MyBlankConceptMap",
  "url": "http://example.org/ConceptMap/MyBlankConceptMap",
  "title": "My Blank ConceptMap",
  "description": "A blank ConceptMap (for example purposes).",
  "status": "draft"
}

Install or Update

NPM only installs non-stable releases when a tag or version number is specified. To install or update to this beta version of SUSHI, run the following command:

$ npm install -g [email protected]

To revert to the most recent stable (non-beta) release, run the following command:

$ npm install -g fsh-sushi

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

Using SUSHI 3.0.0 Beta 1 in the Auto Build

The autobuild environment uses the latest stable version of SUSHI. To force the IG Publisher to use SUSHI 3.0.0-beta.1 when building your project (such as in the autobuild environment), create a fsh.ini file at the root of your project with the following contents:

[FSH]
sushi-version=3.0.0-beta.1

SUSHI 2.6.1

SUSHI 2.6.1 includes the following enhancements and bug fixes:

• SUSHI now allows for cardinality changes to child elements of sliced elements if the new cardinality is compatible with the existing cardinalities on child elements of the parent's slices (#1120) (details below)
• Fixes a bug causing minified XHTML values to work improperly with Webpack 5 (#1113) many thanks to @alexgwalley for contributing this fix!
• SUSHI now honors the NPM_CONFIG_REGISTRY environment variable when checking for the most recent SUSHI version (#1082) many thanks to @bkaney for contributing this fix!

Allow cardinality constraints to be applied to connected elements
When constraining cardinality, previous versions of SUSHI would not allow cardinality rules if the element’s new cardinality is narrower than the cardinality on any equivalent child elements of the slices of the parent (e.g. foo.bar and foo:slice.bar). Now, if all equivalent child elements can safely have the new cardinality constraint applied to them, the cardinality constraint is applied. Likewise, if any equivalent child elements can not safely accept the new cardinality constraint, the cardinality constraint is not applied to the rule’s element or any equivalent child elements.

As an example, consider a case where foo[mySlice].bar currently has a cardinality of 1..5 foo.bar currently has a cardinality of 0..*, and a cardinality constraint is being applied to foo.bar:

• Constraining foo.bar to 0..4 is safe. The resulting cardinality on foo[mySlice].bar will be 1..4.
• Constraining foo.bar to 2..6 is safe. The resulting cardinality on foo[mySlice].bar will be 2..5.
• Constraining foo.bar to 0..10 is safe. The cardinality on foo[mySlice].bar will remain 1..5.
• Constraining foo.bar to 1..1 is safe. The resulting cardinality on foo[mySlice].bar will be 1..1.
• Constraining foo.bar to 6..8 is not safe. An error will be logged, and no cardinalities will change.

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation and/or the FSH Specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi
To revert to a previous release, run a command like the following:

$ npm install -g [email protected]
To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 2.6.0

SUSHI 2.6.0 includes the following enhancements and bug fixes:

• Friendlier configuration properties (details below) (#1018, #1019)
• Add support for extensions on Implementation Guide pages that are configured in sushi-config.yaml (details below) (#1094)
• Allow SUSHI to run without any arguments (#1092)
• Canonical keyword is insensitive to definition order (#1073)
• Validate the values of complex types when assigning a value (#1108)
• Avoid assigning duplicate values on sliced elements (#1008)
• Fix incorrect error when constraining types on choice elements with semi-matching slice names (#1061)

Friendlier Configuration Properties

SUSHI now supports referring to resources by their name or id in the sushi-config.yaml file in various places. The resource name or id can be used directly in the following places:

• global profile values
• group resources
• resources
• resources' exampleCanonicals

For example, SUSHI use to require a configuration file to look like the following:

global:
  Patient: http://example.org/fhir/StructureDefinition/my-patient-profile
  Encounter: http://example.org/fhir/StructureDefinition/my-encounter-profile

resources:
  Patient/my-example-patient:
    name: My Example Patient
    description: An example Patient
    exampleBoolean: true

The following simpler and friendlier syntax is now supported and is equivalent to the configuration above:

global:
  Patient: MyPatientProfile
  Encounter: MyEncounterProfile

resources:
  my-example-patient:
    name: My Example Patient
    description: An example Patient
    exampleBoolean: true

For further examples, see #1018.

In addition, groups can now be defined without any resources. The following configuration format is now supported:

groups:
  GroupA:
    name: Group A
    description: My Group A
  GroupB:
    name: Group B
    description: My Group B

For more detailed examples of how to define groups, see #1019.

Extensions on Configured ImplementationGuide Pages

SUSHI supports configuring pages in the ImplementationGuide resource through the sushi-config.yaml file. Now, SUSHI supports adding extensions to the configured pages. The following configuration is now supported:

pages:
  index.md:
    title: Example Home
    extension:
      - url: http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status
        valueCode: trial-use

An extension array with the configured properties is added to the "Example Home" page entry in the ImplementationGuide.

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation and/or the FSH Specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 2.5.0

SUSHI 2.5.0 includes the following enhancements and bug fixes:

• New --require-latest flag to indicate SUSHI should fail if it is not the latest version (details below) (#1083)
• Failure to determine latest SUSHI version is now logged as a warning (rather than error) (#1084)
• Fix handling of extensions in CodeSystem and ValueSet definitions (#1069)
• Fix resolution of baseDefinitions that use a versioned canonical URL (#1067)
• Only consider master/main branches when searching for current dependency version (#1017)
• Fix download of current dependencies that use main branch (#1075)
• Warn when authors access an existing slice by index rather than slice name (#1030)

New --require-latest flag to indicate SUSHI should fail if it is not the latest version

As of SUSHI 2.4.0, SUSHI informs users when there is a newer version of SUSHI available. Starting with this release (2.5.0), authors may optionally use the --require-latest flag to force SUSHI to exit with an error if it detects that a newer version is available or if it can't determine what the latest version is. This may be especially helpful in publication workflows where it is important that the latest version of SUSHI be used.

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation and/or the FSH Specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 2.4.1

SUSHI 2.4.1 addresses security vulnerabilities found in SUSHI 2.4.0.

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation and/or the FSH Specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 2.4.0

SUSHI 2.4.0 includes the following enhancements and bug fixes:

• Allows contentReference elements to be defined on Logical Models and custom Resources (#1009) (details below)
• Fixes choice type rule paths in Instance assignment rules to use the type specific path (#1032) (details below)
• Alerts users when a new version of SUSHI is available (#969)
• Fixes support for HTTPS proxies (using https_proxy environment variable) (#1045)
• Loads predefined resources in subfolders of existing supported input folders when implicated by the path-resource parameter (#1037)
• Allows concepts added to a CodeSystem via caret rules (e.g., ^) to be included in ValueSets (#1039)
• Now constrains the Reference type when using the Reference() keyword on an R4B/R5 element that supports Reference and CodeableReference (#1044)
• Fixes an issue where assigning a Reference value on an element would wipe out other values already present on the element (#1058)
• Fixes cardinality validation on choice element slices containing extensions (#1021)
• No longer warns for an invalid name or id on a resource when a caret rule on the same resource sets a valid name or id (#1024)
• Warns when an xhtml div element does not start and end with a div tag (#305)
• Warns when properties specific to IG creation are included in sushi-config.yaml when SUSHI is run in FSHOnly mode (#1051)
• Provides a more detailed error message when an attempt is made to add a top-level Extension to a Bundle resource (#1020)

Support for contentReference elements on Logical Models and custom Resources

Elements of type contentReference are now supported in AddElementRules by way of the contentReference keyword. To define an element of type contentReference simply include contentReference <url-to-referenced-element> in the AddElementRule where the type would typically go. E.g. the final AddElementRule will create an element nameReference that is a contentReference to the element found at http://example.org/StructureDefinition/PatientExample#Patient.name.

* section.section 0..1 contentReference http://example.org/StructureDefinition/Report#Report.section "A sub-section"

Updating choice element paths to be type-specific

When assigning values to choice elements on an Instance, type-specific elements should always be used in the rules. In cases where an author specifies a choice element in an instance (e.g., value[x]), SUSHI will change the path to refer to the type-specific element if the choice is constrained to a single type. E.g. The final assignment rule on the following example will be read as * valueBoolean = true as the Instance is exported. Authors, however, should avoid using this construct in instances and should always prefer using type-specific elements to begin with.

Profile: BooleanObservation
Parent: Observation
* value[x] only boolean

Instance: MyObservation
InstanceOf: BooleanObservation
* status = #final
* code = http://example#somecode
* value[x] = true

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation and/or the FSH Specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 2.3.0

SUSHI 2.3.0 includes the following enhancements and bug fixes:

• Improve warning message about files in unsupported folders within the input directory (#987, #986)
• Add support for specifying additional resource paths to predefined resources (#1014, #986) (details below)
• Include provided extensions from sushi-config in the ImplementationGuide resource (#1005)
• Create an IG URL for dependencies listed in sushi-config that do not have an ImplementationGuide resource (#1007) (details below)
• Support referencing the canonical URL of the ImplementationGuide using the Canonical keyword (#963) (details below)
• Improve SUSHI's efficiency when processing profiles and eliminate unexpected error (#1013)
• Improve support for processing large base64 encoded values (#998)
• Update the copy utility used during the build process (#1004)

Specifying additional resource paths

Sometimes authors may wish to put predefined resources in folders other than the normally supported input sub-folders. To support this, SUSHI now recognizes the ImplementationGuide parameter path-resource. Authors can include this parameter in sushi-config.yaml to specify relative paths to additional folders that contain predefined resources. For example, the following can now be used in sushi-config.yaml to include resources from the sub-folder predefined-resources:

parameters:
  path-resource:
    - input/predefined-resources

Note that the value of path-resource is an array (or sequence) formatted in the standard YAML style.

For SUSHI users who manage their own ImplementationGuide resource (i.e. FSHOnly IGs), SUSHI will use the parameter from the ImplementationGuide resource:

"parameter": [
  {
    "code": "path-resource",
    "value": "input/predefined-resource"
  }
]

Automatically create a URL for dependencies with no ImplementationGuide

Some dependency packages do not contain an ImplementationGuide resource. Since SUSHI needs the ImplementationGuide URL to specify the dependency in its own generated ImplementationGuide (per FHIR requirements), this caused problems in the past. Prior to this release, authors had to address the problem by fully specifying the dependency with a uri, like this:

dependencies:
  de.basisprofil.r4:
    uri: http://fhir.org/packages/de.basisprofil.r4/ImplementationGuide/de.basisprofil.r4
    version: 1.1.0

Since then, the FHIR community has determined that packages without an ImplementationGuide should use a virtual IG URL of the format http://fhir.org/packages/${packageId}/ImplementationGuide/${packageId}. Using that guidance, SUSHI can now infer IG URLs for dependency packages without an IG; meaning that authors no longer need to fully specify such dependencies. Starting with this release, authors can simply declare an IG-less dependency like all other dependencies:

dependencies:
  de.basisprofil.r4: 1.1.0

Use the Canonical keyword to reference the canonical URL of the ImplementationGuide

There may be cases where an author needs to refer to the canonical URL of the ImplementationGuide resource they are creating. SUSHI now supports using the Canonical keyword with the id, packageId, or name that is specified in sushi-config.yaml. For example, when creating a CapabilityStatement, the following Assignment Rule can be added:

* implementationGuide = Canonical(my-package-id)

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation and/or the FSH Specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 2.2.6

SUSHI 2.2.6 includes the following bug fixes and minor enhancements:

• Supports in-lining FSH-defined profiles, value sets, and code systems in instances (e.g., in contained, Bundle.entry.resource) (#971, #1000)
• Fixes bug in XHTML processing that could cause invalid XHTML output (#1001, #1002)

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation, the FSH STU1 specification, and/or the FSH current build specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v

SUSHI 2.2.5

SUSHI 2.2.5 includes the following bug fixes and minor enhancements:

• Supports projects using FHIR version 5.0.0-snapshot1 (#994, #995) (details below)
• Fixes handling of elements w/ a slicename matching the element name (#993, #996)

FHIR 5.0.0-snapshot1

The latest R5 pre-release is version 5.0.0-snapshot. Projects that wish to use this version of FHIR can now specify it in their sushi-config.yaml file:

fhirVersion: 5.0.0-snapshot1

NOTE: At the time of this release, the IG Publisher does not yet support FHIR 5.0.0-snapshot1. So while you can use it with SUSHI, you will not yet be able to fully build the IG using the FHIR IG Publisher. IG Publisher support for 5.0.0-snapshot1 is expected later today.

Full Documentation

For additional documentation, refer to FSH School's SUSHI documentation, the FSH STU1 specification, and/or the FSH current build specification.

Install or Update

To install or update to this release, run the following command:

$ npm install -g fsh-sushi

To revert to a previous release, run a command like the following:

$ npm install -g [email protected]

To check or confirm what version of SUSHI you have installed, you can run the following command:

$ sushi -v