fsh-sushi 0.10.0

SUSHI 0.10.0

on Node.js NPM

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:

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