Skip to content

SUSHI 2.0.0
Compare
Choose a tag to compare
@julianxcarter julianxcarter released this 10 Aug 18:30
· 314 commits to master since this release
v2.0.0
996509c
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

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:

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:

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:

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:

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:

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, the following snippet indicates the all recursive references to Questionnaire.item (e.g., Questionnaire.item.item) should conform to the same constraints as the original Questionnaire.item in this profile:

Profile: MyQuestionnaire
Parent: Questionnaire
* item ^type.profile = http://example.org/StructureDefinition/MyQuestionnaire
* item ^type.profile.extension.url = http://hl7.org/fhir/StructureDefinition/elementdefinition-profile-element
* item ^type.profile.extension.valueString = "Questionnaire.item"
// ...

See the following documentation for additional details:

Insert Rules with Paths

SUSHI now supports specifying a path before using an insert rule. The path that is specified is used throughout all rules in the RuleSet being applied. In the following example, we apply the NameRules RuleSet on the PatientProfile1 profile:

RuleSet: NameRules
* family MS
* given MS

Profile: PatientProfile1
Parent: Patient
* name insert NameRules

which is equivalent to the following profile definition:

Profile: EquivalentProfile
Parent: Patient
* name.family MS
* name.given MS

This also allows insert rules to be used on indented rules. The following profile PatientProfile2 is equivalent to the two profiles above:

Profile: Profile2
Parent: Patient
* name
  * insert NameRules

Specifying Warnings to Ignore

SUSHI now allows for users to specific warnings to ignore during processing; specified in an optional sushi-ignoreWarnings.txt file that must be placed either at the root of the project, or within the input directory. The contents of this file can only be used to ignore warnings, as errors and informational logs from SUSHI cannot be ignored.

Each line in the sushi-ignoreWarnings.txt file specifies warnings to ignore. Warnings will be ignored if they completely match the contents of any line in the sushi-ignoreWarnings.txt file. The warning to ignore must be specified on only one line, and the match is case-sensitive. Additionally, regular expressions can be specified in the sushi-ignoreWarnings.txt file. Each regular expression must be on only one line, and a regular expression is indicated by starting and ending the line with /. For example, if the sushi-ignoreWarnings.txt file was as follows:

Instance PatientExample1 is not an instance of a resource, so it should only be used inline on other instances, and it will not be exported to a standalone file. Specify "Usage: #inline" to remove this warning.
/Detected the following non-conformant Resource definitions.*/

Then any warning which exactly matches the contents of the first line will be ignored, and any warning which starts with the text Detected the following non-conformant Resource definitions will be ignored.

Note: SUSHI does log several multi-line warnings, but these warnings cannot be specified directly in the sushi-ignoreWarnings.txt file, since the warnings to ignore must be specified line-by-line. To ignore these warnings, a regular expression should be used.

Additional Changes

  • Adds support for mapping rules within rulesets (#886)
  • 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
  • Adds support for Binary Adjunct Files (#819)
  • Supports a code value in the Value Set Filter operators =, in, and not-in (#812)
    • NOTE: The use of a string values in the operators above is now deprecated
  • Adds support for Logical Models and Resources to constrain nested paths of elements they defined (#849)
  • Adds support for using FHIR R4B (4.1.0) as the FHIR version (#855)
  • Adds support for constraining a canonical type to a specific canonical using the Canonical keyword (#846)
    • NOTE: Support for constraining to a canonical w/ a specific version is not yet supported (see #863)
  • Adds a warning when a custom resource is defined using the Resource keyword which is not in the http://hl7.org/fhir/StructureDefinition domain (#842)

Bug Fixes

  • 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)
  • Fixes a bug so authors can specify a version when referencing a code from a FSH-defined CodeSystem (#816)
  • Fixes a bug related to setting caret paths on code systems codes in a RuleSet (#833)
  • Fixes a bug so that authors can set values on elements that are constrained to a choice of profiles (#794)
    • NOTE: In this case, it will be assigned using the base resource type and a warning will be logged
  • Fixes overly strict checks on assignments to items in an array (#821)
  • Fixes parser to allow more than two value set filters to be chained (#823)

Breaking Changes

  • Indent rules make whitespace before * significant. This may affect a small number of existing IGs.
  • Support for deprecated syntax has been removed (#817), including:
    • Mixins: keyword
    • units keyword
    • , path separator (replaced by and)
    • | type separator (replaced by or)
  • Support for limited ValueSet expansion (added in SUSHI 1.3.0) has been removed (#807)
  • Support for deprecated pre-SUSHI 1.0 project structures has been removed (#820)

All projects using SUSHI 2.0.0 must use the project structure described on the Project Structure section of FSH School. Old project structures will now fail with an error. For instructions on migrating from an old project structure, see FSH School's Migration documentation.

Full Documentation

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

Install or Update

To install or update to this version of SUSHI, 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

Using Previous SUSHI Releases in the Auto Build

The autobuild environment uses the latest stable version of SUSHI, and will now default to SUSHI 2.0.0. To force the IG Publisher to use SUSHI 1.3.2 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=1.3.2
Assets 2
Loading