Configuration
SUSHI is configured by a single sushi-config.yaml file. This file is written using YAML. Authors unfamiliar with YAML should note that:
- White space (new lines and indentation) is significant
- Information is presented in
key: value
pairs - Strings do not have to be quoted unless they contain reserved characters, such as colon (:)
- Arrays/sequences are created using
-
Minimum Configuration
At a minimum, the sushi-config.yaml file must provide a few high-level metadata values for the FSH project, if the author wishes for SUSHI to do additional Implementation Guide (IG) processing:
id: fhir.us.example
canonical: http://hl7.org/fhir/us/example
name: ExampleIG
status: draft
version: 0.1.0
fhirVersion: 4.0.1
copyrightYear: 2020+
releaseLabel: ci-build
Download Minimum Configuration Example
- For an official HL7 project, the
id
andcanonical
will typically be assigned by the FHIR Product Director. canonical
refers to the canonical base of the IG, not the canonical URL of the IG resource (e.g.,http://hl7.org/fhir/us/example
, nothttp://hl7.org/fhir/us/example/ImplementationGuide/fhir.us.example
).- Valid values for
status
include:draft
: The IG is still under development and is not yet considered to be ready for normal use.active
: The IG is ready for normal use.retired
: The IG has been withdrawn or superseded and should no longer be used.unknown
: It is not know which of the status values currently applies for the IG. This should be rare.
- Since SUSHI currently supports only FHIR R4 and R5, the
fhirVersion
should always be4.0.0
or above. - Valid values for the
releaseLabel
include:ci-build
: the continuous integration build release (not stable)draft
: draft versionqa-preview
: frozen snapshot for non-ballot feedbackballot
: frozen snapshot for ballottrial-use
: official release with ‘trial use’ statusrelease
: official release for useupdate
: official release with ‘trial use’ status - posted as an un-balloted STU updatenormative+trial-use
: official release with mixture of trial use and normative content
FSH-Only
If an author wants SUSHI only to build the FHIR definition files, and not to do any additional IG processing, and if the project contains an ImplementationGuide resource, then the author does not need to provide a sushi-config.yaml at all. If there is no sushi-config.yaml, SUSHI will automatically attempt to extract the following information from an ImplementationGuide resource:
id
canonical
url
name
packageId
fhirVersion
version
dependencies
parameters
SUSHI will then run in FSH-Only mode to produce FHIR definition files only.
When attempting to extract information from an ImplementationGuide resource, SUSHI assumes the project structure required by the template-based IG Publisher. The following approach is used to find the ImplementationGuide resource:
- Look for
<root>/ig.ini
, where<root>
is the folder containing the input folder. If the ig.ini file exists, it will have anig
property which gives the path to the ImplementationGuide resource, so SUSHI will use this path to find the resource. - If there is no ig.ini in the root folder, SUSHI will search the
<root>/input
folder for an ImplementationGuide resource, and if exactly one resource is found, SUSHI will extract the above properties from it.
If an author does not have an ImplementationGuide resource, but still wants SUSHI to build FHIR definition files only, the author should add a FSHOnly
flag to the sushi-config.yaml and set its value to true
:
FSHOnly: true
However, the author will also at least need to provide a canonical
and fhirVersion
in the configuration for FSH-Only processing to succeed.
Recommended Configuration
In addition to the minimum configuration requirements shown above, most IG authors will also want to provide a title
, description
, license
, publisher
, and dependencies
:
id: fhir.us.example
canonical: http://hl7.org/fhir/us/example
name: ExampleIG
title: "HL7 FHIR Implementation Guide: Example IG Release 1 - US Realm | STU1"
description: An example IG that exercises many of the fields in a SUSHI configuration
status: draft
license: CC0-1.0
version: 0.1.0
fhirVersion: 4.0.1
copyrightYear: 2020+
releaseLabel: ci-build
publisher:
name: HL7 International - US Realm Steering Committee
url: http://www.hl7.org/Special/committees/usrealm/index.cfm
email: usrsc@lists.HL7.org
dependencies:
hl7.fhir.us.core: 3.1.0
Download Recommended Configuration Example
Note
Thelicense
value should come from the SPDX Licence Value Set, although most FHIR IGs use the CC0-1.0
(Creative Commons Zero v1.0 Universal) license.
Dependencies
The dependencies
value is a YAML object for which the keys are each dependency’s package id and the values are the dependency versions. In addition to standard version identifiers, the following two special versions are supported:
dev
: indicates that the dependency should be loaded from the local FHIR cachecurrent
: indicates that the dependency should be loaded from the last successful auto-build.
The dependencies
property also supports an advanced syntax that allows you to directly specify the dependency id and/or URI if necessary. For example:
dependencies:
hl7.fhir.us.core:
id: uscore
uri: http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core
version: 3.1.0
SUSHI also supports extensions for converting between versions of FHIR. To get extensions that represent elements from other versions of FHIR, a package of the form hl7.fhir.extensions.<extension-version>:<package-version>
is used. The <extension-version>
should be one of r2
, r3
, or r4
to indicate which version of FHIR the element represented by the extension is defined in. The <package-version>
represents which version of FHIR the extension will be used in. For an IG defined using FHIR R4, this would be 4.0.1
. As an example, if an author wanted to represent the Patient.animal.species
element as defined in R3, 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
.
Full Configuration
The table below lists all configuration properties that can be used in SUSHI’s sushi-config.yaml file. Most SUSHI configuration properties come directly from the Implementation Guide resource and will be translated into the generated ImplementationGuide resource for your project. Differences between the sushi-config.yaml properties and ImplementationGuide properties are noted below.
Property | Corresponding IG element | Usage |
---|---|---|
id | id | As specified in the IG resource |
meta | meta | As specified in the IG resource |
implicitRules | implicitRules | As specified in the IG resource |
language | language | As specified in the IG resource |
text | text | As specified in the IG resource |
contained | contained | As specified in the IG resource |
extension | extension | As specified in the IG resource |
modifierExtension | modifierExtension | As specified in the IG resource |
url | url | As specified in the IG resource. If not specified, defaults to {canonical}/ImplementationGuide/{id} . |
version | version | As specified in the IG resource |
name | name | As specified in the IG resource |
title | title | As specified in the IG resource |
status | status | As specified in the IG resource |
experimental | experimental | As specified in the IG resource |
date | date | As specified in the IG resource |
publisher | publisher, with cardinality changed to 0..* | Publisher can be a single item or a list, each with a name and optional url and/or email. The first publisher’s name will be used as IG.publisher. The contact details and/or additional publishers will be translated into IG.contact values |
contact | contact | As specified in the IG resource |
description | description | As specified in the IG resource |
useContext | useContext | As specified in the IG resource |
jurisdiction | jurisdiction | As specified in the IG resource |
copyright | copyright | As specified in the IG resource |
packageId | packageI | As specified in the IG resource. If not specified, defaults to id . |
license | license | As specified in the IG resource |
fhirVersion | fhirVersion | As specified in the IG resource |
dependencies | dependsOn | A key: value pair, where key is the package id and value is the version (or dev /current ). For advanced use cases, the value can be an object with keys for id , uri and version . |
global | global | Key is the type and value is the profile |
groups | definition.grouping | A key: value pair, where key is the group id and value is the description of the group. For advanced use cases, the value can be an object with keys for name , description , and resources . |
resources | definition.resource | SUSHI can auto-generate a list of resources based on FSH definitions and provided JSON or XML resources, but this property can be used to add additional entries or override generated entries. SUSHI uses the {resource type}/{resource name} format as the YAML key (corresponding to IG.definition.resource.reference). Authors can specify the value “omit” to omit a FSH-generated resource from the resource list. groupingId can be used, but top-level groups syntax may be a better option. |
pages | definition.page | SUSHI can auto-generate pages, but authors can manage pages through this property. If this property is used, SUSHI will not generate any page entries. The YAML key is the file name containing the page. The title key-value pair provides the title for the page. If a title is not provided, then the title will be generated from the file name. If a generation value (corresponding to definition.page.generation) is not provided, it will be inferred from the file name extension. In the IG resource, pages can contain sub-pages; so in the config file, any sub-properties that are valid filenames with supported extensions (e.g., .md/.xml) will be treated as sub-pages. |
parameters | definition.parameter | The key is the code. If a parameter allows repeating values, the value in the YAML may be a sequence/array. |
templates | definition.template | As specified in the IG resource |
copyrightYear or copyrightyear | N/A | Used to add a copyrightyear parameter to IG.definition.parameter |
releaseLabel or releaselabel | N/A | Used to add a releaseLabel parameter to IG.definition.parameter |
canonical | N/A | The canonical base URL to be used throughout the IG |
menu | N/A | Used to generate the fsh-generated/includes/menu.xml file. The key is the menu item name and the value is the URL. Menus can contain sub-menus, but the IG Publisher currently only supports sub-menus one level deep. Authors can provide their own menu.xml by removing this property and placing a menu.xml file in /input/includes |
FSHOnly | N/A | When this flag is set to true , no IG specific content will be generated, SUSHI will only convert FSH definitions to JSON files. When false or unset, IG content is generated. |
applyExtensionMetadataToRoot | N/A | When set to true, the “short” and “definition” field on the root element of an Extension will be set to the “Title” and “Description” of that Extension. Default is true. |
instanceOptions | N/A | A key: value pair, where key can be setMetaProfile (options are always , never , inline-only , standalone-only ) or setId (options are always or standalone-only ). |
Exhaustive Example
The following provides an exhaustive example sushi-config.yaml covering many of the properties discussed above.
# This IG YML file is inspired by the ImplementationGuide resource
# and also draws from package.json, package-list.json, and ig.ini.
# That said, it is structured for ease-of-use, so it is not strictly
# conformant to any of those existing configuration formats.
# SUSHI will use id as both id and packageId in the IG unless a
# specific packageId is also provided in this file.
id: fhir.us.example
canonical: http://hl7.org/fhir/us/example
url: http://hl7.org/fhir/us/example/ImplementationGuide/fhir.us.example
name: ExampleIG
title: "HL7 FHIR Implementation Guide: Example IG Release 1 - US Realm | STU1"
description: Example IG exercises many of the fields in a SUSHI configuration.
status: active
license: CC0-1.0
date: 2020-02-26
version: 1.0.0
# Although fhirVersions is 0..* in the ImplementationGuide resource
# it can be a single item OR and array here (but so far SUSHI only
# supports 4.0.1 anyway).
fhirVersion: 4.0.1
# The following two lines correspond to items that used to be in
# ig.ini but were moved to IG.definition.parameter. For
# consistency within this file, the names are represented using
# camelcase, but if authors use the formal parameter names, SUSHI
# will recognize them as well. In either case, they'll be copied
# to the IG JSON using the formal names.
copyrightYear: 2019+
releaseLabel: STU1
# The publisher can be a single item or a list, each with a name and
# optional url and/or email. The first publisher's name will be used
# as IG.publisher. The contact details and/or additional publishers
# will be translated into IG.contact values.
publisher:
name: HL7 FHIR Management Group
url: http://www.hl7.org/Special/committees/fhirmg
email: fmg@lists.HL7.org
# Those who need more control or want to add additional details to the contact values can use
# contact directly and follow the format outlined in the ImplementationGuide resource and
# ContactDetail.
contact:
- name: Bob Smith
telecom:
- system: email
value: bobsmith@example.org
use: work
# The jurisdiction can be a single item or a list. The FHIR Shorthand
# code syntax can be used here.
jurisdiction: urn:iso:std:iso:3166#US "United States of America"
# The dependencies property corresponds to IG.dependsOn. The key is the
# package id and the value is the version (or dev/current). For advanced
# use cases, the value can be an object with keys for `uri` and `version`.
dependencies:
hl7.fhir.us.core: 3.1.0
hl7.fhir.us.mcode:
id: mcode
uri: http://hl7.org/fhir/us/mcode/ImplementationGuide/hl7.fhir.us.mcode
version: 1.0.0
# The global property corresponds to the IG.global property, but it
# uses the type as the YAML key and the profile as its value. Since
# FHIR does not explicitly disallow more than one profile per type,
# neither do we; the value can be a single profile URL or an array
# of profile URLs.
global:
Patient: http://example.org/fhir/StructureDefinition/my-patient-profile
Encounter: http://example.org/fhir/StructureDefinition/my-encounter-profile
# The resources property corresponds to IG.definition.resource.
# SUSHI can auto-generate all of the resource entries based on
# the FSH definitions and/or information in any user-provided
# JSON or XML resource files. If the generated entries are not
# sufficient or complete, however, the author can add entries
# here. If a generated entry matches the reference, it will
# not be added to SUSHI output. The format follows IG.definition.resource
# with the following differences:
# * use IG.definition.resource.reference.reference as the YAML key
# * specify "omit" to omit a FSH-generated resource from the
# resource list.
# * groupingId can be used, but top-level groups syntax may be a
# better option (see below).
# The following are simple examples to demonstrate what this might
# look like:
resources:
Patient/my-example-patient:
name: My Example Patient
description: An example Patient
exampleBoolean: true
Patient/bad-example: omit
# Groups can control certain aspects of the IG generation. The IG
# documentation recommends that authors use the default groups that
# are provided by the templating framework, but if authors want to
# use their own instead, they can use the mechanism below. This will
# create IG.definition.grouping entries and associate the individual
# resource entries with the corresponding groupIds.
groups:
GroupA:
name: Group A
description: The Alpha Group
resources:
- StructureDefinition/animal-patient
- StructureDefinition/arm-procedure
GroupB:
name: Group B
description: The Beta Group
resources:
- StructureDefinition/bark-control
- StructureDefinition/bee-sting
# The pages property corresponds to IG.definition.page. SUSHI can
# auto-generate the page list, but if the author includes pages in
# this file, it is assumed that the author will fully manage the
# pages section and SUSHI will not generate any page entries.
# The page file name is used as the key. If title is not provided,
# then the title will be generated from the file name. If a
# generation value is not provided, it will be inferred from the
# file name extension. Any subproperties that are valid filenames
# with supported extensions (e.g., .md/.xml) will be treated as
# sub-pages.
pages:
index.md:
title: Example Home
implementation.xml:
examples.xml:
title: Examples Overview
simpleExamples.xml:
complexExamples.xml:
# The ImplementationGuide resource defines several other properties
# not represented above. These properties can be used as-is and
# should follow the format defined in ImplementationGuide:
# * meta
# * implicitRules
# * language
# * text
# * contained
# * extension
# * modifierExtension
# * experimental
# * useContext
# * copyright
# * packageId
# The menu property will be used to generate the input/menu.xml file.
# The menu is represented as a simple structure where the YAML key
# is the menu item name and the value is the URL. The IG publisher
# currently only supports one level deep on sub-menus.
# To provide a custom menu.xml file, do not include this property and
# include a `menu.xml` file in input/includes.
menu:
Home: index.html
Artifacts:
Profiles: artifacts.html#2
Extensions: artifacts.html#3
Value Sets: artifacts.html#4
Downloads: downloads.html
History: http://hl7.org/fhir/us/example/history.html
# The parameters property represents IG.definition.parameter. Rather
# than a list of code/value pairs (as in the ImplementationGuide
# resource), the code is the YAML key. If a parameter allows repeating
# values, the value in the YAML should be a sequence/array. For a
# partial list of allowed parameters see:
# https://confluence.hl7.org/display/FHIR/Implementation+Guide+Parameters
parameters:
excludettl: true
validation: [allow-any-extensions, no-broken-links]
show-inherited-invariants: false
# The FSHOnly flag indicates if only FSH resources should be exported.
# If set to true, no IG related content will be generated.
# The default value for this property is false.
FSHOnly: false
# When set to true, the "short" and "definition" field on the root element of an Extension will
# be set to the "Title" and "Description" of that Extension. Default is true.
applyExtensionMetadataToRoot: false
# The instanceOptions property is used to configure certain aspects of how SUSHI processed instances.
# See the individual option definitions below for more detail.
instanceOptions:
# Determines for which types of Instances SUSHI will automatically set meta.profile
# if InstanceOf references a profile. Options are:
# - 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
setMetaProfile: always
# Determines for which types of Instances SUSHI will automatically set id
# if InstanceOf references a profile. Options are:
# - always: Set id for all Instances (default)
# - standalone-only: Set id for only Instances where Usage is any value other than #inline
setId: always
Download Exhaustive Configuration Example