Skip to content

SUSHI 3.0.0 Beta 1

Pre-release
Pre-release
Compare
Choose a tag to compare
@cmoesel cmoesel released this 11 Aug 02:06
· 53 commits to next since this release
v3.0.0-beta.1
3f28ad2
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.

SUSHI 3.0.0 Beta 1 is the first beta release for SUSHI 3.0. This release significantly changes SUSHI output in certain scenarios. It also requires a later version of Node.js. As such, this release is considered to have breaking changes.

SUSHI 3.0.0 Beta 1 Overview

SUSHI 3.0.0 Beta 1 introduces the following changes from the SUSHI 2.x releases:

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

NOTE: This is a beta release and may not be as stable as previous production releases. Additional beta releases with additional features and breaking changes are expected in the near future. Please be aware that functionality in this release is subject to change before the final release. We value user feedback, so please let us know your thoughts or concerns about this release.

SUSHI 3.0.0 Beta 1 Details

Require Node.js 16 or Node.js 18

Node.js 12 has reached its end-of-life and Node.js 14 is currently in its maintenance-only phase (see Node.js Releases). In order to ensure that SUSHI remains performant and secure, it now requires Node.js 16 (LTS) or 18 (Current). Although Node.js 12 (EOL) and 14 (Maintenance) currently work with this release of SUSHI, they are not officially supported (and may stop working in the future).

To download a more recent version of Node.js go to: https://nodejs.org/en/download/.

Do not use choice type renaming in element ids or paths

SUSHI 1.x and 2.x utilized an approach to choice types that simplified their element ids and paths. For example, Observation.value[x]:valueQuantity could be simplified to Observation.valueQuantity in the profile's differential and the IG Publisher would convert it to the "long form" during the snapshot generation process. This was referred to as choice type renaming.

While this was once considered an acceptable (and even recommended) approach, it is no longer considered good practice. In fact, in some cases this approach has caused problems in tooling and validation. As a result, SUSHI 3.0.0 no longer supports choice type renaming.

Consider the following rule on an Observation profile:

* valueQuantity MS

In SUSHI 2.x, this results in the following profile differential element:

{
  "id": "Observation.valueQuantity",
  "path": "Observation.valueQuantity",
  "min": 0,
  "max": "1",
  "type": [{ "code": "Quantity" }],
  "mustSupport": true
}

In SUSHI 3.0.0, this results in the following instead:

{
  "id": "Observation.value[x]:valueQuantity",
  "path": "Observation.value[x]",
  "sliceName": "valueQuantity",
  "min": 0,
  "max": "1",
  "type": [{ "code": "Quantity" }],
  "mustSupport": true
}

This provides a more consistent representation of choice type elements without changing their meaning.

Do not slice choice elements when they have been restricted to a single type

In SUSHI 2.x, whenever an author uses a type-specific path (such as valueCodeableConcept), it uses the standard type slicing mechanism to represent it. While this is necessary to distinguish types when there are multiple types to choose from, it is not necessary when a choice element has already been constrained to a single type.

For example, consider the following FSH definition:

Profile: MyObservation
Parent: Observation
* value[x] only CodeableConcept
* valueCodeableConcept from MyValueSet

Given the definition above, SUSHI 2.x will produce a differential that slices value[x] by type and introduces a specific choice type slice for valueCodeableConcept:

image

Given the same definition, SUSHI 3.0.0 will recognize that value[x] can only be a CodeableConcept and will simplify the differential by applying the constraint directly to value[x] instead of slicing it:

image

This maintains the intent of the profile while simplifying its representation by avoiding unnecessary slices when possible.

Note: If a choice element has already been sliced (i.e., by a parent profile), then SUSHI 3.0.0 will maintain consistency by using choice type slicing even if the choice element has already been reduced to a single type.

Automatically assign title and description for Instances that support them

To define conformance resources other than profiles, extensions, code systems, and value sets, authors must define an Instance of the resource. Although conformance resources often have a title and description, SUSHI 2.x requires authors to set those using assignment rules (e.g., * title = "My Operation Definition"), even when the author already specified a title using the Title: keyword.

In SUSHI 3.0.0, if an author specifies a Title: on an Instance, and that instance type supports a title element, SUSHI 3.0.0 will automatically assign the Title: keyword value to the instance's title element. Similarly, if an author specifies a Description: on an Instance, and that instance type supports a description element, SUSHI 3.0.0 will automatically assign the Description: keyword value to the instance's description element.

For example, consider the following FSH definition:

Instance: MyBlankConceptMap
InstanceOf: ConceptMap
Title: "My Blank ConceptMap"
Description: "A blank ConceptMap (for example purposes)."
Usage: #definition
* status = #draft

In SUSHI 2.x, the Title: and Description: values will be used for generating documentation in the IG, but the actual instance will not contain them:

{
  "resourceType": "ConceptMap",
  "id": "MyBlankConceptMap",
  "url": "http://example.org/ConceptMap/MyBlankConceptMap",
  "status": "draft"
}

In SUSHI 3.0.0, however, the Title: and Description: values will be automatically applied to the instance:

{
  "resourceType": "ConceptMap",
  "id": "MyBlankConceptMap",
  "url": "http://example.org/ConceptMap/MyBlankConceptMap",
  "title": "My Blank ConceptMap",
  "description": "A blank ConceptMap (for example purposes).",
  "status": "draft"
}

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 3.0.0 Beta 1 in the Auto Build

The autobuild environment uses the latest stable version of SUSHI. To force the IG Publisher to use SUSHI 3.0.0-beta.1 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=3.0.0-beta.1
Assets 2
Loading