SUSHI 3.0.0 is a major release of SUSHI introducing a number of new features, enhancements, and bug fixes. In addition, it adds preliminary support for FSH syntax and features that will be balloted in September. As a major release, this version contains breaking changes and updated system requirements.

The SUSHI team recommends that all users upgrade to SUSHI 3.0.0 by running the following command:

$ npm install -g fsh-sushi

Breaking Changes

The following breaking changes affect how you use SUSHI:

SUSHI now requires Node.js 18 (#933)
SUSHI executable now uses commands (#1163)

The following changes are considered breaking in that they change SUSHI's output in significant ways:

Element ids and paths no longer use choice type renaming (#954)
Choice elements are not sliced when they are restricted to only a single type (#1088)
The resource status element defaults to IG status instead of active (#1143)
The resource version element is only included when specifically set by the author (#1143)
Title and description elements are automatically assigned for Instances that support them (#1003)

New Features

The following new features support FSH specification changes that will be balloted in September:

Instances of logical models can be defined in FSH (#1280)
Elements of Invariant definitions can be defined using rules (#1272)
Insert rule parameters can be enclosed in double brackets to avoid excessive escaping (#1216)
Optional "manual slicing" mode improves control over slice order (#1121, #1200)
Path rules may be used to force export of required fixed values (#1252)

The following new features are specific to SUSHI, but not related to the specification:

Include the fsh-link-references.md file for easier linking in pages (#1136)
Run the update-dependencies command to check for dependency updates (#1152)
Configure log levels to affect logging output (#1208)
Specify an alternate package server to use for downloading dependencies (#1260)

Enhancements

The following enhancements affect how SUSHI processes FSH and FSH projects:

Support for scientific notation when defining number types (#1203)
Improved support for versioned canonicals (#1275)
Logical and Resource element names are checked against FHIR naming rules (#1230)
Improved ordering of resources in generated IG file (#1118)
Improved validation of sushi-config.yaml property names (#1265)
Improved support for paths whose names contain FSH keywords (#1244)
A new environment variable can be used to force fancy characters in console output (#1177)
Dependency loading uses new FHIR Package Loader library (#1026)
New and improved (?) puns (#1229)

Bug Fixes

The following bug fixes address bugs from the latest 2.x release:

Correctly resolve references to non-instance items (#1254, #1257)
Support versions in instance meta.profile when setting exampleCanonical in IG (#1228)
Populate IG exampleCanonicals regardless of meta.profile configuration (#1245)
Correctly parse unicode characters using \u escape sequence in strings (#1233)
Improve assigning instance as values, especially when instance id is a number or boolean (#1242)
Fix bug that sometimes caused primitives to be exported as objects (#1261)
Don't create Instances if the nearest specialization ancestor is abstract (#1237)

Additional Details

Breaking: SUSHI now requires Node.js 18 (#933)

Node.js 12 and 14 have reached their end-of-life and Node.js 16 will reach end-of-life in September 2023 (see Node.js Releases). In order to ensure that SUSHI remains performant and secure, it now requires Node.js 18 (LTS). Although previous versions of Node.js may 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/.

Breaking: SUSHI executable now uses commands (#1163)

The sushi executable now takes a command as the second argument. Available commands are: build, init, update-dependencies, and help. This provides a more consistent approach to using SUSHI and allows for further functionality in the future.

To build a project, use sushi build path/to/project (or sushi build to build the current directory).
To initialize a new project, use sushi init.
To update your dependencies to the latest versions, use sushi update-dependencies path/to/project (or sushi update-dependencies to update dependencies in the current directory).

For now, SUSHI will continue to accept the legacy usage for building, allowing for users to enter just sushi or sushi path/to/project. Future versions, however, may deprecate and/or remove legacy command support.

Breaking: Element ids and paths no longer use choice type renaming (#954)

SUSHI 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.

As of 2023, this is no longer considered best practice. As a results, SUSHI 3.0.0 no longer uses choice type renaming.

Consider the following rule on an Observation profile:

* valueQuantity MS

In SUSHI 2.x, this results in a differential element with the following id and path:

{
  "id": "Observation.valueQuantity",
  "path": "Observation.valueQuantity",
  // additional properties
}

In SUSHI 3.0.0, this results in the following id and path instead:

{
  "id": "Observation.value[x]:valueQuantity",
  "path": "Observation.value[x]",
  // additional properties
}

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

Breaking: Choice elements are not sliced when they are restricted to only a single type (#1088)

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.

Breaking: The resource `status` element defaults to IG status instead of `active` (#1143)

SUSHI 2.x automatically defaults the status field to active on Profiles, Extensions, Logical Models, Resources, Value Sets, and Code Systems. SUSHI 3.0.0, however, now defaults the status to be the same as the overall IG status. This aligns more closely to the behavior of the IG Publisher and more likely reflects the intended status of resources. Authors can always override the status on individual definitions via a caret rule (e.g., * ^status = #active).

Breaking: The resource `version` element is only included when specifically set by the author (#1143)

SUSHI 2.x automatically defaults the version field on Profiles, Extensions, Logical Models, Resources, Value Sets, and Code Systems to the version of the IG. SUSHI 3.0.0, however, no longer sets the version unless the author has specifically set it via a FSH rule. This allows the version to be controlled by the FHIR templates and IG Publisher. The default behavior for these is to apply the IG version across all resources, so most authors will not see a change in the end result when using the IG Publisher.

Authors who want more control over when and how version is set should look into the apply-version and default-version IG parameters, which can be set in the sushi-config.yaml parameters object.

Breaking: Title and description elements are automatically assigned for Instances that support them (#1003)

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 whose type supports a title element, SUSHI 3.0.0 will automatically assign that value to the instance's title element. Similarly, if an author specifies a Description: on an Instance whose type supports a description element, SUSHI 3.0.0 will automatically assign its 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"
}

Feature: Instances of logical models can be defined in FSH (#1280)

Authors can now use Instance: to create instances of logical models (and instances of logical model profiles). Instances are exported using standard JSON serialization and automatically receive id and meta.profile values when the logical model supports those elements (and according to configuration). Per requirements of the IG Publisher, logical model instances have filenames starting with Binary- and will be auto-encoded as part of the publishing process. As a result, these instances will be registered in the IG and rendered as simple JSON on their respective pages.

Feature: Elements of Invariant definitions can be defined using rules (#1272)

In FSH 2.0, Invariant definitions consisted only of keywords. This approach was inconsistent with how other items are defined in FSH and did not allow for adding extensions to invariants (such as the BestPractice extension). In SUSHI 3.0.0 (and the upcoming ballot of FSH), authors can use rules to specify invariant elements. For example:

Invariant:   us-core-6
Description: "Patient.name.given or Patient.name.family or both SHALL be present"
* severity = #error
* expression = "family.exists() or given.exists()"
* xpath = "f:given or f:family"

More details on the use of Invariant rules are available in the FSH language reference.

Feature: Insert rule parameters can be enclosed in double brackets to avoid excessive escaping (#1216)

Parameter values used in insert rules can be enclosed in double brackets to avoid most of instances of needing to escape ) and ,. More details on the use of this syntax are available in the FSH language reference.

Feature: Optional "manual slicing" mode improves control over slice order (#1121, #1200)

When processing Instances in SUSHI 2.x, SUSHI always processes the slices according to the following rules:

Required slices are added as the first elements in the sliced array.
If an author adds optional slices using named slice paths, they are added after the required slices.
If an author uses numeric index paths or soft index paths to reference slices, they may overwrite existing values and/or add new values.

This approach makes it difficult (or impossible) for authors to control the exact order of elements in a sliced array. In addition, it causes confusion when authors use soft indexing and mistakenly overwrite a required slice (partially or completely). That said, many authors have come to expect this behavior and have written their FSH to accommodate it. For this reason, SUSHI 3.0.0 continues to work this way by default (avoiding unexpected changes in existing IGs).

Going forward, however, FSH authors are encouraged to use the new instanceOptions --> manualSliceOrdering option in sushi-config.yaml. When set to true, this indicates that SUSHI should use the new manual slice ordering mode when processing instances. This new mode processes slices according to the following rules:

Authors should always add slice values using named slice paths.
Slice values are added to the array in the order they are referenced in the FSH Instance rules (while keeping items in the same slice contiguous).
When values are added using a soft index path, the soft index takes into account preceding named slice paths, adding the item after them.
Any remaining unreferenced required slices are added at the end.

Authors who enable manualSliceOrdering on existing projects should carefully review the results, as the new rules for slice application may result in unexpected output. To mitigate risk, authors should check all of their Instances to ensure they use named slice paths when assigning slice values in Instances.

To enable manual slice ordering add (or modify) the following in your sushi-config.yaml:

instanceOptions:
  manualSliceOrdering: true

NOTE: The FSH team recommends that new projects enable manualSliceOrdering. As such, the sushi init command will generate a sushi-config.yaml with manualSliceOrdering set to true.

For more information and examples, see Manual Slice Ordering on FSHSchool.

Feature: Path rules may be used to force export of required fixed values (#1252)

If a path rule in an Instance refers to an optional element, fixed values on that element will be set on that element. Additionally, any required child elements with fixed values will be set on that element. This is useful if those fixed values are the only values the author wants to set on the parent element.

More details about path rules are available in the FSH language reference.

Feature: Include the `fsh-link-references.md` file for easier linking in pages (#1136)

SUSHI 3.0.0 now generates a file at fsh-generated/includes/fsh-link-references.md. This file makes linking to IG resources easier in IG markdown pages. To use it, add {% include fsh-link-references.md %} to the bottom of the markdown (.md) file where you want to link by resource names.

After doing that, you can reference IG resources in that markdown file using their name surround by square brackets. For example, if your FSH defines Profile: NationalPatient, then the following markdown will correctly link to that profile:

This IG defines a [NationalPatient] that represents...

...

{% include fsh-link-references.md %}

This feature is optional. Authors who do not wish to use it should not add the include directive in their markdown files.

For more information and examples, see Link References on FSHSchool.

Feature: Run the `update-dependencies` command to check for dependency updates (#1152)

SUSHI 3.0.0 introduces a new update-dependencies command. When run, this command checks the dependencies defined in the sushi-config.yaml file to see if they are at the latest published versions. If SUSHI finds outdated dependencies, it will display a list of the outdated dependencies and ask the user if they wish to update. If the user chooses to update them, SUSHI will directly modify the sushi-config.yaml file with the latest versions and download them to the FHIR cache. Any dependency with a current or dev version will not be modified. This command can be used in the root folder of a project as follows:

sushi update-dependencies

Users can also specify a project path:

sushi update-dependencies path/to/project

For more information, see update-dependencies on FSHSchool.

Feature: Configure log levels to affect logging output (#1208)

While SUSHI 2.x allowed users to indicate if they wanted debug logging, SUSHI 3.0.0 allows users more control of the logging. Users can pass a -l or --log-level flag to specify the desired log-level: error, warn, info, or debug. For example, sushi build -l warn will run SUSHI in the current directory, outputting only warn and error messages.

Feature: Specify an alternate package server to use for downloading dependencies (#1260)

SUSHI uses the packages.fhir.org and packages2.fhir.org package servers for looking up and downloading dependencies. In some cases, however, users may need to override this behavior to use a different package server for dependency resolution. In this case, the FPL_CUSTOM_REGISTRY environment variable can be used to specify a different package server.

Enhancement: Support for scientific notation when defining number types (#1203)

Authors can now assign numbers using scientific notation. For example:

* valueInteger = 2e8

Both positive and negative exponents are supported, but authors should take care to ensure that the resulting value is appropriate for the data type it is being assigned to.

Enhancement: Improved support for versioned canonicals (#1275)

SUSHI 2.x supports some, but not all, uses of versioned canonicals. In some cases, it will allow the versioned canonical as input, but drop the version in its output. SUSHI 3.0.0 improves support for versioned canonicals by allowing them to be used in more places and retaining the version in more cases. Authors should note, however, that implementation is not complete and there still may be edge cases where versioned canonicals are not fully supported.

Enhancement: Logical and Resource element names are checked against FHIR naming rules (#1230)

The specification for ElementDefinition defines two invariants regarding element names: a strict invariant regarding prohibited characters and name length, and a less strict invariant regarding recommended format. When adding elements on Logical or Resource definitions, SUSHI now outputs errors for violations of the strict invariant and warnings for violations of the less strict invariant.

Enhancement: Improved ordering of resources in generated IG file (#1118)

SUSHI 3.0.0 preserves the order of resources when all resources are manually listed in sushi-config.yaml's resources section or groups sections. Otherwise SUSHI orders the resources by their title (when applicable) or id. This ordering affects the order in which resources are listed in the IG's generated table of contents.

Enhancement: Improved validation of `sushi-config.yaml` property names (#1265)

In SUSHI 2.x, unrecognized properties in sushi-config.yaml are ignored. As a result, mistakes in the configuration sometimes go unnoticed. SUSHI 3.0.0 validates configuration properties and logs warnings when it detects properties that are not known or supported.

Enhancement: Improved support for paths whose names contain FSH keywords (#1244)

SUSHI's parser now correctly recognizes when a FSH keyword, such as exclude, is being used as a path. Most FSH keywords can now be used as paths. There are still some cases that can result in ambiguous statements, but for most uses, there should no longer be any problems.

Enhancement: A new environment variable can be used to force fancy characters in console output (#1177)

The environment variable FORCE_FANCY_CHARACTERS can be set to force SUSHI to output fancy characters when being run by the IG publisher. Previously, SUSHI would never output fancy characters when being run by the IG publisher. The FORCE_FANCY_CHARACTERS environment variable should be set to 1 or true to enable this feature. Users may also wish to set the FORCE_COLOR environment variable, which is defined and used by chalk, to control color output.

Enhancement: Dependency loading uses new FHIR Package Loader library (#1026)

Much of SUSHI's package-loading capabilities have been moved to a new FHIR Package Loader project. This allows for better re-use of package loading logic across FSH tooling (such as SUSHI and GoFSH).

Enhancement: New and improved (?) puns (#1229)

Some freshly-caught fish puns are added in this release.

Bug Fix: Correctly resolve references to non-instance items (#1254, #1257)

References to non-Instance items are resolved using relative URLs, when possible. This applies to References to both local and external items. Furthermore, if the Reference points to a contained resource, the fragment id of the referenced item will be used.

Bug Fix: Support versions in instance meta.profile when setting exampleCanonical in IG (#1228)

Example instances may have a URL with a version in their meta.profile. If the profile with that URL and version are available, use that URL to set exampleCanonical in the IG.

Bug Fix: Populate IG exampleCanonicals regardless of meta.profile configuration (#1245)

SUSHI will add an exampleCanonical for example instances defined in FSH to the IG's resource list, even if the example instance's meta.profile element is not set.

Bug Fix: Correctly parse unicode characters using `\u` escape sequence in strings (#1233)

Unicode characters can be used in FSH strings by using \u followed by the character's four-digit code. For example:

* valueString = "This cool \u2603 can read music in \uD834\uDD1E!"

Bug Fix: Improve assigning instance as values, especially when instance id is a number or boolean (#1242)

Assignment rules, with or without caret paths, now consistently allow for the assignment of instances. Previously, SUSHI would not allow instance assignment in many situations, such as when defining a ValueSet. Additionally, since instances can legally have an id that looks like a number or boolean, SUSHI will be flexible when trying to assign such values. For example, an instance with id 12E1 can now be used in assignment rules.

Bug Fix: Fix bug that sometimes caused primitives to be exported as objects (#1261)

In rare cases, primitives were exported as objects instead of simple primitives. This behavior has been fixed.

Bug Fix: Don't create Instances if the nearest specialization ancestor is abstract (#1237)

SUSHI will not allow authors to create instances of abstract specializations, such as DomainResource. An instance of an abstract Profile is fine, as long as the nearest specialization ancestor is not abstract.

Install or Update

SUSHI 3.0.0 is now considered the latest stable release of fsh-sushi. To install or update to SUSHI 3.0.0, run the following command:

$ npm install -g fsh-sushi

To revert to the previous SUSHI 2.x stable release, run the following command:

$ npm install -g fsh-sushi@2.10.2

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

$ sushi -v

fsh-sushi 3.0.0 SUSHI 3.0.0 on Node.js NPM