SUSHI 1.3.0

SUSHI 1.3.0 includes the following new features, enhancements, and bug fixes:

• Add capability for SUSHI to expand certain ValueSets (details below) (#736)
• Support all whitespace characters on quoted codes (#765)
• Support targeting an Instance with the Canonical keyword (#743)
• Add a warning that is logged when resources are specified with null array values (#486)
• Fix referencing extensions by URL on Instances (#674)
• Fix overwriting of extension URL values on Instances (#751)
• Fix assignment of values to sliced children of an element (#748)
• Fix assignment of extensions to primitive elements (#752)
• Fix confusing error message observed on FSH Online (#750)
• Fix bugs causing repeated extensions to appear on Instances (#759)

ValueSet Expansion

SUSHI now supports expansion of ValueSets in specific cases. To request a ValueSet expansion, the user can add the following two rules to the ValueSet which they wish to expand:

* ^expansion.parameter.name = "sushi-generated"
* ^expansion.parameter.valueBoolean = true

Expansion entails populating the ValueSet.expansion element. Expansion is only possible if the ValueSet.compose element contains some combination of specific codes, and CodeSystems which have CodeSystem.content set to complete. If the ValueSet is specified using filter operators, references other ValueSets, or references a CodeSystem that is not available to SUSHI, SUSHI will log an error and not attempt to expand the ValueSet.

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 stable 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 1.2.0

SUSHI 1.2.0 includes the following new features, enhancements, and bug fixes:

• Update Quantity syntax to support non-UCUM units (details below) (#730)
• Add support for the new R5 integer64 datatype (details below) (#728)
• Do not repeat mappings/invariants from the parent definition in the differential (#731)
• Do not allow slice errors to halt processing of other slices (#721)
• Treat redeclared extensions (via contains rules) as warnings rather than errors (#721)
• Treat names that don't match [A-Z]([A-Za-z0-9_]){0,254} as warnings instead of errors (#741)
• Support additional name variants (e.g., all numeric, matching flag names, etc.) (#741)
• Avoid use of regular expression features not supported in Safari (#749)
• Change exit code semantics: exit code now indicates number of errors encountered (0 continues to mean success) (#721)
• Fix "Cannot convert undefined..." error when applying extensions to arrays of primitives (#733)
• Fix handling of counting aggregrate cardinalities w/ slices and re-slices (#742)
• Fix duplicate values in meta.profile for exported Instances (#737)
• Fix SUSHI documentation link in sushi --init output (#738)
• New and improved puns (#732, #734, #747)

Update to Quantity Syntax

FHIR Shorthand STU1 supports an abbreviated Quantity syntax to indicate a value and UCUM unit:

* valueQuantity = 155.0 '[lb_av]'

SUSHI 1.1.0 updated the syntax to allow the human-readable unit to also be specified:

* valueQuantity = 155.0 '[lb_av]' "lb"

SUSHI 1.2.0 now allows for non-UCUM units by specifying the unit using the standard FSH code syntax:

* valueQuantity = 9623 http://potrzebie.org/mad/measures#blintz "blintz"

As is the case for other FSH codes, you can also use aliases:

Alias: POTRZEBIE = http://potrzebie.org/mad/measures
// ...
* valueQuantity = 9623 POTRZEBIE#blintz "blintz"

New integer64 Datatype

The integer64 datatype was introduced in FHIR 4.2.0. It supports a larger range of values than integer and is encoded in the JSON serialization as a string. To use integer64 in a FSH project, you must identify a FHIR version that supports it (e.g., 4.2.0, 4.4.0, 4.5.0, current). Otherwise it works as you would expect. For example, narrowing a type to integer64:

* value[x] only integer64

and assigning an integer64 value:

* extension[my-extension].valueInteger64 = 1234567890

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 stable 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 1.1.0

SUSHI 1.1.0 is a significant release of SUSHI that introduces several new features, including changes that may impact existing FSH projects. All SUSHI users should read these release notes for more details.

SUSHI 1.1.0 introduces the following significant features and enhancements:

• Supports soft indexing (#687, #781, proposed FSH STU2 feature, details below)
• Supports parameterized RuleSets (#700, proposed FSH STU2 feature, details below)
• Extends Quantity syntax to include unit string (#652, proposed FSH STU2 feature, details below)
• Introduces limited support for R5 (#698, details below)
• Applies extension metadata to root element (#719, affects existing projects, details below)

In addition, SUSHI 1.1.0 also contains the following minor enhancements and bug fixes:

• Allows aliases to be used with canonical | and version (#702)
• Allows SUSHI projects w/ sushi-config.yaml but no FSH files (#672)
• Allows sushi-config.yaml to reference generated pages (#696)
• Relaxes validation of array slices when indexed items are present (#707)
• Downloads IG publisher scripts from new location (#718)
• Fixes poor character rendering when run in IG Publisher (#697)
• Fixes bug that dropped the first character in some multi-line strings (#708)
• Fixes bug when using inline resources with meta properties (#726)
• Fixes bug when using Canonical with inline resources (#688)
• Fixes bug when using block comments without whitespace (#681)
• Fixes incorrect paths in generated document comments (#705, #706)
• Improves potentially confusing error message (#703)

Soft Indexing

FHIR Shorthand STU1 requires that all items in an array be indexed using numeric indices (or an omitted index to represent [0]). For example, to assign multiple names in an instance of Patient, the following FSH could be used:

* name[0].given = "Robert"
* name[0].family = "Smith"
* name[1].given = "Rob"
* name[1].family = "Smith"
* name[2].given = "Bob"
* name[2].family = "Smith"

In complex resources such as Bundle and CapabilityStatement, arrays may have tens or hundreds of items. As a result, managing their indices can become quite tedious and error prone when needing to add or remove items in the middle of a list.

Soft indexing is a proposed feature for FHIR Shorthand STU2. Soft indexing allows authors to signal when an array index should be incremented rather than needing to track specific numeric indices. Using soft indexing, [+] increments the index and [=] represents the most recently used index. When an array is empty, [+] refers to the first element ([0]). Using soft indexing, the example above could be written as:

* name[+].given = "Robert"
* name[=].family = "Smith"
* name[+].given = "Rob"
* name[=].family = "Smith"
* name[+].given = "Bob"
* name[=].family = "Smith"

For more information, see the soft indexing documentation.

Parameterized RuleSets

FHIR Shorthand STU1 supports simple RuleSets with static content. Wherever the RuleSet is inserted, the same exact FSH will be inserted. In many cases, however, authors may want to insert a RuleSet for which a few values might be variable.

Parameterized RuleSets is a proposed FSH STU2 feature that allows authors to define RuleSets with variable parameters that can be supplied when the RuleSet is inserted. Following the example from the soft indexing section above, an author could create a parameterized RuleSet to assign a Patient's first and last name:

RuleSet: Name(first, last)
* name[+].given = "{first}"
* name[=].family = "{last}"

To assign three different names in a Patient instance, the author could insert the RuleSet three times, each with the desired first and last names:

* insert Name(Robert, Smith)
* insert Name(Rob, Smith)
* insert Name(Bob, Smith)

When the inserted RuleSets are expanded, and soft indexing is resolved, the result would be equivalent to:

* name[0].given = "Robert"
* name[0].family = "Smith"
* name[1].given = "Rob"
* name[1].family = "Smith"
* name[2].given = "Bob"
* name[2].family = "Smith"

For more information, see the documentation for defining parameterized RuleSets and inserting parameterized RuleSets.

Extended Quantity Syntax

FHIR Shorthand STU1 supports a simple syntax for assigning a Quantity with a value and a UCUM unit (which sets the system and code). To also assign the string unit property, however, the author needs an additional assignment rule. For example:

* valueQuantity = 155.0 '[lb_av]'
* valueQuantity.unit = "lb"

Supporting the string unit property in the Quantity syntax is proposed for FHIR Shorthand STU2. Using this new syntax, the above FSH could be written as a single rule:

* valueQuantity = 155.0 '[lb_av]' "lb"

Limited Support for R5

SUSHI 1.0.x (and previous versions) supports only FHIR 4.0.1. Starting with SUSHI 1.1.0, authors can specify any of the following fhirVersion values in their sushi-config.yaml or IG file:

• 4.0.1
• 4.2.0
• 4.4.0
• 4.5.0
• current

SUSHI will use the formal FHIR definitions for the version of FHIR that is specified. If current is specified, SUSHI will use the latest CI build of FHIR.

Limitations: SUSHI has not been extensively tested with versions of FHIR > 4.0.1. In addition, SUSHI 1.1.0 does not yet contain specific support for the new integer64 or CodeableReference datatypes. Constraining or assigning elements of type integer64 or CodeableReference is not expected to work in this release.

Application of Extension Metadata

When an extension is applied to a profile definition, the FHIR IG publisher uses the extension root element's short and definition values as the extension description in the profile's snapshot/differential tables and "Detailed Descriptions" tab. If the author has not explicitly set the extension's root element's short and definiton values, generic placeholders will be used. For example:

Starting in SUSHI 1.1.0, if an author has not explicitly defined an extension root element's short or definition, SUSHI will automatically apply the extension definition's Title to the root element short, and Description to the root element definition. This provides the default behavior and rendering that most IG authors would expect and desire, without requiring redundant descriptions in the FSH. This will result in the above example now be rendered like this:

Authors who do not want this behavior can turn it off by using the applyExtensionMetadataToRoot configuration property in sushi-config.yaml:

applyExtensionMetadataToRoot: false

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 stable 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 1.0.2

SUSHI 1.0.2 is a patch release with the following fixes and minor enhancements:

• Enforces specific dependency library versions to ensure SUSHI installations behave as expected (#675)
  • This specifically fixes a bug related to ANTLR4 v4.9.0 and Node 14 that some users have experienced
• Fixes handling of content references when the reference is more than a fragment (#671)
• Adds a link to migration instructions when legacy projects are detected (#676)
• New and improved puns! Try to find them all!

SUSHI 1.0.0 was a significant major release of SUSHI. Please see the SUSHI 1.0.0 Release Notes for a full description of changes in SUSHI 1.0.0.

Full Documentation

For additional documentation, refer to FSH School's SUSHI 1.0 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 stable 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 0.16.1

WARNING: THIS IS A "LEGACY" RELEASE OF SUSHI!
Most users should be using SUSHI 1.x. This release should only be used for projects that cannot use SUSHI 1.x.
(By the way, if you are one of those projects, please contact us so we can understand why 1.x does not work for you.)

SUSHI 0.16.1 is a patch release to SUSHI 0.16.0 with the following fixes and enhancements:

• Enforces specific dependency library versions to ensure SUSHI installations behave as expected
  • This specifically fixes a bug related to ANTLR4 v4.9.0 and Node 14 that some users have experienced
• Adds an API function for invoking SUSHI (NOTE: this function may not work the same as the 1.x function) (#599)
• Fixes bug with cardinality min value of choices when type slicing is used (#596)
• Fixes bug with finding slices of choice slices (#567, #593)
• Sets the grouping id in the IG JSON file when using the group property in config.yaml (#590)

Full Documentation

For additional documentation on this legacy version of SUSHI, refer to FSH School's Legacy Documentation.

Install, Update, or Downgrade

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

$ 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 1.0.1

SUSHI 1.0.1 is a patch release addressing one issue discovered using SUSHI 1.0.0:

• Changed format for logging inferred dependencies to log a dependency per line (#669)

This change was needed due to a limitation in the HL7 IG Publisher: if SUSHI outputs a log statement larger than 255 characters, the IG Publisher will immediately stop relaying all SUSHI logs, giving the appearance that SUSHI has stopped (even though it has not stopped). The log statement for inferred dependencies occasionally triggered this limitation in the IG Publisher, so this fix helps mitigate the issue by splitting that log statement into multiple lines (one line per dependency).

SUSHI 1.0.0 was a significant major release of SUSHI. Please see the SUSHI 1.0.0 Release Notes for a full description of changes in SUSHI 1.0.0.

Full Documentation

For additional documentation, refer to FSH School's SUSHI 1.0 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 stable 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 1.0.0

This is the official, stable SUSHI 1.0.0 release, marking the end of the beta phase for SUSHI 1.0.0. SUSHI 1.0.0 includes full support for FHIR Shorthand 1.0 and a new project structure to better support IG Publisher integration.

New Project Structure

SUSHI 1.0 no longer uses a top-level fsh folder or a nested ig-data folder. Instead, SUSHI 1.0 projects are designed to fit seamlessly within the current template-based IG Publisher project structure. Using SUSHI 1.0:

• Authors configure SUSHI via /sushi-config.yaml (previously /fsh/config.yaml)
• Authors put all .fsh files in /input/fsh/* (previously /fsh/*)
• Authors put all other IG files (ig.ini, package-list.json, menu.xml, pages, etc.) in their normal locations based on current IG Publisher requirements (previously /fsh/ig-data/*)
• SUSHI generates all outputs to /fsh-generated and clears it before each generation (previously /* and /input/* without clearing old generated files)

This approach has several advantages over the old approach:

• Project layout and structure is consistent with all template-based IG Publisher projects
• Existing projects can more easily convert to using SUSHI, even leveraging incremental conversion
• All source files and generated files are clearly separated, and no longer need to be copied around

For detailed instructions on the new project structure see the SUSHI 1.0 Project Structure documentation.

To migrate an existing SUSHI 0.16.0 project to the new project structure see the SUSHI 1.0 Migration Guide.

Supported Templates

The new SUSHI project structure required that changes be made to the base template in order to find and use files in the /fsh-generated folder. Currently, these changes are only in the #current version of the base template, so your project's /ig.ini MUST specify a template that is based on fhir.base.template#current. For now, any of the following should work:

• fhir.base.template#current
• hl7.base.template#current
• hl7.fhir.template#current
• hl7.davinci.template#current
• hl7.cda.template#current

Once the base template has been officially released with these changes, you will be able to use a locked version of a template again.

Deprecated Features

SUSHI 1.0.0 deprecates several features found in SUSHI 0.16.0. These features were deprecated based on feedback from the FHIR Core team and SUSHI users, as well as to provide a cleaner, more consistent approach to developing IGs.

• The template property in the SUSHI configuration is no longer supported. Authors should manage the /ig.ini file directly.
• The history property in the SUSHI configuration is no longer supported. For now, authors should manage the /package-list.json file directly, but further guidance may come from the FHIR Core team in the future.
• The /input/ignoreWarnings.txt file is no longer generated by SUSHI. Authors should manage this file directly.
• The /_updatePublisher, /_genonce, and /_gencontinuous scripts are no longer generated by SUSHI. If you wish to use these scripts, you can always download the latest versions from the sample-ig repository. (NOTE: sushi --init will download these automatically if you use it to initialize a new project).
• The external keyword for menu URLs in config.yaml is no longer supported since the IG Publisher now detects external links and automatically inserts an external link icon.

Legacy Projects

SUSHI 1.0.0 continues to support "legacy" projects (i.e., projects not using the new file structure). In these cases, the behavior should be the same as in SUSHI 0.x, with one caveat: SUSHI will not generate the publisher scripts even for legacy projects.

If SUSHI detects that you are using a legacy project format, it will issue a warning that you should update your project to the new project structure. Support for legacy projects will be removed in a future version of SUSHI.

HL7 IG Auto-Builder

Currently, the HL7 IG Auto-Builder uses the most recent official version of SUSHI. This means that all projects will now build using SUSHI 1.0.0 by default. We do not anticipate this causing any issues due to SUSHI's support of legacy project structures. If you absolutely must continue using the pre-1.0.0 SUSHI, you can affect the version of SUSHI that the IG Publisher uses by providing a fsh.ini file at the root of the project with the following contents:

[FSH]
sushi-version=0.16.0

Additional Changes
In addition to the changes to project structure and configuration, SUSHI 1.0.0 includes the following changes and bug fixes:

• Fixes SUSHI incorrectly counting the minimum cardinality on sliced elements (#659)
• If SUSHI is run against a directory with no FSH files but the directory has a config.yaml file, SUSHI will not exit early.
• Fixes bug with using ad hoc extensions on nested paths in instances (#621)
• Fixes bug with cardinality min value of choices when type slicing is used (#596)
• Fixes bug with finding slices of choice slices (#593)
• Supports setting the resource description in the generated ImplementationGuide on conformance and terminology resources only (#629)
• Avoids generating a duplicate resource when a resource is provided in input and defined in FSH (#623)
• Correctly extracts SUSHI configuration information from a provided ImplementationGuide resource (#635)
• Skips the processing of XML files that appear to be spreadsheets (#638)
• Fixes a bug where SUSHI specific comments were appended to input files (#626)
• Fixes a bug that allows uses the current working directory as the input directory if is not specified (#627)
• Resets the errors and warnings in between invocations of fshToFhir (#625)
• Allows (and ignores) non-JSON/non-XML files in input/* resource folders (#641)
• Fixes ambiguous identifier in error message about duplicate resources (#642)
• Fixes bug that overwrote a Quantity value when a unit was set in a subsequent rule (#608)
• Fixes handling of MS flag when applied to sliced elements and/or slices (#647)
• Fixes assignment to Quantity specializations (e.g., Age) using FSH quantity syntax (#617)
• Merges Mapping rules when a matching Mapping already exists on the parent resource (#657)
• Exports _-prefixed properties (e.g., extensions on primitives) directly after their non-_ counterparts (#632)
• Changes config.yaml's group keys to represent id rather than name, allowing name to be set independently (#646)
• Emits an error if an inline extension is defined on a profile since this is disallowed by the IG Publisher (#591)
• Supports new instance-name and instance-description extensions to set example resource metadata in the generated IG (#654)

Full Documentation

For additional documentation, refer to FSH School's SUSHI 1.0 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 stable 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 1.0.0 Beta 4

SUSHI 1.0.0 Beta 4 is a candidate release for SUSHI 1.0.0. Barring the discovery of any major bugs, it will become the official SUSHI 1.0.0 release. SUSHI 1.0.0 Beta 4 contains the following bug fixes and enhancements since Beta 3:

• Fixes bug that overwrote a Quantity value when a unit was set in a subsequent rule (#608)
• Fixes handling of MS flag when applied to sliced elements and/or slices (#647)
• Fixes assignment to Quantity specializations (e.g., Age) using FSH quantity syntax (#617)
• Merges Mapping rules when a matching Mapping already exists on the parent resource (#657)
• Exports _-prefixed properties (e.g., extensions on primitives) directly after their non-_ counterparts (#632)
• Changes config.yaml's group keys to represent id rather than name, allowing name to be set independently (#646)

Full Documentation

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

Install or Update

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

$ npm install -g fsh-sushi@beta

To revert to a previous stable 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 1.0.0 Beta 3

SUSHI 1.0.0 Beta 3 contains fixes for two bugs reported by our users:

• Allows (and ignores) non-JSON/non-XML files in input/* resource folders (#641)
• Fixes ambiguous identifier in error message about duplicate resources (#642)

Full Documentation

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

Install or Update

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

$ npm install -g fsh-sushi@beta

To revert to a previous stable 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 1.0.0 Beta 2

SUSHI 1.0.0 Beta 2 contains the following enhancements and bug fixes:

• Supports setting the resource description in the generated ImplementationGuide on conformance and terminology resources only (#629)
• Avoids generating a duplicate resource when a resource is provided in input and defined in FSH (#623)
• Correctly extracts SUSHI configuration information from a provided ImplementationGuide resource (#635)
• Skips the processing of XML files that appear to be spreadsheets (#638)
• Fixes a bug where SUSHI specific comments were appended to input files (#626)
• Fixes a bug that allows uses the current working directory as the input directory if is not specified (#627)
• Resets the errors and warnings in between invocations of fshToFhir (#625)

Full Documentation

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

Install or Update

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

$ npm install -g fsh-sushi@beta

To revert to a previous stable 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