SUSHI 2.2.4

SUSHI 2.2.4 includes the following bug fixes and minor enhancements:

• Fix output paths for resources with path separators in their id (#990, #991) (details below)
• Fix canonical lookups for instances whose URL was set by an insert rule (#958, #985)
• Update dependency libraries to address known vulnerabilities (#992)

Output Paths and IDs

SUSHI generates file names based on the resource id (i.e., ${resourceType}-${resourceId}.json). In past versions of SUSHI, if the id contained one or more path separators, it was possible to cause SUSHI to write the JSON file to other locations on the filesystem. This behavior could be abused to intentionally overwrite existing JSON files. The utility of leveraging this bug, however, is limited by the fact that the file contents would still be a FHIR resource (i.e., you cannot force it to write arbitrary JSON). In this version of SUSHI, the bug has been fixed by properly sanitizing file names before writing them to disk.

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

SUSHI 2.2.3 includes the following bug fixes:

• Remove incorrect warnings about unused soft indices in rules (#978, #979)
• Correctly handle mixed case dependencies extracted from the IG resource (#980, #981)

These fixes are for bugs that were introduced in SUSHI 2.2.2. We apologize for the inconvenience!

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 2.2.2

SUSHI 2.2.2 includes the following bug fixes and minor improvements:

• Use package.json canonical when a package does not have an IG resource (#948, #966)
• Log an error when a modifier extension is used in a non-modifier extension array (and vice-versa) (#576, #960)
• Mirror slice base extensions in slices to accommodate validator (#932, #955)
• Improve handling of package name case insensitivity (#962, #912, #800)
• Fix handling of soft-indexing when used with indent rules (#973, #974)
• Fix package loading errors by no longer using HTTP HEAD method (#975)

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 2.2.1

SUSHI 2.2.1 includes the following bug fixes:

• Fixes failing to find element slices when other elements have the same slice name (#956, #957)
• Always fallback to packages2.fhir.org when a package doesn't exist at packages.fhir.org (#961, #965)
• Fix assignment of value 0 on Quantities (#947, #964)

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 2.2.0

SUSHI 2.2.0 includes the following enhancements and bug fixes:

• Allow authors to control if instances should serialize the meta.profile and/or id (#844) (details below)
• Allow authors to provide instances of logical models (#941) (details below)
• Allow authors to insert RuleSets at concept paths in CodeSystem definitions (#942)
• Allow authors to specify mappings for logical models and custom resources (#940)
• Allow authors to use string values for all ValueSet filter operators (#936)
• Provide more details and optional configurations in sushi --init config file (#944)
• Limited support for validating codes defined in local code systems (#595)
• Limited support for validating slicing logic in profiles (#885, #952)
• Clarify error message regarding attempts to "widen" cardinality (#943)
• Fix id generation bug on manually sliced choice elements (#927)
• Fix dependency loading bug for dependence with version "current" (#951)

Allow Authors to Control if Instances Should Serialize the meta.profile and/or id

By default, SUSHI always generates an instance id and the meta.profile property (for instances of profiles). Now authors can control this by specifying an instanceOptions configuration property in sushi-config.yaml. This configuration allows setMetaProfile and setId sub-properties.

The setMetaProfile value controls whether or not meta.profile is set on generated instances. It can have the following values:

• always: Set meta.profile for all Instances of profiles (default)
• never: Do not set meta.profile on any Instances
• inline-only: Set meta.profile for only Instances of profiles with Usage set to #inline
• standalone-only: Set meta.profile for only Instances of profiles where Usage is any value other than #inline

The setId value controls whether or not id is set on generated instances. It can have the following values:

• always: Set id for all Instances (default)
• standalone-only: Set id for only Instances where Usage is any value other than #inline

The setId flag can't have an inline-only or never option, because the IG Publisher requires ids for non-inline instances.

Allow Authors to Provide Instances of Logical Models

A recent version of the IG Publisher added support for including instances of logical models as binary resources. This feature was announced and discussed in a Logical Model Examples thread on chat.fhir.org. The basic steps an author needs to take in order to include logical model examples in a SUSHI project are:

1. Add the example to the input/resources or input/examples folder
   a. The file name of the example should be Binary-{id}.json or Binary-{id}.xml (substituting {id} for the real id)
2. Add an entry for the example in the sushi-config.yaml resources property
   a. Specify a name
   b. Specify exampleCanonical pointing to the canonical of your logical model
   c. Add an extension w/ the proper resource format (application/fhir+json or application/xml)

For example, given the following simple logical model definition in an IG w/ IG canonical root http://example.org:

Logical: MyLM
Id: MyLM
Title: "My LM"
Description: "This is mine"
* important 1..1 SU boolean "Is this resource important"

Create the file input/examples/Binary-my-logical-example.json:

{
  "resourceType": "MyLM",
  "id": "my-logical-example",
  "important": true
}

And add the following in your sushi-config.yaml:

resources:
  Binary/my-logical-example:
    extension:
      - url: http://hl7.org/fhir/StructureDefinition/implementationguide-resource-format
        valueCode: application/fhir+json
    name: Example of LM
    exampleCanonical: http://example.org/StructureDefinition/MyLM

This will result in your logical model example being listed and displayed as a proper example of the logical model.

NOTE: This does not allow/support using the Instance keyword for creating examples of logical models. Authors must created the example as raw JSON or XML. Support for the Instance keyword may come in future versions of SUSHI.

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 2.1.1

SUSHI 2.1.1 includes the following bug fix:

• Remove support for case-insensitive package names. This support was causing failures in the IG auto-build process. This will be added back in a later release. (#912, #800)

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 2.1.0

SUSHI 2.1.0 includes the following enhancements and bug fixes:

• Automatically populate url element on Usage: #definition Instances (#908, #791)
• Warn when a concept is included in a ValueSet more than once (#913, #832)
• Support case-insensitive package names (#912, #800) Reverted in 2.1.1 as this causes failures in the IG Publisher auto-build process
• Display source information when warning about ValueSet filter operand types (#922, #910)
• Support finding Usage: #definition Instances with InstanceOf: CodeSystem when resolving codes in FSH (#920, #801)
• Replace errors related to slice cardinality being greater than cardinality of the sliced element with a warning (#926, #918)
• Fix bug with validation of choice slices when validating cardinality of Instance elements (#916, #911)
• Update vulnerable dependencies (#917)

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 2.0.1

SUSHI 2.0.1 includes the following enhancements and bug fixes:

• Support downloading packages via https rather than http (#904)
• Support including version information in only rules on Canonical types (#898)
• Fix bug causing soft indexing to fail on indented rules which are not path rules (#907)
• Fix bugs in sushi --init causing IG Publisher to build with errors (#899)
• Fix bug causing duplicate detection to only work within a file (#900)
• Fix bug allowing duplicate concepts to be added to CodeSystem definitions via insert rules (#903)

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 2.0.0

This is the official, stable SUSHI 2.0.0 release, marking the end of the beta phase for SUSHI 2.0.0. This release fully implements FHIR Shorthand v1.2.0; introducing significant new features, bug fixes, and several breaking changes.

Rule Indentation for Succinct Specification of Subpaths

Indentation can now be used to provide a more succinct visual representation of rules with nested paths. When one rule is indented below another, the full path of the indented rule or rules is obtained by prepending the path from the previous less-indented rule. For example:

* item[0]
  * linkId = "title"
  * type = #display
  * item[0]
    * linkId = "uniquearv_number"
    * type = #string
  * item[1]
    * linkId = "personal_info"
    * type = #group
* status = #active

is equivalent to the more repetitive FSH STU1 approach:

* item[0].linkId = "title"
* item[0].type = #display
* item[0].item[0].linkId = "uniquearv_number"
* item[0].item[0].type = #string
* item[0].item[1].linkId = "personal_info"
* item[0].item[1].type = #group
* status = #active

Using rule indentation is optional. Authors can continue using the longer path form if desired. Existing users should note, however, that this feature assigns meaning to whitespace before the * in rules. Prior to SUSHI 2.0.0, whitespace before the * was insignificant. Existing projects that have arbitrary whitespace before * or put multiple rules on the same line will likely experience errors when running SUSHI 2.0.0. These errors can be fixed by removing unnecessary whitespace before * where needed.

See the following section from the current build FSH specification for additional details:

• Indented Rules

Logical Models and Custom Resources

Logical models can be defined with the Logical keyword and the optional Parent, Id, Title, and Description keywords. The default parent for logical models is Base. Logical models are useful for representing arbitrary content, since a logical model supports adding elements, unlike profiles and extensions. Elements are added via AddElement rules. These rules specify a path, cardinality, optional flags, type(s), short definition, and optional long definition. For example:

* email 0..* SU string "The person's email addresses" "Email addresses by which the person may be contacted." 

The following demonstrates how logical models could be used to represent a human and their family (also using the optional rule indentation described above):

Logical:        Human
Title:          "Human Being"
Description:    "A member of the Homo sapien species."
* name 0..* SU HumanName "Name(s) of the human" "The names by which the human is or has been known"
* birthDate 0..1 SU dateTime "The date of birth, if known"
    "The date on which the person was born. Approximations may be used if exact date is unknown."
* deceased[x] 0..1 SU boolean or dateTime or Age "Indication if the human is deceased"
    "An indication if the human has died. Boolean should not be used if date or age at death are known."
* family 0..1 BackboneElement "Family" "Members of the human's immediate family."
  * mother 0..2 FamilyMember "Mother" "Biological mother, current adoptive mother, or both."
  * father 0..2 FamilyMember "Father" "Biological father, current adoptive father, or both."
  * sibling 0..* FamilyMember "Sibling" "Other children of the human's mother and/or father."

Logical:        FamilyMember
Title:          "Family Member"
Description:    "A reference to a human's family member."
* human 1..1 SU Reference(Human) "Family member" "A reference to the human family member"
* biological 0..1 boolean "Biologically related?"
      "A family member may not be biologically related due to adoption, blended families, etc."

Custom resources are defined much like logical models, but use the Resource keyword rather than Logical. The default parent for resources is DomainResource.

See the following sections from the current build FSH specification for additional details:

• Defining Logical Models
• Defining Resources
• AddElement Rules

NOTE: The SUSHI team would like to thank Joe Paquette and athenahealth for implementing this feature in SUSHI. Their quality contribution and teamwork has greatly improved SUSHI and allowed the SUSHI team to focus on many of the other proposed FSH STU2 features found in this release. Thank you, Joe and athenahealth!

Hierarchical CodeSystems and Concept-Specific Caret Rules

Concepts in a CodeSystem can now be defined in a hierarchical structure. To define such concepts, list all of the preceding codes in the hierarchy before the new code:

* #{parent code} "{display string}" "{definition string}"
* #{parent code} #{child code} "{display string}" "{definition string}"

This can also be accomplished with indentation:

* #{parent code} "{display string}" "{definition string}"
  * #{child code} "{display string}" "{definition string}"

In addition, authors can now use caret (^) rules on specific concepts to set metadata elements, such as designation and property. For example:

#rash ^designation.use = SCT#900000000000013009 "Synonym"

See the following sections from the current build FSH specification for additional details:

• Defining Code Systems
• Caret Paths

Option to Output Preprocessed FSH

The -p or --preprocessed flag can be used to to create a _preprocessed folder in a SUSHI project. This folder contains representations of the input FSH after several preprocessing steps have taken place. These steps include resolution of Alias values, insertion of RuleSet rules, and resolution of soft indexing. This representation can be useful for investigating errors from SUSHI or other tools. For example, the following FSH:

Alias: CAT = http://hl7.org/fhir/ValueSet/observation-category

Profile: ObservationProfile
Parent: Observation
* insert Metadata
* category from CAT (required)

RuleSet: Metadata
* ^version = "1.2.3"
* ^publisher = "Example publisher"

Instance: PatientInstance
InstanceOf: Patient
* name.given[+] = "John"
* name.given[+] = "Q"

results in the following preprocessed output:

Alias: CAT = http://hl7.org/fhir/ValueSet/observation-category

// Originally defined on lines 3 - 6
Profile: ObservationProfile
Parent: Observation
Id: ObservationProfile
* ^version = "1.2.3"
* ^publisher = "Example publisher"
* category from http://hl7.org/fhir/ValueSet/observation-category (required)

// Originally defined on lines 12 - 15
Instance: PatientInstance
InstanceOf: Patient
Usage: #example
* name.given[0] = "John"
* name.given[1] = "Q"

See the following section from the FSH School SUSHI documentation for additional details:

• Preprocessed FSH

Extensions for Representing Elements From Other Versions of FHIR

The FHIR specification defines behavior for a feature they refer to as extensions for converting between versions (also known as "implied extensions"). This feature allows authors to represent specific elements from past and future versions of FHIR using a specific extension URL format (as described in the spec linked above). These extensions are not available in any physical package, but rather, are understood and processed conceptually.

To use this feature in SUSHI, authors must specify a dependency on a package using an id and version of the form hl7.fhir.extensions.<extension-version>: <package-version>, where valid extension-versions are r2, r3, r4, and r5. As an example, if an author wanted to represent the Patient.animal.species element as defined in STU3, the dependencies should be specified as:

  dependencies:
    hl7.fhir.extensions.r3: 4.0.1

An author can then reference the extension using a URL following the format defined in the FHIR specification linked above. For example, the extension referring to the R3 Patient.animal.species element would be: http://hl7.org/fhir/3.0/StructureDefinition/extension-Patient.animal.species.

See the following documentation for additional details:

• Dependencies from the FSH School SUSHI documentation
• Extensions for Converting Between Versions from the current build FHIR specification

Extension for Profiling BackboneElements

The profile-element extension can be used to profile a BackboneElement by pointing at another BackboneElement defined elsewhere. This is typically used to indicate that constraints on the target of a contentReference should be applied to all the references as well. For example, t...

SUSHI 2.0.0 Beta 3

SUSHI 2.0.0-beta.3 is the third beta release for SUSHI 2.0.0. It contains the following enhancements and bug fixes:

• Updates rule indentation to require that the first rule that sets context be aligned to the left of the document, with no preceding whitespace. Therefore, the first rule in a FSH entity must have no whitespace preceding it and only rules that are indented to use a previous rule's context can have leading whitespace. (#874)
• Supports creating Profiles of LogicalModels (#857)
• Supports loading predefined resources from nested folders within the IG template supported input folders (#786)
• Adds support for checking the type of a StructureDefinition when assigning a value using the Canonical keyword (#870)
• Properly sets context on rules with no path (such as a caret (^) paths) and on rules that use the . path (#866, #887)
  • Note: The . path is only allowed on top-level rules and cannot be indented
• Fixes a bug to avoid changing the cardinality of optional slices when a value is assigned (#878)
• Fixes a bug to allow aliases to be assigned to URLs with fragments (#872)

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

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 2.0.0 Beta Releases in the Auto Build

The autobuild environment uses the latest stable version of SUSHI. To force the IG Publisher to use SUSHI 2.0.0-beta.3 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=2.0.0-beta.3