SUSHI 0.12.1

SUSHI 0.12.1 contains the following enhancements and bug fixes:

• Adds -f|--force flag to _updatePublisher.sh and _updatePublisher.bat to force the script to run without user input. Can be used in non-interactive settings (thanks @peturv!) (#327)
• Adds the ability to fix inline instances to elements of any matching type, not just elements of type Resource (#347)
• Fixes issue with setting version on compose.include elements in a ValueSet (#346)
• Fixes issue with finding paths with matching elements on instances (#357)
• Fixes issue with fixing values on slices that do not have associated discriminators (#362)

Full Documentation

For additional documentation, refer to the FSH language reference.

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.12.0

SUSHI 0.12.0 aligns with the FHIR Shorthand 0.12.0 (May 2020 ballot) specification. All FHIR Shorthand features specified in the balloted language reference are supported in this release of SUSHI.

SUSHI 0.12.0 contains the following enhancements and bug fixes:

• Introduces streamlined usage for IG Publisher workflows (details below)
• Allows multiline strings for concept definitions (#319)
• Supports using an alias as the value in fixed value rules (#87)
• Sets minimum cardinality to 1 for fixed values that are discriminator paths (#301)
• Checks for supported FHIR version and minimally verifies that FHIR cache is properly loaded
• Fixes comment insertion bug that caused XML parsing issues in IG Publisher (#338)
• Fixes handling of nested required fixed values when generating instances (#300)
• Fixes parser support for non-breaking spaces (#315)
• Adds more random punny expressions for the CLI summary report

Streamlined Usage for IG Publisher Workflows

The HL7 FHIR IG Publisher has recently been updated to support invoking SUSHI as part of the IG Publisher build. In this workflow, all FSH source (e.g., the "FSH Tank") must be contained in a subfolder called fsh. When the IG publisher detects the fsh subfolder, it will automatically run SUSHI on it and direct the SUSHI output to the root folder (the folder above fsh). After SUSHI completes successfully, the IG Publisher will run the normal publishing process on the outputted files in the root folder. For more information on this workflow, see New! IG Publisher Integration (Autobuild Configuration).

This version of SUSHI detects repositories that are set up for this workflow and adjusts the SUSHI input/output parameters accordingly. Starting with this version of sushi:

• If you type sushi with no input directory specified, it will use the working directory as the input directory.
• If the input directory is named fsh, or contains a subfolder named fsh, SUSHI will
  • use the fsh directory as input,
  • default output to the parent folder of fsh,
  • and skip generation of publisher scripts (since it assumes you are running the publisher already).

This means:

• Running sushi (with no arguments) in a folder containing a fsh subfolder is equivalent to running sushi ./fsh -o .. This mimics how the IG Publisher invokes SUSHI.
• Running sushi (with no arguments) in a folder named fsh is equivalent to running sushi . -o ...
• Running sushi (with no arguments) in any other folder is equivalent to running sushi . or sushi . -o ./build.

Full Documentation

For additional documentation, refer to the FSH language reference.

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.11.2

SUSHI 0.11.2 contains the following enhancements and bug fixes:

• Adds support for caret rules on the root element using the . path (details below)(#277)
• Adds do-not-edit warning to generated IG files where allowed (details below) (#309)
• Adds new SUSHI-GENERATED-FILES.md file in IG output (details below)
• Adds user-friendly results summary at end of console output (details below)
• Enforces requirement that invariant names be valid FHIR ids (#290)
• Fixes issue w/ sparse differentials and slice paths (#293)
• Fixes duplicate entries for instances used in inline references (#333)
• Fixes issue w/ single-line block comments (#155)
• Updates various application dependencies to their more recent versions

Root Element Path

A simple dot (.) can be used to reference the root element in path-based rules. Prior to this, it was not possible to access the root element in FSH. This capability is most useful for caret rules, e.g.:

Extension: MyExtension
Id: my-extension
* . ^short = "My Extension"
// ...

Do-Not-Edit Warnings in Generated Files

To prevent users from mistakenly editing generated output files (rather than the corresponding input files), SUSHI now inserts comments on generated or copied .xml, .md, .ini, and script files. Currently, this applies only to files related to IG configuration, not FHIR resources or instances. .json files are an exception, as standard JSON does not support comments.

Example (ig.ini):

[IG]
; **************************************************************************************************
; *                                 WARNING: DO NOT EDIT THIS FILE                                 *
; *                                                                                                *
; * This file is generated by SUSHI. Any edits you make to this file will be overwritten.          *
; *                                                                                                *
; * This ig.ini was generated by merging values from ig-data/ig.ini with a default set of values,  *
; * including values inferred from package.json (name, license, version). To affect the generation *
; * of this file, edit values in the ig-data/ig.ini input file.                                    *
; **************************************************************************************************
ig = input/ImplementationGuide-hl7.fhir.us.mcode.json
; ... etc.

SUSHI-GENERATED-FILES.md

SUSHI now creates a file named SUSHI-GENERATED-FILES.md with a table showing IG config files that were generated or copied and the original files that were used to generate or copy them. This gives users more insight into SUSHI's IG generation.

Example excerpt:

| SUSHI-GENERATED FILE                             | ACTION    | INPUT FILE(S)                                                       |
| ------------------------------------------------ | --------- | ------------------------------------------------------------------- |
| _gencontinuous.bat                               | generated |                                                                     |
| _gencontinuous.sh                                | generated |                                                                     |
| _genonce.bat                                     | generated |                                                                     |
| _genonce.sh                                      | generated |                                                                     |
| _updatePublisher.bat                             | generated |                                                                     |
| _updatePublisher.sh                              | generated |                                                                     |
| ig.ini                                           | generated | ../ig-data/ig.ini, ../package.json                                  |
| input/ImplementationGuide-hl7.fhir.us.mcode.json | generated | ../ig-data/ig.ini, ../package.json, {all input resources and pages} |
| input/ignoreWarnings.txt                         | copied    | ../ig-data/input/ignoreWarnings.txt                                 |
| input/includes/menu.xml                          | copied    | ../ig-data/input/includes/menu.xml                                  |
| input/pagecontent/change_log.md                  | copied    | ../ig-data/input/pagecontent/3_change_log.md                        |
| input/pagecontent/index.md                       | copied    | ../ig-data/input/pagecontent/index.md                               |
| package-list.json                                | copied    | ../ig-data/package-list.json                                        |
| package.json                                     | copied    | ../package.json                                                     |
| ... etc.                                         |           |                                                                     |

User-Friendly Results Summary

When SUSHI completes, it now prints a summary that is easier to understand at a glance. For consoles that support it, the summary will be color-coded green, orange, or red depending on if your build is clean, has warnings, or has errors. Just for fun, it also gives you a random fish-related pun summarizing the status of your results.

Full Documentation

For additional documentation, refer to the FSH language reference.

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.11.1

SUSHI 0.11.1 contains the following enhancements and bug fixes:

• BREAKING CHANGE: Changes fixed value rules to enable usage of (exactly) keyword (details below) (#218, #187)
• Adds support for Mixins and RuleSets (details below)
• Adds support for Mappings (details below)
• Adds Usage keyword on Instances (details below)
• Adds support for contained Instances (details below) (#224)
• Adds support for one sided cardinality statements (details below) (#258)
• Improves error reporting when applying rules to a sliced element which conflict with slices of that element (#227)
• Adds an optional units keyword that has no effect, but can be used to clarify setting values and binding on quantity types: * {Quantity type} units = {system}#{code} "{display text}" (#246)
• Adds support for setting standards status to "Normative", "Trial Use", or "Draft" using the N, TU, and D flags, respectively
• Updates the updatePublisher and genonce scripts based on the updates in the sample-ig: https://github.com/FHIR/sample-ig
• Generates a path-history parameter when being run on an HL7 IG (#286)
• Logs an error if a Profile defines itself as its own Parent
• Fixes bug with adding slices of a primitive on an Instance
• Fixes bug with failing to find slices of slices
• Fixes bug that would cause an error when using system in a path (#274)
• Fixes bug that caused obeys to fail when applied to id (#298)
• Fixes bug with local templates in ig.ini (#299)
• Fixes bug with line indentation on multiline strings (#306)

NOTE: We skipped directly to SUSHI 0.11.1 since a small bug was found and fixed in SUSHI 0.11.0 at the very end of the publishing process.

BREAKING CHANGE: New (exactly) keyword
In previous versions of SUSHI, a value was fixed on an element using either fixed[x] or pattern[x] depending on the type of the element. Primitive types were set using fixed[x] and complex types were set using pattern[x]. When a value is fixed using pattern[x], an Instance of that Profile must include at least the values indicated by pattern[x], but may contain additional values. When a value is fixed using fixed[x], an Instance of that Profile must include exactly the values indicated, and no additional values. Now, in SUSHI 0.11.1, all values will be fixed by default using pattern[x]. If users want to fix a value using fixed[x], they should use the (exactly) keyword, as shown below:

* {path} = {value} (exactly)

This change will not cause new errors when running SUSHI, but it could change the output of SUSHI. All primitive values that were previously being fixed by fixed[x] will now be set by pattern[x], unless the (exactly) keyword is added. The practical difference for primitives is that now, using pattern[x], instances are allowed to supply an id and/or extensions\ on the primitive values, whereas formerly this was not allowed since fixed[x]` was used. IG authors should consider this difference and check their fixed value rules to ensure they are fixing values as desired.

Mixins and RuleSets
A RuleSet is an entity that can be used in FSH to define a chunk of rules that can then be applied to Profiles, Extensions, or Instances. RuleSets are defined as follows:

RuleSet: {RuleSetName}
* {rule1}
* {rule2}
// More rules

The defined RuleSet can then be applied to a Profile, Extension, or Instance using the Mixins keyword:

Profile: MyPatientProfile
Parent: Patient
Mixins: {RuleSet1}, {RuleSet2}

All RuleSets are applied before applying rules from the Profile, Extension or Instance, in the order that they are listed. Rules from a RuleSet should be compatible with the item they are being mixed into, and errors will be thrown if this is not the case.

Mappings
A Mapping is an entity that can be used in FSH to map a Profile or Extension to another standard. Mapping definitions use the following keywords, which map to the FHIR StructureDefinition mapping properties as follows:

FSH Mapping Keyword	FHIR Mapping Property
Mapping	n/a (provides unique name)
Source	n/a (name of the profile to apply this to)
Target	mapping.uri
Id	mapping.identity
Title	mapping.name
Description	mapping.comment

Once a mapping is defined using these keywords, rules can be added to map individual elements using the syntax:

* {path} -> "{map}" "{comment}" {mime-type}

The "{comment}" and {mime-type} are optional. Each rule maps to the FHIR ElementDefinition mapping properties as follows:

Mapping Rule Part	FHIR Mapping Property
{path}	n/a (selects element to apply mapping on)
"{map}"	mapping.map
"{comment}"	mapping.comment
{mime-type}	mapping.language

An example of a mapping on USCorePatient to Argonaut is shown below:

Mapping:  USCorePatientToArgonaut
Source:   USCorePatient
Target:   "http://unknown.org/Argonaut-DQ-DSTU2"
Title:    "Argonaut DSTU2"
Description: "This is a mapping of US Core Patient to Argonaut"
Id:       argonaut-dq-dstu2
* identifier -> "Patient.identifier" "optional comment" #optionalCode
* identifier.system -> "Patient.identifier.system"

Usage keyword on Instances
Previously, all Instances were treated as examples. Now, the user has the power to specify the usage of an instance using the Usage keyword. The Usage can be specified as one of three values:

• #example means the instance is intended as an illustration of a profile, and will be presented on the Examples tab for the corresponding profile.
• #definition means the instance is a conformance item that is an instance of a resource such as a search parameter, operation definition, or questionnaire. These items will each be presented on their own IG page.
• #inline means the instance should not be instantiated as an independent resource, but appears as part of another instance (for example, in a composition or bundle).

When no Usage is specified, the default value is #example. See below for an example of how usage can be used:

Instance:  MyPerson
InstanceOf: MyPatientProfile
Usage:  #example
// some rules

Instance: MySearchParameter
InstanceOf: SearchParameter
Usage: #definition
// some rules

Contained Instances
Often, FHIR resources have elements of type Resource. Examples include the contained element, or fields on the Bundle resource. Previously, there was no way to set values to elements of this type on an Instance. SUSHI 0.11.1 introduces a syntax for setting elements of type Resource to another Instance defined in FSH. The syntax works as shown below:

Instance: MyPatient
InstanceOf: Patient
* name[0].family = "InstanceMan"

Instance: MyBundle
InstanceOf: Bundle
* entry[0].resource = MyPatient

In the example, we create an Instance of Patient, and then we set the resource field on the first element of the entry array to that Instance. The MyBundle Instance will now contain a copy of the MyPatient Instance at the indicated path. This syntax can be combined with the Usage keyword described above. If the Usage on MyPatient is set to #inline, then no independent JSON file will be generated for the MyPatient Instance. That Instance will only exist in the context of MyBundle. This can help reduce cluttered output when adding many contained Instances.

One Sided Cardinality
SUSHI 0.11.1 introduces the ability to only specify one side of a cardinality. Users can now specify * path 1.., or * path ..1. If one side of the cardinality is left off, the element's current cardinality will be used for that side. This is not a requirement, two sided cardinality statements are still allowed, but this allows users to avoid specifying information that is not being changed.

Full Documentation
For additional documentation, refer to the FSH language reference.

Install or Update
To install or update to the latest version, run the following command:

$ npm install -g fsh-sushi

SUSHI 0.10.0

SUSHI 0.10.0 (or SUSHI 0.X.0 for you Apple fans) contains the following enhancements and bug fixes:

• BREAKING CHANGE: Changes syntax for adding standalone extensions (details below) (#86, #182)
• Adds support for invariants (a.k.a. constraints) and obeys rule (details below)
• Adds support for Bring-Your-Own-JSON resources (details below) (#257)
• Improves alias resolution and adds support for $ prefix (details below) (#185)
• Adds support for indicating code system version in URLs using | (#252)
• Adds support for nested input folders containing FSH files (thanks for the contribution, @peturv!) (#239)
• Automatically sets extension to 0..0 in simple extensions and value[x] to 0..0 in complex extensions
• Copies ignoreWarnings.txt from ig-data/input to appropriate location in output (#267)
• Logs an error when a type is constrained out of a choice, but the profile also constrains other aspects of the now obsolete choice type (#210)
• Logs an error if a profile or extension from a dependency IG cannot be used because it does not provide snapshot elements (#248)
• Fixes crash when invalid syntax is used (#228)
• Fixes bug when applying fixed codes to instances (#194)
• Fixes bug that could cause non-extensions to be used where only extensions are valid (#83)
• Fixes bug that stripped template version from ig.ini (#268)
• Fixes bug that caused errors when nested extensions were set to 0..0 (232)
• Fixes bug finding children of contentReference slices

BREAKING CHANGE: New Extension Syntax

In previous releases, inline extensions and standalone extensions could be added using the following syntax:

* {extension path} contains {extensionName} {card} {flags}

If {extensionName} could be resolved to a standalone extension (i.e., an extension with its own StructureDefinition), then it was assumed that the user intended to specify that standalone extension. If it could not be resolved to a standalone extension, it was assumed that the user intended to define a new inline extension (i.e., an extension only defined inline inside another extension). This caused problems, however, when an author wanted to define an inline extension with a certain name, but that name happened to resolve to a standalone extension. It also allowed for a mistyped name (that should have referred to a standalone extension) to go undetected since it was just treated as an inline extension instead.

In SUSHI 0.10.0, inline extensions still use the same syntax as above. Authors who want to specify standalone extensions, however, must use the following new syntax:

* {extension path} contains {ExtensionNameIdOrURL} named {extensionSliceName} {card} {flags} 

For example, adding the US Core Race extension might look like this:

// Assumes the following is defined elsewhere in the file:
// Alias: USCoreRace = http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
* extension contains USCoreRace named race 0..1

IG authors will need to update their FSH files to use the new syntax where appropriate. To ease this transition, SUSHI 0.10.0 detects cases that likely need to be fixed and issues a warning with specific guidance. For more information on using extensions in FSH, see the FHIR Shorthand documentation.

Invariants and obeys Rule

SUSHI 0.10.0 adds support for defining invariants (or constraints) and applying them to elements in a profile or extension. Invariant definitions use the following keywords, which map to FHIR constraint properties as described:

FSH Invariant Keyword	FHIR Constraint Property
Invariant	key
Severity	severity
Description	human
Expression	expression
XPath	xpath

Once an Invariant is defined, it can be referenced by an obeys rule using the following syntax:

* {optional-path} obeys {invariant}

For example, US Core Patient contains an invariant that might be expressed like the following:

Invariant: us-core-8
Description: "Patient.name.given or Patient.name.family or both SHALL be present"
Expression: "family.exists() or given.exists()"
XPath: "f:given or f:family"
Severity: #error

and then used in a rule like so:

* name obeys us-core-8

Bring Your Own JSON

In some cases, IG authors may want to integrate externally authored artifacts into a FSH-based IG. This might happen when an author is slowly transitioning an existing IG to FSH, when and author prefers other tools for certain resource types (e.g., SearchParameters or examples), or if an author needs to override a FSH-generated resource for some reason.

SUSHI 0.10.0 supports Bring-Your-Own-JSON, a mechanism for allowing authors to provide their own JSON formatted IG artifacts and have SUSHI automatically add them to the IG it creates. These user-provided JSON resources are usable by FSH definitions and will be automatically added to the entries in the ImplementationGuide JSON file.

To use this feature, simply add JSON files to one of the supported subfolders in ig-data/input specified by Guidance for FHIR IG Creation:

• capabilities (for CapabilityStatements/Conformance resources)
• examples
• extensions
• models (for logical models)
• operations
• profiles
• resources (for anything/everything or whatever doesn't fit one of the other folders)
• vocabulary (for code systems & value sets)

Alias Resolution and $ Prefix

Some SUSHI users have expressed concern that typos in FSH aliases can go too easily undetected since SUSHI might just interpret them as a standard string. To address this, SUSHI now validates that aliases resolve to a URL wherever a URL would be expected.

In addition, authors who wish to be extra safe in their use of aliases can choose to name their aliases with a starting $. Since only aliases are allowed to start with $, SUSHI can easily identify uses of these aliases and validate that they do resolve to URLs, eliminating the possibility of typos going undetected. NOTE: Using $ as the starting character of alias names is optional. In addition, note that the $ is a part of the name -- it must exist in the alias definition as well as the alias uses.

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.9.1

SUSHI 0.9.1 contains the following minor enhancements and bug fixes:

• New approach to color-coding logged messages, providing better readability and contrast (#217)
• Fixes a bug that caused maintainer.url in package.json to be dropped when building the Implementation Guide JSON (#234)

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.9.0

SUSHI 0.9.0 contains the following features, enhancements, changes, and bug fixes:

• Exports results into type-specific folders (as defined in Using IG Templates)
  • Currently supports: profiles, extensions, vocabulary, and examples
• Generates StructureDefinitions without snapshot elements by default (#186)
  • This is the FHIR-recommended approach for providing input to the IG Publisher
  • This addresses several other bugs that were caused by providing snapshot data (#170, #128)
  • Users can keep the snapshot by using SUSHI with the -s or --snapshot flag
• Automatically applies value[x] 0..0 to complex extensions and extension 0..0 to simple extensions (#183)
  • Currently supported for top-level value[x] and extensions of named extensions (not inlined extensions)
• Adds support for code system URLs containing # by allowing authors to escape # (#180)
  • e.g., http://systems.org\#system1#my-code
• Fixes differential bug that didn't include slice names in sparse slice differentials (#204)
• Checks to ensure that fixed values aren't already fixed by a parent pattern (#84)
• Adds support for Description: keyword on Instances (descriptions are reflected in rendered IG pages)
• Allows authors to add extensions to instances even when the profile doesn't explicitly specify them (#188)
• Reports errors when instances do not provide required (1..1) values (#206)
• Allows authors to provide their own files in ig-data/input/includes (including menu.xml)
• Allows authors to force pages to be listed in a certain order by prefixing page names with a number and underscore
  • e.g., 1_MyFirstPage.md, 2_MySecondPage.md, etc.
• Changes the default index page title to: Home
• Uses the ig.ini properties copyrightyear and ballotstatus to populate the ImplementationGuide.definition.parameter values for copyrightyear and releaselabel
• Exits with a non-success code when there are errors (useful for CI)

NOTE: Implementation Guide configuration is still being designed and developed. Features specific to configuring or assembling Implementation Guide content are expected to change in future versions.

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.8.0

SUSHI 0.8.0 contains the following features, enhancements, and bug fixes:

• Adds supports for copying and configuring multiple pages, intros, notes, and images in ig-data
  • See README for details on page support and configuration
• Logs info messages to inform users of progress in SUSHI execution
• Automatically fixes the url value for extensions that are defined inline (#178)
• Fixes package resolution for current versions of packages (#201)
• Fixes support for paths containing contentReferences (e.g., item.item on Questionnaire) (#184)
• Fixes incorrect base differential element for profiles with no constraints (#198)

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.7.0

SUSHI 0.7.0 contains the following features, enhancements, and bug fixes:

• ValueSets and CodeSystems now support the caret (^) syntax for setting root-level metadata. E.g.,

  ValueSet: FreshWaterValueSet
  Description: "All fresh water fish"
  * ^publisher = "Fish Brothers"
  * ^status = #draft
  * ^experimental = true
  

• Applies pattern[x] constraints to generated instances (#160)
• Suppresses inherited invariants from IG documentation (#117)
• Fixes slice differentials to only specify what changed from the element that was sliced (#181)
• Fixes processing of multi-line strings using """ (#80)
• Fixes incorrect error message when package.json is corrupt (#177)

Install or Update

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

$ npm install -g fsh-sushi

SUSHI 0.6.3

SUSHI 0.6.3 contains the following minor enhancements and bug fixes:

• Defaults new Profile/Extension definitions to minimal set of high-level metadata (#157)
• Validates id and name values (#139)
  • id: any combination of upper- or lower-case ASCII letters ('A'..'Z', and 'a'..'z', numerals ('0'..'9'), '-' and '.', with a length limit of 64 characters: [A-Za-z0-9\-\.]{1,64}
  • name: should be usable as an identifier for the module by machine processing applications such as code generation: [A-Z]([A-Za-z0-9_]){0,254}
• Converts local CodeSystem names to URLs when used in concepts (#149)
• Minimizes xhtml strings to remove whitespace or other invalid characters (#147)
• Adds releaselabel and copyrightyear parameters to generated ImplementationGuide JSON to make IG Publisher happy (#166)
  • NOTE: These currently use default values but will be configurable in future versions
• Fixes redundant display of slice information in differential (#99)
• Fixes instance generation for slices from external profiles/extensions (#121)
• Fixes parsing of paths that contain a URL in square brackets (#151)
• Fixes parsing issues for files that don't end with a newline (#145)

Install or Update

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

$ npm install -g fsh-sushi