fhir / sushi

SUSHI (aka "SUSHI Unshortens Short Hand Inputs") is a reference implementation command-line interpreter/compiler for FHIR Shorthand (FSH).

SUSHI

SUSHI (aka "SUSHI Unshortens Short Hand Inputs") is a reference implementation command-line interpreter/compiler for FHIR Shorthand (FSH).

FHIR Shorthand (FSH) is a specially-designed language for defining the content of FHIR Implementation Guides (IG). It is simple and compact, with tools to produce Fast Healthcare Interoperability Resources (FHIR) profiles, extensions and implementation guides (IG). Because it is a language, written in text statements, FHIR Shorthand encourages distributed, team-based development using conventional source code control tools such as GitHub.

For more information about the evolving FSH syntax see the FHIR Shorthand Reference Manual.

FHIR Foundation Project Statement

• Maintainers: This project is maintained by The MITRE Corporation.
• Issues / Discussion: For SUSHI issues, such as bug reports, comments, suggestions, questions, and feature requests, visit SUSHI GitHub Issues. For discussion of FHIR Shorthand and its associated projects, visit the FHIR Community Chat @ https://chat.fhir.org. The #shorthand stream is used for all FHIR Shorthand questions and discussion.
• License: All contributions to this project will be released under the Apache 2.0 License, and a copy of this license can be found in LICENSE.
• Contribution Policy: The SUSHI Contribution Policy can be found in CONTRIBUTING.md.
• Security Information: The SUSHI Security Information can be found in SECURITY.md.
• Compliance Information: SUSHI supports creating Implementation Guides for FHIR R4, FHIR R4B, and FHIR R5. While SUSHI performs basic validation to help users author FSH that will produce valid FHIR artifacts, it is not intended to be a full-featured validator. For example, SUSHI does validate paths and cardinalities, but does not validate author-provided FHIRPath expressions, terminological compliance, or slice membership. Authors are encouraged to use a full-featured validator, such as the one found in the IG Publisher, to test their final FHIR outputs. The SUSHI source code includes a comprehensive suite of unit tests to test SUSHI's own behavior and compliance with FHIR, which can be found in the test directory.

Installation for SUSHI Users

SUSHI requires Node.js to be installed on the user's system. Users should install Node.js 18. Although previous versions of Node.js may work, they are not officially supported.

Once Node.js is installed, run the following command to install or update SUSHI:

$ npm install -g fsh-sushi

After installation, the sushi commandline will be available on your path:

$ sushi help

Usage: sushi [options] [command]

Options:
  -v, --version                                        print SUSHI version
  -h, --help                                           display help for command

Commands:
  build [options] [path-to-fsh-project]                build a SUSHI project
  init [options] [name]                                initialize a SUSHI project
  update-dependencies [options] [path-to-fsh-project]  update FHIR packages in project configuration
  help [command]                                       display help for command

To build a SUSHI project, use the build command:

$ sushi build --help

Usage: sushi build [options] [path-to-fsh-project]

build a SUSHI project

Arguments:
  path-to-fsh-project      path to your FSH project (default: ".")

Options:
  -l, --log-level <level>  specify the level of log messages (default: "info") (choices: "error", "warn", "info", "debug")
  -o, --out <out>          the path to the output folder (default: "fsh-generated")
  -p, --preprocessed       output FSH produced by preprocessing steps
  -r, --require-latest     exit with error if this is not the latest version of SUSHI (default: false)
  -s, --snapshot           generate snapshot in Structure Definition output (default: false)
  -c, --config <config>    override elements in sushi-config.yaml (supported: 'version', 'status', 'releaselabel') (eg: --config status:draft)
  -h, --help               display help for command

See the SUSHI documentation for detailed information on using SUSHI.

IG Generation

SUSHI supports publishing implementation guides via the new template-based IG Publisher. The template-based publisher is still being developed by the FHIR community. See the Guidance for HL7 IG Creation for more details.

Based on the inputs in FSH files, sushi-config.yaml, and the IG project directory, SUSHI populates the output directory. See the documentation on IG Project with SUSHI for more information on using SUSHI to generate IGs.

Installation for Developers

SUSHI is a TypeScript project. At a minimum, SUSHI requires Node.js to build, test, and run the CLI. Developers should install Node.js 18.

Once Node.js is installed, run the following command from this project's root folder:

$ npm install

NPM tasks

The following NPM tasks are useful in development:

Task	Description
build	compiles src/**/*.ts files to dist/**/*.js files using the TypeScript compiler (tsc)
build:watch	similar to build but automatically builds when changes are detected in src files
build:grammar	builds the ANTLR grammar from 'antlr/src/main/antlr' to 'src/import/generated'
test	runs all unit tests using Jest
test:watch	similar to test, but automatically runs affected tests when changes are detected in src files
lint	checks all src files to ensure they follow project code styles and rules
lint:fix	fixes lint errors when automatic fixes are available for them
prettier	checks all src files to ensure they follow project formatting conventions
prettier:fix	fixes prettier errors by rewriting files using project formatting conventions
check	runs all the checks performed as part of ci (test, lint, prettier)
regression	runs regression against repositories found by FSHFinder
regression:last-year	runs regression against repositories found by FSHFinder updated in the last 365 days

To run any of these tasks, use npm run. For example:

$ npm run check

Regression

The regression/cli.ts script can be used to run regression on a set of repos. It's default command, run supports the following options:

