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 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.
  • Valid values for the releaseLabel include:
    • ci-build: the continuous integration build release (not stable)
    • draft: draft version
    • qa-preview: frozen snapshot for non-ballot feedback
    • ballot: frozen snapshot for ballot
    • trial-use: official release with ‘trial use’ status
    • release: official release for use
    • update: official release with ‘trial use’ status - posted as an un-balloted STU update
    • normative+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 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.

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.

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. 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 cache
  • current: 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


Last modified May 5, 2022: 2022 site updates (#60) (2e88c59)