Configuration

Description of the configuration options that may be set in sushi-config.yaml

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 -

FSH Only: Minimum Configuration

If an author does not have an ImplementationGuide resource, and wants SUSHI to build FHIR definition files and not to do any additional IG processing, the author should create a sushi-config.yaml with the keys FSHOnly (with value true), canonical, and fhirVersion. For example:

FSHOnly: true
fhirVersion: 4.0.1
canonical: http://hl7.org/fhir/us/example

The sushi-config.yaml file should be located in the project’s root folder.

FSH Only: Existing ImplementationGuide Resource

If an author wants SUSHI only to build the FHIR definition files and not to do any additional IG processing, AND the project contains an ImplementationGuide resource, then the author does not need to provide a sushi-config.yaml file. If there is no sushi-config.yaml file, SUSHI will attempt to extract the following information from the ImplementationGuide resource:

  • id
  • canonical
  • url
  • name
  • packageId
  • fhirVersion
  • version
  • dependencies
  • parameters

SUSHI will then run in FSHOnly mode to produce FHIR definition files only.

To locate the ImplementationGuide resource, SUSHI assumes the project structure required by the template-based IG Publisher, and uses the following approach:

  • Look for <root>/ig.ini, where <root> is the folder containing the input folder. If the ig.ini file exists, it will have an ig 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.

FSH and IG Processing: Minimum Configuration

If the author wants SUSHI to do additional Implementation Guide (IG) processing, then the sushi-config.yaml file must provide some metadata values for the FSH project. Here is an example of a minimal configuration:

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 and canonical 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, not http://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 be 4.0.0 or above.
  • releaseLabel is a text label with no fixed set of values that describes the status of the publication to users. Recommended best practices include the following values, optionally suffixed with Ballot:
    • ci-build
    • STU1, STU2, etc.
    • STU 1.1, STU 1.1.0, etc.
    • Normative 1, etc.
    • Informative 1, etc.

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

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. The typical format is:

dependencies:
  hl7.fhir.us.core: 3.1.0

In addition to standard version identifiers, the following three special versions are supported:

  • dev: indicates that the dependency should be loaded from the local FHIR cache
  • current: indicates that the dependency should be loaded from the last successful auto-build.
  • latest: indicates that the dependency should be loaded using the version tagged as latest on the package server.

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.