Options:
  -a, --a <version>      Baseline version of SUSHI. Can be an NPM version number or tag, "gh:branch" to use a GitHub branch, or "local" to use the local code with
                         ts-node. (default: "gh:master")
  -b, --b <version>      Version of SUSHI under test. Can be an NPM version number or tag, "gh:branch" to use a GitHub branch, or "local" to use the local code with
                         ts-node. (default: "local")
  -l, --lookback <days>  The number of days to lookback in FSHFinder repositories (based on last updated date).
  -c, --count <number>   The maximum number of FSHFinder repositories to test (most recent first).
  -r, --repo <repos...>  One or more repos to test, each specified as a Github {org}/{repo}#{branch} (e.g., HL7/fhir-mCODE-ig#master). This option is not
                         compatible with the lookback, count, or file options.
  -f, --file <file>      A text file for which each line is a GitHub {org}/{repo}#{branch} to test (e.g., HL7/fhir-mCODE-ig#master). This is mostly used for legacy
                         purposes and is not compatible with the lookback, count, or repo arguments.
  -o, --output <folder>  The folder to write regression data to (default: "regression/output")
  -h, --help             display help for command

You can run it via ts-node:

$ ts-node regression/cli.ts run -a 3.0.0 -b local -c 50

You can also run it via npm by adding -- followed by the arguments you wish to pass:

$ npm run regression -- -l 30 -c 50

Another example specifying just two specific repositories to run regression on:

$ npm run regression -- --repo HL7/fhir-mCODE-ig#master HL7/davinci-crd#master

The regression script first installs the -a and -b SUSHIs to temporary folders (except for local, in which case it runs npm install on the local SUSHI). Then for each of the relevant repositories, it does the following:

1. Downloads the repo source from GitHub, creating two copies (for the base version of SUSHI and the version under test)
2. Runs the base version of SUSHI against one copy of the repo
3. Runs the version of SUSHI under test against the other copy of the repo
4. Compares the results and generates a report of the differences

When the script is complete, it will generate and launch a top-level index file with links to the reports and logs for each repo.

Recommended Development Environment

For the best experience, developers should use Visual Studio Code with the following plugins:

• ESLint
• Prettier - Code formatter
  • Consider configuring the formatOnSave feature in VS Code settings:

    "[typescript]": {
        "editor.formatOnSave": true
    }

• vscode-language-fsh

License

Copyright 2019-2022 Health Level Seven International

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

sushi's Issues

FHIR rules for name and id should be enforced

Currently SUSHI allows name and id to be any sequence of non-whitespace characters. FHIR, however, is more specific:

