Guidance for FHIR IG Creation
0.1.0 - CI Build International flag

Guidance for FHIR IG Creation, published by HL7 International - FHIR Management Group. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/FHIR/ig-guidance/ and changes regularly. See the Directory of published versions

Working with Binaries

Binary Adjunct Files

For several resource types, it can be more convenient to edit base64Binary content directly. The obvious candidate resources are:

  • Binary
  • Library
  • DocumentReference

But there are many other resources where this might be useful. The technique described here will work for any Resource with Attachments in it.

Here's how to make it work:

  • Create the resource as per normal
  • For the attachment element, leave the data out, and provide only an id and contentType
  • the id has the special value "ig-loader-[filename]", where filename is the name of the file to load. e.g. "id" : "ig-loader-MyLibrary.cql" (case sensitive)
  • The IG Publisher will scan all the folders identified by the path-binary parameter, and remove the id property, and replace with with the content from the file
  • If a matching file cannot be found, the id will be left in place, and an error will be logged in the qa page

Binary is a special case. For Binary, make the content of the data itself equal to "ig-loader-[filename]"

Note: the following file extensions are supported:

  • .txt (text/plain)
  • .pdf (application/pdf)
  • .jpg, .png, .gif (image/xx)
  • .dicom - application/dicom
  • .cql - text/cql.

CQL Processing

CQL included into a library is subject to additional processing. Additional content elements will be injected for application/elm+xml or application/elm+json, depending on the format cql translator option - do not create a stub for this manually.

CQL translator options are provided using a cql-options.json file co-located with the CQL source content (as specified in the path-binary parameter). Documentation of this file is provided in the CqlTranslatorOptions topic of the CQL-to-ELM translator overview.

If no CQL options file is present, the default translator options will be used.

For each CQL source file included in a Library resource, the following steps are performed:

  1. The CQL source file is compiled to ELM, returning any information, warning, or error messages as messages to the publisher output.
  2. If there are errors, an additional failure message is reported to the publisher output as an error, indicating the CQL file could not be successfully processed.
  3. On successful compilation, the ELM output is base64-encoded as an additional content element application/elm+xml, application/elm+json, or both, depending on the format option.
  4. Dependencies of the library are reported as depends-on relatedArtifact entries in the library as documented in Related Artifacts. Dependencies include any models, libraries, code systems, or value sets referenced in the CQL.
  5. Any input parameters are added as in parameters
  6. Any expression definitions are added as out parameters
  7. Any retrieves in the library are added as dataRequirement elements
  8. The CqlTranslatorOptions used are added using the cqf-cqlOptions extension

Parameters and data requirements are reported as documented in FHIR Type Mapping and Parameters and Data Requirements

The resulting Library is expected to conform to the following profiles:

  1. CQLLibrary
  2. CQLModule
  3. ELMXMLLibrary
  4. ELMJSONLibrary, if JSON is specified as a format