FSH and IG Processing: 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
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.
canonical N/A The canonical base URL to be used throughout the IG
contact contact As specified in the IG resource
contained contained As specified in the IG resource
copyright copyright As specified in the IG resource
copyrightLabel copyrightLabel As specified in the IG resource - Note: this is an R5 IG element
copyrightYear or copyrightyear N/A Used to add a copyrightyear parameter to IG.definition.parameter
date date As specified in the IG resource
definition
└ extension
definition.extension A list of extensions that apply to IG.definition. Note: the only property supported on the definition property is extension.
description description 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, version, and extension. For R5 IG resources, the key reason can also be provided.
experimental experimental As specified in the IG resource
extension extension As specified in the IG resource
fhirVersion fhirVersion As specified in the IG resource. SUSHI supports FHIR versions in the R4 or R5 sequences, as given in the FHIR Publication History. 5.0.0-snapshot1. Projects that wish to use a 5.0.0 pre-release can specify the version in their sushi-config.yaml file, e.g., fhirVersion: 5.0.0-snapshot1.
FSHOnly N/A When this flag is set to true, no IG-specific content will be generate. SUSHI will only convert FSH definitions to JSON files. The author at least needs to provide a canonical and fhirVersion for FSHOnly processing to succeed. When FSHOnly is false or unspecified, IG content is generated.
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. See the Exhaustive Example for details.
id id As specified in the IG resource
implicitRules implicitRules As specified in the IG resource
instanceOptions N/A key: value pairs, where keys are setId, setMetaProfile, and manualSliceOrdering.
  • The setId value controls whether id is set on generated instances. Options are always (set id on all instances [the default]) or standalone-only (set id for instances where the Usage keyword is NOT #inline).
  • The setMetaProfile value controls whether meta.profile is set on generated instances. It can have the following values: always (set meta.profile for all instances [the default]), never (do not set meta.profile on any instances), inline-only (set meta.profile only for instances of profiles with Usage keyword set to #inline), or standalone-only (set meta.profile for instances where the Usage keyword is NOT #inline).
  • The manualSliceOrdering value controls whether slice ordering is determined exclusively by the order in which slices are referenced in an instance’s FSH rules. When this flag is set to true, manual ordering is enabled (see Manual Slice Ordering).
jurisdiction jurisdiction As specified in the IG resource
language language As specified in the IG resource
license license As specified in the IG resource
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. See the Exhaustive Example for details. Authors can provide their own menu.xml by removing this property and placing a menu.xml file in /input/includes.
meta meta As specified in the IG resource
modifierExtension modifierExtension As specified in the IG resource
name name As specified in the IG resource
packageId packageId As specified in the IG resource. If unspecified, defaults to id.
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. See the Exhaustive Example for details.
parameters definition.parameter Consists of key-value pairs where the keys are values of definition.parameter.code. For R5 IG resources, the key can be a FSH code that specifies the code and system values of definition.parameter.code, which is a Coding. See the Exhaustive Example for details. If a parameter allows repeating values, the value in the YAML may be a sequence/array. For example, the path-resource parameter specifies relative paths to additional folders that contain predefined resources (see Specifying Additional Resource Paths).
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
releaseLabel or releaselabel N/A Used to add a releaseLabel parameter to IG.definition.parameter
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.
status status As specified in the IG resource
templates definition.template As specified in the IG resource
text text As specified in the IG resource
title title As specified in the IG resource
url url As specified in the IG resource. If unspecified, defaults to {canonical}/ImplementationGuide/{id}.
useContext useContext As specified in the IG resource
version version As specified in the IG resource
versionAlgorithmString versionAlgorithm[x] As specified in the IG resource - Note: this is an R5 IG element
versionAlgorithmCoding versionAlgorithm[x] As specified in the IG resource - Note: this is an R5 IG element

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`.
# For R5 ImplementationGuides, the object can also have a key for `reason`.
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

# NOTE: All of the properties of IG.definition are abstracted to
# individual top-level configuration properties (below). This
# definition property should only be used to provide extensions
# that have a context of IG.definition.
definition:
  extension:
    - url: http://example.org/example/ig-definition-ext
      valueBoolean: true

# 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

# For R5 ImplementationGuides, the example[x] property was replaced
# with isExample. A profile property is also included. These can be
# specified directly in configuration. Profile can be a single item
# or an array.
# An example resources configuration for an R5 ImplementationGuide:
# resources:
#   Patient/my-example-patient:
#     name: My Example Patient
#     description: An example Patient
#     isExample: true
#     profile: http://example.org/fhir/StructureDefinition/my-patient-profile

# 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.
#
# For R5 ImplementationGuides, the IG.definition.page element now
# supports a source[x] element. SUSHI will generate sourceUrl
# based on the name if it is not provided. To provide a source,
# add a key/value pair subproperty with the type slice as the key.
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 R5 ImplementationGuide resource defines additional properties
# not represented above. These properties can be used as-is and
# should follow the format defined in ImplementationGuide:
# * copyrightLabel
# * versionAlgorithm[x], which should be specified with the type slice (e.g. versionAlgorithmString)

# 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 parameters
# defined by core FHIR see: http://build.fhir.org/codesystem-guide-parameter-code.html.
# For parameters defined by the FHIR Tools IG  see:
# http://build.fhir.org/ig/FHIR/fhir-tools-ig/branches/master/CodeSystem-ig-parameters.html
parameters:
  excludettl: true
  validation: [allow-any-extensions, no-broken-links]
  show-inherited-invariants: false

# For R5 ImplementationGuides, the IG.definition.parameter.code became a Coding.
# In this case, the YAML key becomes the code.code. If the code provided is in the
# value set bound in the IG definition (see: http://hl7.org/fhir/2022Sep/valueset-guide-parameter-code.html),
# that system is automatically set. If no system is provided, SUSHI will default the system
# to the system for the IG Parameter Codes
# (see: http://build.fhir.org/ig/FHIR/fhir-tools-ig/branches/master/CodeSystem-ig-parameters.html).
# To use a different system, the YAML key can be a FSH code.
# An example parameters configuration for an R5 ImplementationGuide:
# parameters:
#   generate-xml: true
#   validation: [allow-any-extensions, no-broken-links]
#   http://example.org/fhir/other-system#example: 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
  # When set to true, slices must be referred to by name and not only by a numeric index in order to be used
  # in an Instance's assignment rule. All slices appear in the order in which they are specified in FSH rules.
  manualSliceOrdering: true

Download Exhaustive Configuration Example