SUSHI 3.0.0 Beta 2

SUSHI 3.0.0 Beta 2 is the second beta release for SUSHI 3.0. The SUSHI 3.0 beta releases change SUSHI behavior and output. They also require a later version of Node.js. As such, SUSHI 3.0 is considered to have breaking changes.

SUSHI 3.0.0 Beta 2 Overview

SUSHI 3.0.0 Beta 2 introduces the following changes from the SUSHI 3.0.0 Beta 1 release:

• Changes to how you use SUSHI on the command line (#1163)
• New optional "manual slicing" mode for improved control over slice order (#1121, #1200) (breaking change if enabled)
• Do not set resource version unless specifically set by author (#1143) (breaking change)
• Default resource status to IG status instead of active (#1143) (breaking change)
• New fsh-link-references.md file for easier linking in pages (#1136)
• Support for scientific notation of numbers (#1203)
• Order IG resources based on the configuration order (#1118)
• New update-dependencies command (#1152)
• Configurable log levels (#1208)
• Include default type slicing in differential (#1179)
• All updates from SUSHI 2.6.1, 2.7.0, 2.7.1, 2.8.0, and 2.9.0

SUSHI 3.0.0 Beta 2 Details

Changes to how you use SUSHI on the command line

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). See New update-dependencies command below for more details.

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.

New optional "manual slicing" mode for improved control over slice order

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.

Do not set resource version unless specifically set by author

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.

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.

Default resource status to IG status instead of active

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

New fsh-link-references.md file for easier linking in pages

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.

Support for scientific notation of numbers

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.

Order IG resources based on the configuration order

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.

New update-dependencies command

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.

Configurable log levels

While SUSHI 2.x allowed users to indicate if they wanted debug logging, SUSHI 3.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.

Include default type slicing in differential

SUSHI 3.0.0 Beta 1 stopped using choice type renaming in element ids and paths, preferring choice type slices instead. Unfortunately, it did not introduce the default type slicing metadata in the differential when it was needed. This has been fixed in SUSHI 3.0.0 Beta 2.

All updates from SUSHI 2.6.1, 2.7.0, 2.7.1, 2.8.0, and 2.9.0

SUSHI 3.0.0 Beta 1 branched off of the SUSHI 2.6.0 release. SUSHI 3.0.0 Beta 2 brings in all of the SUSHI 2.x changes that have happened since then, including the changes in SUSHI 2.6.1, 2.7.0, 2.7.1, 2.8.0, and 2.9.0.

SUSHI 3.0.0 Beta 1 Overview

The previous beta release, SUSHI 3.0.0 Beta 1, introduced the following changes from the SUSHI 2.x releases:

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

For more details on these changes, see the SUSHI 3.0.0 Beta 1 Release Notes.

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