• name: [A-Z]([A-Za-z0-9_]){0,254} (http://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.name)
• id: [A-Za-z0-9\-\.]{1,64} (http://hl7.org/fhir/R4/datatypes.html#id)

We should probably catch names/ids that violate these rules and report them as errors in SUSHI. While we could update the ANTLR grammar to reflect these requirements, it might be more user-friendly to keep the grammar as-is and do the check in code. Grammar violations make ugly and sometimes-confusing error messages.

Using a URL explicitly in brackets fails

When you try to use a URL explicitly in a path, SUSHI fails to correctly resolve the path. As an example:

* extension[http://hl7.org/fhir/us/fsh/StructureDefinition/us-core-race].url = "foo"

will fail. However, using an alias for the same URL works:

Alias: USCoreRace = http://hl7.org/fhir/us/fsh/StructureDefinition/us-core-race]
* extension[USCoreRace].url = "foo"

This is likely to do with how we split up paths. We split paths based on periods, and the URL contains periods.

Codes are not passing validation

The IG Publisher is reporting an error validating certain codes.

You can see this error in the QA report when you run the IG Pub.

Example -- on master branch, at commit standardhealth/fsh-mcode@4948b6e

Instance: build\input\resources\Condition-mCODEComorbidConditionExample01.json. Here's how the relevant bit of the resource looks:

  "id": "mCODEComorbidConditionExample01",
  "clinicalStatus": {
    "coding": [
      {
        "code": "active"
      }
    ]
  },

Here's the resulting error message:

Condition/mCODEComorbidConditionExample01: Condition.clinicalStatus | error | None of the codes provided are in the value set http://hl7.org/fhir/ValueSet/condition-clinical\|4.0.1 (http://hl7.org/fhir/ValueSet/condition-clinical, and a code from this value set is required) (codes = null#active) (see Tx log)

Here's the relevant part of the Terminology Log:

<?xml version="1.0" encoding="UTF-8"?><Parameters xmlns="http://hl7.org/fhir"><parameter><name value="codeableConcept"/><valueCodeableConcept><coding><code value="active"/></coding></valueCodeableConcept></parameter><parameter><name value="valueSetMode"/><valueString value="CHECK_MEMERSHIP_ONLY"/></parameter><parameter><name value="valueSet"/><resource><ValueSet><id value="condition-clinical"/><meta><lastUpdated value="2019-10-31T18:29:23.356-04:00"/><profile value="http://hl7.org/fhir/StructureDefinition/shareablevalueset"/></meta><extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-wg"><valueCode value="pc"/></extension><extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status"><valueCode value="trial-use"/></extension><extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm"><valueInteger value="3"/></extension><url value="http://hl7.org/fhir/ValueSet/condition-clinical"/><identifier><system value="urn:ietf:rfc:3986"/><value value="urn:oid:2.16.840.1.113883.4.642.3.164"/></identifier><version value="4.0.1"/><name value="ConditionClinicalStatusCodes"/><title value="Condition Clinical Status Codes"/><status value="draft"/><experimental value="false"/><date value="2019-10-31T18:29:23-04:00"/><publisher value="FHIR Project team"/><contact><telecom><system value="url"/><value value="http://hl7.org/fhir"/></telecom></contact><description value="Preferred value set for Condition Clinical Status."/><immutable value="true"/><compose><include><system value="http://terminology.hl7.org/CodeSystem/condition-clinical"/></include></compose></ValueSet></resource></parameter><parameter><name value="profile"/><resource><Parameters><parameter><name value="profile-url"/><valueString value="dc8fd4bc-091a-424a-8a3b-6198ef146891"/></parameter></Parameters></resource></parameter></Parameters>

Conflicting Aliases are not reported

If an author defines the same Alias with two different values, only one of them will be used -- but there is no error indicating what happened. We should log an error when we encounter a duplicate Alias definition with a different value than the previous one.

This came up in fsh-mcode. In CodeSystemAliases.fsh, it had:

Alias:   USCoreRace = http://hl7.org/fhir/us/core/ValueSet/omb-race-category

But in USCoreAliases and Examples.fsh, it had:

Alias:   USCoreRace = http://hl7.org/fhir/us/core/StructureDefinition/us-core-race

I noticed this when reviewing this line in Examples.fsh, where the same alias is used twice: once to replace an Extension URL and once to replace a VS URL:

* extension[USCoreRace].extension[ombCategory].valueCoding = USCoreRace#2186-5 "Not Hispanic or Latino"

Entire IG generated to build/input/resources

If an ig-data folder exists (indicating you want to build an IG), then the entire IG gets generated to build/input/resources instead of just to build. This was introduced when we changed the default output folder to build/input/resources.

We need to change the default folder back to build and then update the export to always export the resources to ${outDir}/input/resources.

Unable to set the .text element

These lines:

• ^text.status = #additional
• ^text.div = "<div xmlns="http://www.w3.org/1999/xhtml\">text"

result in this error:

error: Cannot fix string value:

text

. Value does not match element type: xhtml
File: /Users/davidhay/IG/registry/shorthand/profile-HpiPractitioner.fsh
Line: 8

Sushi 0.6.0 should put generated SDs and other artifacts in /build/input/resources by default

When no ig-data directory is present, SUSHI 0.6.0 puts the generated artifacts directly into the /build directory. The IG publisher can't find them there. The artifacts need to always go in /build/input/resources directory.

The workaround is to use the -o /build/input/resources option.

Note: This only happens when the ig-data directory does not exist, but that is a significant use case for when IG customizations are to be preserved.

When profiling a reference, targetProfile is not set correctly in slices (High Priority)

When profiling a reference, targetProfile is not set correctly in slices. An example is the profile TNMPathologicalStageGroup in which we profile hasMember. The targetProfile is Observation when it should be the URL of the profile, i.e., TNMPathologicalRegionalNodesCategory. Here's the way the code is inside the slice:

"type" : [
          {
            "code" : "Reference",
            "targetProfile" : [
              "http://hl7.org/fhir/StructureDefinition/Observation"
            ]
          }
        ],

and here's what I think it should be is:

"type" : [
          {
            "code" : "Reference",
            "targetProfile" : [
            "http://hl7.org/fhir/us/mcode/StructureDefinition/TNMPathologicalRegionalNodesCategory"
            ]
          }
        ],

This might be the source of a bunch of slicing issues we've been seeing, so I'm anxious to have it resolved.

Slicing anomaly in instance of US Core Organization

There something wrong with the attached example.

Organization-mCODEOrganizationExample01.json.txt

The IG Publisher complains that:

Practitioner | error | Unrecognised property '@identifier:NPI'

Here's the FSH - it is pretty straightforward:

Instance: mCODEOrganizationExample01
InstanceOf: USCoreOrganization
* id = "mCODEOrganizationExample01"
* identifier[NPI].value = "1265714091"
* active = true
* name = "Foundation Medicine"
* contact.telecom.system = #phone
* contact.telecom.value = "617-418-2200"
* address.line = "150 Second Street"
* address.city = "Cambridge"
* address.state = "MA"
* address.postalCode = "02141"
* address.country = "USA"

VHDir dependency not properly copied into ImplementationGuide JSON

If this dependency is put in the package.json:

    "hl7.fhir.uv.vhdir":"current"

the generated ImplementationGuide is missing it. It should include:

    {
      "uri": "http://hl7.org/fhir/uv/vhdir/ImplementationGuide/hl7.core.uv.vhdir",
      "packageId": "hl7.fhir.uv.vhdir",
      "version": "current"
    }

Pattern in StructureDefinition not reflected in Instance

mCODE's CancerGenomicsReport profile has a fixed code (implemented via a pattern) on category. There is an instance example of this class named mCODECancerGenomicsReportExample01. The instance doesn't have the category it should have inherited from its structure definition it is an InstanceOf. This results in an (accurate) IG Pub error:
Profile http://hl7.org/fhir/us/mcode/StructureDefinition/CancerGenomicsReport, Element 'DiagnosticReport.category': minimum required = 1, but only found 0

Multi-line descriptions are corrupted in SD

New line and and carriage return characters are being inserted at strange spots in descriptions. The FSH source code in PrimaryCancerCondition. Example from fsh-mcode:

Here's the FSH:

Description: """
Records the history of the primary cancer condition, the original or first tumor in the body (Definition from: NCI Dictionary of Cancer Terms). Cancers that are not clearly secondary (i.e., of uncertain origin or behavior) should be documented as primary.

Cancer staging information summarized in this profile should reflect the most recent staging assessment on the patient, and should be updated if and when there is a new staging assessment. Past staging assessments will be preserved in instances of the TNMClinicalStageGroup and/or TNMPathologicalStageGroup, which refer back to PrimaryCancerCondition.

Conformance note: For the code attribute, to be compliant with US Core Profiles, SNOMED CT must be used unless there is no suitable code, in which case ICD-10-CM can be used.
"""

and here's the resulting description field in SD. Note the \n and \r characters and trucations:

"description": "\necords the history of the primary cancer condition, the original or first tumor in the body (Definition from: NCI Dictionary of Cancer Terms). Cancers that are not clearly secondary (i.e., of uncertain origin or behavior) should be documented as primary.\r\n\nancer staging information summarized in this profile should reflect the most recent staging assessment on the patient, and should be updated if and when there is a new staging assessment. Past staging assessments will be preserved in instances of the TNMClinicalStageGroup and/or TNMPathologicalStageGroup, which refer back to PrimaryCancerCondition.\r\n\nonformance note: For the code attribute, to be compliant with US Core Profiles, SNOMED CT must be used unless there is no suitable code, in which case ICD-10-CM can be used.\r",

Single-line comment error

SUSHI flags an error on this line:
Parent: Observation //USCoreObservationLab

But it is OK with this line:
Parent: Observation // USCoreObservationLab

The only difference is the space after //. The space should not be necessary.

Comment on the last line of a FSH file causes an error

If the last line of a FSH file is a comment or if the last line ends with an inline comment, the following error is reported:

error: extraneous input '//' expecting {<EOF>, KW_ALIAS, KW_PROFILE, KW_EXTENSION, KW_INSTANCE, KW_INVARIANT, KW_VALUESET, KW_CODESYSTEM}

This may be related to the fix for #130 because I did not see this issue prior the the PR that addressed that bug.

Example FSH files that will report that error:

Instance: Example
InstanceOf: Patient
// Comment

Instance: Example
InstanceOf: Patient // Comment

Validating extensions during instance generation

If you add an extension to an instance, sushi doesn;'t validate that the extension instance data is compliant with the extension definition

Error on instance generation setting extensions to fixed values

In instances, setting extensions seems to work in SUSHI, but something in the generated resource causes IG Publisher to crash. The offending lines seems to follow the same pattern, e.g.:

* extension[TreatmentIntent].valueCodeableConcept = SCT#373808002 "Curative - procedure intent"

* extension[RadiationDose].extension[TotalRadiationDoseDelivered].valueQuantity = UCUM#cGy

* extension[USCoreBirthSex] = GENDER#F

See examples.fsh for commented-out lines where this error occurs.

This error was "silent" in SUSHI, but only because apparent when the IG Publisher died -- hence, very hard to diagnose and pin down. This makes it a high priority to fix.

FHIR IG Publisher chokes on profiles/extensions w/ no differential elements

Apparently the publisher requires at least one differential element, so profiles/extensions w/ no rules cause errors in the publisher. To get around this, we should check if differential is empty after export. If so, we should toss in a single element representing the base. For example, on a profile of Observation, we'd just have:

"differential": {
  "element": [{
    "id": "Observation"
    "path": "Observation"
  }]
}

SUSHI should validate that names and IDs are unique

Within an IG / FSH Tank, names and ids should be unique. Technically I think that uniqueness is only required per type by FHIR (e.g., you could have a profile and extension w/ the same name) --- but for now I think we should be more stringent in FSH. I'm not sure SUSHI would handle duplicate names/ids well, even if they were for different types.

So, SUSHI should issue an error when encountering definitions that introduce a name or id that has already been used in the FSHTank.

Intensional Value Sets not expanding

FHIR is not able to expand value sets defined by filter rules. Look at the HistologyMorphologyBehaviorVS in the current master branch, and compare to
http://build.fhir.org/ig/HL7/fhir-mCODE-ig/branches/master/ValueSet-onco-core-HistologyMorphologyBehaviorVS.html
I'm not sure if the problem is in the rule definitions, or the way we are producing the value sets. Here are the rules as the currently are written:

ValueSet:   HistologyMorphologyBehaviorVS
Title: "Histology Morphology Behavior Value Set"
Description: "Codes representing etc..."
* codes from system SCT where concept is-a #367651003 "Malignant neoplasm of primary, secondary, or uncertain origin (morphologic abnormality)"
* codes from system SCT where concept is-a #399919001 "Carcinoma in situ - category (morphologic abnormality)"
* codes from system SCT where
    concept is-a #399983006 "In situ adenomatous neoplasm - category (morphologic abnormality)" and
    concept is-not-a #450893003 "Papillary neoplasm, pancreatobiliary-type, with high grade intraepithelial neoplasia (morphologic abnormality)" and
    concept is-not-a #128640002 "Glandular intraepithelial neoplasia, grade III (morphologic abnormality)" and
    concept is-not-a #450890000 "Glandular intraepithelial neoplasia, low grade (morphologic abnormality)" and
    concept is-not-a #703548001 "Endometrioid intraepithelial neoplasia (morphologic abnormality)"
* SCT#399878004 "Malignant neoplasm with pilar differentiation (morphologic abnormality)"

Fixed codes don't account for parent elements w/ pattern[x]

Currently, when the user tries to fix a value, we check the Structure Definition to see if that value has already been set on the element by a pattern or fixed field. However, the pattern field can be used to specify which values children of the element must have. We do not account for this. For example, if Patient.maritalStatus has a field like:

"patternCodeableConcept": {
  "coding": [
    { "code": "foo" }
  ]
}

We currently still allow the user to re-fix the value of Patient.maritalStatus.coding[0].code. This behavior is incorrect, and should be fixed to not allow this value to be fixed to something other than "foo"

Block comments on a single line cause syntax errors

Block comments are typically meant to be used as multi-line comments, such as this:

/*
Comment
Comment
/*

Using a block comment on a single line like below causes a syntax error:

/* Comment Comment */

Although it is unlikely that this will be an issue, since we have support natively for single-line comment syntax with //, this is an unintended error and should be resolved.

Aliases are limited

If you define Alias: systemCPN = example.com, then you can use that alias in some places, but not others. For example, you could use the alias in a code, like someCode#systemCPN, but you could not use the alias when fixing a value, * identifier[0].system = systemCPN. It may be better to expand the usefulness of aliases by allowing them to appear in more places.

Choice slices are named repetitively in differential

When a choice is constrained to a single type, this is represented by slicing the choice. But to simplify things, this is represented in the differential using just the type of the sliced element, as shown below:

When we represent this, we do not create just a single element, and we leave the slicing visible on the differential:

Instead of showing value[x] sliced by the element called valueCodeableConcept:valueCodeableConcept, we want to just have one single element called valueCodeableConcept, as the FHIR example has one single valueQuantity element.

Set properties on instance from pattern[x] on parent element

When we create an instance, we copy over fixed and pattern values from the Structure Definition onto the instance. However, if an element's value is set by a pattern on that element's parent, the element does not get fixed, because we only account for fixed values that are directly on the element, not for pattern values that may be present on parents of the element. As an example, see the below:

* identifier[NPI].value = "1265714091"
// workaround for https://github.com/FHIR/sushi/issues/148: "Pattern in StructureDefinition not reflected in Instance" opened 1-25-2020 by MK
* identifier[NPI].system = "http://hl7.org/fhir/sid/us-npi"   // although URI is not a supported type in FSH yet, apparently you can get away with giving the URI as a string, and the json comes out correctly.

If we remove the workaround (i.e., delete the line fixing the system) then the system doesn't get set in the example at all:

  "identifier": [
    {
      "value": "1265714091"
    }
  ],

Although indentifier[NPI] slice is 0..1, identifier[NPI].system is 1..1 -- so according to our basic rules, it should be set since we're going to identifier[NPI] to set the value. The system element needs to not only be checked to see if it has any direct fixed values, it also needs to be checked to see if parents fix it as well. This is similar to #84, and it is likely that solving this issue will make that issue easy to solve, but they are not quite duplicates.

Source info not being logged with all errors

It's been reported that there may be some log statements that don't report their source info (file and line #). We need to ensure all log statements include source info.

See: https://chat.fhir.org/#narrow/stream/215610-shorthand/topic/complex.20extensions

Instances not correctly written to ImplementationGuide JSON

The references to instances in the generated ImplementationGuide.json is incorrect. For example, I have a project with an instance of Patient. When I run sushi to generate an IG, I find this in the generated ImplementationGuide JSON:

        {
        "reference": {
          "reference": "Patient/undefined"
        },
        "name": "Patient-undefined",
        "exampleBoolean": true
      }

I've attached a sample project that displays this issue using the version of SUSHI on master.

simple-ig.zip

The filter "concept is-not-a 128462008" was not understood"

The IG Publisher complains about ValueSet-PrimaryOrUncertainBehaviorCancerDisorderVS.json:

Error from server: The filter "concept is-not-a 128462008" was not understood in the context of http://snomed.info/sct

The FSH looks ok to me:

* codes from system SCT where concept is-a #363346000 "Malignant neoplastic disease (disorder)" and concept is-not-a #128462008 "Secondary malignant neoplastic disease (disorder)"

I double-checked the codes are valid, too. I can't figure this one out since similar syntax is accepted elsewhere.

Exported artifacts are not reflecting the package version

Each exported artifact should default to the package version for its version element (when applicable). It should also allow users to override it if desired.

Apparently it is currently set as the FHIR version, not the package version.

Multi line elements

I created a multi line text entry (to simulate long text). Worked fine, but got '\n' in the output so not valid xhtml...

* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>
Dr Multi
<ul>
<li> item 1 </li>
<li> item 2 </li>
</ul>

</div>"

    "div": "<div xmlns='http://www.w3.org/1999/xhtml'>\nDr Multi\n<ul>\n<li> item 1 </li>\n<li> item 2 </li>\n</ul>\n\n</div>",
    "status": "additional"
  },

Nested extension error

SUSHI is reporting the following error:

error: Cannot resolve element from path: extension[USCoreRace].extension[ombCategory].valueCoding

I'm not sure if the problem is in the FSH or in SUSHI.

Lengthy List of Constraints on Profile Pages

There is a huge list of constraints on each profile page. For example, ele-1 and ext-1 are repeated many times -- once for each element. While this might be technically correct, US Core don't even include a section of constraints. This is a low priority, and probably requires some chat on zulip to see what other IGs are doing.

Problems with slices named 'code'

It appears there may be a parsing error (likely due to a keyword conflict) that doesn't allow authors to specify slices named code.

See: https://chat.fhir.org/#narrow/stream/215610-shorthand/topic/complex.20extensions/near/185044847

Instances (Examples) must have Ids

IG publisher won't process an example instance that doesn't have an id. The id should be the same as the name of example, by default. FSH doesn't accept an Id: keywork on example instances. Note: This is an mCODE show-stopper.

No file name or line number on certain errors

These error messages do no include line numbers/file names:

• Cannot resolve element from path
• Cannot fix string value
• Cannot bind value set to boolean
  Can we sweep the code base and see if there are any others?

Examples not showing up in tab on profile pages

Examples are not showing up on the pages of the profiles they are examples of. This is because we're generating the ImplementationGuide resource descriptions of examples with exampleBoolean instead of exampleCanonical. We need to update this to get the desired functionality. See: http://hl7.org/fhir/R4/implementationguide-definitions.html#ImplementationGuide.definition.resource.example_x_

e.type error causes SUSHI to skip Instance generation

In CancerGenomicsExample.fsh, the very last line is:
* component[GeneStudied].valueCodeableConcept = HGNC#619728 "STK11"
When this line is in, SUSHI generates an error:
error: e.type is not iterable
and SUSHI does not produce the example instance (mCODEGenomicRegionStudiedExample01).

When this line is commented out, the example instance is produced, and there is no error message.

This was hard to track down, because the line number was missing from the error message.

Dependencies are not copied into ImplementationGuide.json

When a user declares dependencies in their package.json file, if they are trying to export an IG, we need to copy the dependency information over into the generated ImplementationGuide.json file, so that the IG publisher knows about the dependencies. Otherwise any build will fail in the IG publisher if external dependencies are required.

Don't inherit potentially irrelevant metadata from parents

This issue stems from the conversation of #128. The general discussion was around clearing inherited metadata that causes issues in the IG Publisher or is potentially irrelevant to the profile. The main concern of #128 was the "comment" field, which is in ElementDefinition. We've currently decided not to address that because clearing comments would cause many differential elements.

This issue is to point out that the top-level metadata of profiles and extensions still inherits many fields that are potentially irrelevant or wrong for the profile/extension. We should remove those. I proposed an approach on Zulip here: https://chat.fhir.org/#narrow/stream/179252-IG-creation/topic/Bad.20links.20on.20Detailed.20Description.20tab/near/186460459

I've also copied the approach in case something happens to the zulip:

• id - overwrite w/ new id
• meta - clear
• implicitRules - clear
• language - clear
• text - clear
• contained - clear
• extension - clear (see #116)
• modifierExtension - clear
• url - overwrite w/ new url
• identifier - clear
• version - overwrite w/ IG version (author can override if maintaining per-profile versions)
• name - overwrite w/ new name
• title - clear or overwrite w/ new title (if applicable)
• status - currently defaults to active but FSH should add (required?) keyword
• experimental - clear
• date - clear
• publisher - clear (or overwrite w/ publisher from config?)
• contact - clear (or overwrite w/ contributors from config?)
• description - clear or overwrite w/ new description (if applicable)
• useContext - clear
• jursidiction - clear
• purpose - clear
• copyright - clear
• keyword - clear or keep? Would parent keywords still be applicable to child profiles?
• fhirVersion - set to target version (should match anyway)
• mapping - keep (assuming mappings are still valid and because removing them would require use to remove mappings from every element, creating tons of diffs)
• kind - keep (this should not change)
• abstract - keep or set to false. If you set an abstract profile as a parent should you need to explicitly toggle abstractness to false? Or should we default to false?
• context - keep (assuming context is still valid for child extensions)
• contextInvariant - keep (assuming context is still valid for child extensions)
• type - keep (this should not change for profiles or extensions)
• baseDefinition - overwrite w/ the parent URL of the new profile/extension
• derivation - set to constraint (so far, SUSHI only supports constraints)
• snapshot - keep, but elements will obviously be overwritten by constraints
• differential - clear, as the differential starts from scratch to reflect changes the profile has made to the parent

Error Populating Slices on Observation.component

The CancerGeneticVariant profile needs to slice Observation.component. SUSHI seems to be OK with populating the slices in-line, but the IG Publisher crashes with this message:

Caused by: org.hl7.fhir.exceptions.DefinitionException: Attempt to a slice an element that does not repeat: Observation.component.code/Observation.component.code from http://hl7.org/fhir/us/core/StructureDefinition/us-core-observation-lab in http://hl7.org/fhir/us/mcode/StructureDefinition/CancerGeneticVariant

The offending lines are currently commented out so we can build the IG, but look for these lines in CancerGenomics.fsh:

* component[GeneStudied] ^short = "Gene studied [ID]"
* component[GeneStudied].code = LNC#48018-6
* component[GeneStudied].value[x] only CodeableConcept
* component[GeneStudied].valueCodeableConcept 1..1
* component[GeneStudied].valueCodeableConcept from http://www.genenames.org/geneId (extensible)
* component[VariationCode] ^short = "Discrete genetic variant"
* component[VariationCode].code = LNC#81252-9
* component[VariationCode].value[x] only CodeableConcept
etc.

Required status field defaults to `active`

StructureDefinition, ValueSet, and CodeSystem has status fields that are 1..1. Since they're 1..1, we default to a value (active). But... we probably should not be doing this, because we really don't know. We probably should create a Status: keyword and force the author to declare it. But... at this point that would cause currently valid FSH definitions to start failing, so... we should discuss:

• should we add a Status: keyword?
• should it be required?
• if not required, what should we default to?

Images and other auxiliary files must be put into /images

Must be documented and implemented.

Bad links in Detailed Description page

There are a large number of QA errors reported by the IG Publisher about 404 links on the Profile "Detailed Description" pages. The links that are on the page are misconstructed, for example, http://hl7.org/fhir/R4/StructureDefinition-CancerStageParent.html/observation.html#notes. The SD that the page was constructed from only has the last part, as follows:

"comment": "For a discussion on the ways Observations can be assembled in groups together see [Notes](observation.html#notes) below."

Somewhere in the Publication process, the wrong root URL got added. The correct URL would have been http://hl7.org/fhir/R4/observation.html#notes.

Is this in the IG Publisher? Something in SUSHI??

References to codes defined in locally-defined code system cause IG Pub error

I tried to define a local code system:

CodeSystem:  AJCCFairUse
Title: "AJCC Fair Use"
Description: "A small local subset of AJCC staging codes for example purposes."
* #3C
* #cM0
* #cT3
* #cN3
* #pM0
* #pT3
* #pN3
```
and then referenced it in an instance like this:

`* valueCodeableConcept = AJCCFairUse#3C "IIIC"`

That didn't work because the IG Pub complained that you must use a URL for a code system, not a local name. 

So I tried this:

`Alias:   FairUse = http://hl7.org/fhir/us/mcode/CodeSystem/AJCCFairUse`

and then tried to reference it in an instance like this:

`* valueCodeableConcept = FairUse#3C "IIIC"`

but that didn't work either. The IG Pub complained "Unknown Code System 'http://hl7.org/fhir/us/mcode/CodeSystem/AJCCFairUse'", and "URL value 'http://hl7.org/fhir/us/mcode/CodeSystem/AJCCFairUse' does not resolve"

So I'm wondering how one an define a code system in FSH and use codes from that system in the same FSH Tank.

Sorry I can't provide a more complete example because I pulled back my change.

Issue creating complex extension definitions

When creating a complex extension using ginzu slicing, sushi attempts to locate an existing definition for each 'sub extension child' based on the name (as I understand it). I suspect that in most cases, the intention of the author is to create these child elements directly in the extension - rather than referencing some other.

That being the case, is the current behaviour the best? Would it be better to assume that the intention is to create an inline child, and have some other syntax when wanting to refer to an existing one?

As an example, the following would fail if anyone else used 'latitude' or 'longitude' as an extension name:

Extension: geolocation
Id: geolocation
Description:  "None supplied yet"

* extension contains
    latitude 0..1 and
    longitude 0..1

// definitions of sub-extensions
* extension[latitude].url = "latitude"
* extension[latitude] ^definition = "No description"
* extension[latitude].value[x] only decimal

* extension[longitude].url = "longitude"
* extension[longitude] ^definition = "No description"
* extension[longitude].value[x] only decimal

IG Publisher fails due to missing parameters

Apparently the IG Publisher instituted a new requirement that the ImplementationGuide resource contain parameters for releaselabel and copyrightyear, which is kind of funny since parameters use a required valueset and neither of those codes are in it. Oh well.

onGenerate.infoFile:
     [xslt] Processing /Users/cmoesel/dev/fhir/sushi/build/template/onGenerate-ig-working.xml to /Users/cmoesel/dev/fhir/sushi/build/temp/pages/_data/info.json
     [xslt] Loading stylesheet /Users/cmoesel/dev/fhir/sushi/build/template/scripts/onGenerate.genJson.xslt
IG must include a definition parameter with a code of 'copyrightyear'.  Value can be '2020+' or some similar value.
     [xslt] /Users/cmoesel/dev/fhir/sushi/build/template/scripts/onGenerate.genJson.xslt:11: Fatal Error! Processing terminated by xsl:message at line 11 in onGenerate.genJson.xslt
     [xslt] Failed to process /Users/cmoesel/dev/fhir/sushi/build/template/onGenerate-ig-working.xml
Publishing Content Failed: Fatal error during transformation using /Users/cmoesel/dev/fhir/sushi/build/template/scripts/onGenerate.genJson.xslt: Processing terminated by xsl:message at line 11 in onGenerate.genJson.xslt; SystemID: file:/Users/cmoesel/dev/fhir/sushi/build/template/scripts/onGenerate.genJson.xslt; Line#: 11; Column#: -1 (01:52.0302)
                                                                                 (01:52.0302)
Use -? to get command line help                                                  (01:52.0302)
                                                                                 (01:52.0303)
Stack Dump (for debugging):                                                      (01:52.0303)
/Users/cmoesel/dev/fhir/sushi/build/template/scripts/ant.xml:78: Fatal error during transformation using /Users/cmoesel/dev/fhir/sushi/build/template/scripts/onGenerate.genJson.xslt: Processing terminated by xsl:message at line 11 in onGenerate.genJson.xslt; SystemID: file:/Users/cmoesel/dev/fhir/sushi/build/template/scripts/onGenerate.genJson.xslt; Line#: 11; Column#: -1
	at org.apache.tools.ant.taskdefs.XSLTProcess.handleTransformationError(XSLTProcess.java:1435)
	at org.apache.tools.ant.taskdefs.XSLTProcess.process(XSLTProcess.java:880)
	at org.apache.tools.ant.taskdefs.XSLTProcess.execute(XSLTProcess.java:408)
	at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:292)
	at sun.reflect.GeneratedMethodAccessor4.invoke(Unknown Source)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at org.apache.tools.ant.dispatch.DispatchUtils.execute(DispatchUtils.java:99)
	at org.apache.tools.ant.Task.perform(Task.java:350)
	at org.apache.tools.ant.Target.execute(Target.java:449)
	at org.apache.tools.ant.Target.performTasks(Target.java:470)
	at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1388)
	at org.apache.tools.ant.Project.executeTarget(Project.java:1361)
	at org.hl7.fhir.igtools.templates.Template.runScriptTarget(Template.java:184)
	at org.hl7.fhir.igtools.templates.Template.beforeGenerateEvent(Template.java:341)
	at org.hl7.fhir.igtools.publisher.Publisher.templateBeforeGenerate(Publisher.java:2852)
	at org.hl7.fhir.igtools.publisher.Publisher.generate(Publisher.java:4255)
	at org.hl7.fhir.igtools.publisher.Publisher.createIg(Publisher.java:785)
	at org.hl7.fhir.igtools.publisher.Publisher.execute(Publisher.java:663)
	at org.hl7.fhir.igtools.publisher.Publisher.main(Publisher.java:6893)

Instance property must be an Array, not an Object

Elements that are defined as 0..* in resources must be JSON arrays in the instance, even if the cardinality has been constrained, or the array contains just one value. It appears array elements are being rendered as Objects rather than Arrays.

Example -- on master branch, at commit https://github.com/standardhealth/fsh-mcode/commit/4948b6ebe0018ddf2f9d8d8c53a469de972f059d

Example: build\input\resources\Condition-mCODEComorbidConditionExample01.json

IG Publisher reports: Condition.category | error | This property must be an Array, not an Object

Extensions in Generated StructureDefinitions are wrong

There is a section of extension within each SD generated by SUSHI that includes the standards status, fhir maturity (fmm), and work group. The values given are wrong, and should be corrected or the extension removed:

• The Standards Status is "normative" -- this is false. It should be derived from the IG json or package.json file, in mCODE's case, "trial-use" would be appropriate (note: the value must come from this value set: http://hl7.org/fhir/valueset-standards-status.html).

• The maturity (fmm) is set at level 5. This level is the highest maturity level, and should be assumed. A user can set it in FSH using the escape (^) syntax, but otherwise, it probably should be omitted entirely.

• If the maturity is specified, the "Text Summary" of each Profile page includes the text "Maturity: 5". with a link to a non-existent URL, versions.html#maturity. I am not sure what assumption the IG Publisher is making here, but we can't have a 404 happening here.

• The Work group (wg) extension is specified, and it seems to be the work group responsible for the resource, instead of the work group responsible for the profile. It should be the latter. The work group responsible for the profile is in the IG json or maybe package.json.

IG Pub warning about not finding value sets

The IG Publisher is issuing "no value set found" warnings. I'm not sure whether this is benign or if there is an impact on the IG:

onGenerate:
No value set found at Extension.value[x]:valueCodeableConcept (url = 'AnatomicalOrientationVS')
No value set found at Extension.valueCodeableConcept (url = 'AnatomicalOrientationVS')
No value set found at Observation.value[x]:valueCodeableConcept (url = 'ConditionStatusTrendVS')
No value set found at Observation.value[x]:valueCodeableConcept (url = 'ConditionStatusTrendVS')
No value set found at Observation.valueCodeableConcept (url = 'ConditionStatusTrendVS')
No value set found at Observation.valueCodeableConcept (url = 'ConditionStatusTrendVS')
No value set found at Observation.value[x]:valueCodeableConcept (url = 'https://fhir.loinc.org/ValueSet/LL1971-2')
No value set found at Observation.value[x]:valueCodeableConcept (url = 'https://fhir.loinc.org/ValueSet/LL1971-2')
No value set found at Observation.valueCodeableConcept (url = 'https://fhir.loinc.org/ValueSet/LL1971-2')
No value set found at Observation.valueCodeableConcept (url = 'https://fhir.loinc.org/ValueSet/LL1971-2')

Importer not reporting syntax errors

Sometimes the importer ignores syntax errors and doesn't report them to the user.

For example:

ValueSet: 				YesNoUnknownVS
Description:			"A value set containing yes, no, and unknown."
SCT#373066001			"Yes"
SCT#373067005			"No"
SCT#261665006			"Unknown"

This is missing the * before each line that adds a code. The importer should report this, but instead just skips those lines so you end up with a valueset having no codes in it.

Revert default status to `#active`

By request of Mark Kramer, we should revert default status back to #active until the community resolves what it should be. This aligns us w/ previous versions of SUSHI but brings us out of alignment w/ Forge defaults.

Default status will be a topic of discussion and changes will be made after the discussion, if necessary. But for now, back to #active for Profiles, Extensions, ValueSets, and CodeSystems.