Proposed new FHIR IG build Process

This is some notes about of the proposed new FHIR build process for publishing implementation guides

Summary

Building an IG is a 3 part process:

• Defining the resources that underpin the Implementation Guide resources (Implementation Guide, Conformance Resources, Knowledge statements, examples)
• Building the publishing process that will publish it (linked to where it will be published)
• Developing the structure and the narrative content that turns the resources into a useful implementation guide

The FHIR team provide a IG Publishing tool that takes the implementation guide resources and converts them to a set of 3 different types of files:

• generated resources ready for inclusion into the published guide (xml, json, ttl formats)
• a set of fragments ready to include in generated html files
• 4 standard zip files: definitions.zip, xml.zip, json.zip, and ttl.zip - these are used by implementers for various purposes, so should be included in the final published version

Rules for Implementation Guides

The Implementation Guide is free to lay out the content in what form it chooses. However there are some rules about the arrangement of the implementation guide that must be followed:

• the IG Publisher will produce resources at [Type]-[id].[fmt] where fmt is one of xml, json, and ttl) (you can turn specific formats off using the fragment generation below)
• the IG publisher will produce redirects to those examples so the IG itself behaves like a FHIR end-point
• the IG publisher will produce the files definitions.[fmt].zip. The community will expect that these are published along with the guide as these enable the conformance tooling to work with the guide. These should be referenced somewhere from the guide, but the tooling will just expect that they exist at [base]/definitions.[fmt].zip
• the implementation guide is required to produce a page [Type]-[id].html for resource - this is where browsers are redirected to
• the implementation guide should produce a page [Type]-[id].[fmt].html for each [Type]-[id].[fmt] that contains the html fragment of the appropriate format (see below for tooling options to help with this)

Using the IG Publisher

The publishing process is a 3 step process:

1. pre-process spreadsheets and logical models
2. run the FHIR IG Publisher to validate all the resources & generate outputs and fragments
3. run a web site build tool to generate the final IG from the fragments and page templates

Supported tools for the third part of the process:

• Jekyll

To add tools to this list, discuss your tool of choice with Grahame Grieve

FHIR IG Publisher

This is a java jar called org.hl7.fhir.igpublisher.jar. You can get it from the downloads for the version of FHIR you are using, or - if you build locally - from your own publish directory. The jar includes everything from the spec that is required to generate the implementation guide. Make sure you use the correct version of the IG publisher for your guide.

The jar can be run from the command line, or hosted in a process. This documentation concerns the command line version. If you're hosting it, look at the class org.hl7.fhir.igtools.Publisher for guidance.

Run the IG Publisher like this:

 java -jar org.hl7.fhir.igpublisher.jar -ig [source] -out [folder] -spec [path] -tx [url] -watch

parameters:

• -ig: a path or a url where the implementation guide control file is found. see below for Documentation of that format
• -out: a local folder where the output from the IG publisher will be generated
• -spec: the location of the FHIR specification relative to the guide (can be an absolute URL, or relative if the guide will be published on the FHIR site)
• -tx: (optional) Address to use for terminology server (default is http://fhir3.healthintersections.com.au)
• -watch (optional): if this is present, the publisher will not terminate; instead, it will stay running, an watch for changes to the IG or its contents and re-run when it sees changes

once running, it:

• reads the control file
• reads the IG, and loads all the resources in the IG
• processes code systems, value sets, structure definitions, structure maps
• validates the all resources in the IG and produces an HTML file with any errors encountered
• for each resource in the IG, generate a set of files - renderings of the artifact for possible inclusion in the published IG
• generates summary output

Control file

When the IG publisher is executed, it is pointed at a json file that contains publishing information about the Implementation Guide. This is a json file in the same directory as the implementation guide resource, with the same [name].json, with this structure:

 {
   "source": "[ig].xml", // the name of the ig file to load
   "tool": {
     "type" : "jekyll" // The tool that will be used for the second step. see below for choices
     // other tool specific commands
   },
   "static-content" : "[folder]",
   "dependencies": {
     // not done yet
   },
   "canonicalBase": "[where this will be published finally and formally]",
   "defaults": {
     // this object contains the default publishing policy for different types. Anything not mentioned defaults to true
     "Any": {
       // fragment options - see below. example:
       "xml" : false // don't produce xml example
     },
     "[Type]": {
       // fragment options - see below
     }
   },
   "bundles" : [
     "[id]" // see using bundles below
   ],
   "spreadsheets" : [
     "[filename]" // see using spreadsheets below
   ], 
   "resources": {
     "[Type]/[id]": {
       "source" : "[optional source file]", 
       "base": "[destination page for things referring to this resource",
       "defns": "[destination page, for structure definitions]",
       "version" : "[optional version]"
       // and fragment options - see below
     }
   }
 }

This file must be maintained by the editor of the implementation guide. The IG resource must use sourceReference references by id. e.g.

 <sourceReference>
   <reference value="ValueSet/my-value-set"/>
 </sourceReference>

The ids are resolved to a local file by this control file. if there is no "source" property, the files will be assumed to be in the same directory as the ig, with the name [type]-[id].xml/json, or just [id].xml/json (can only use the simpler form if there's no duplicate ids across types)

Version: the version can either be "1.0.2" (version of FHIR supported by the current version of FHIR), or absent (meaning to treat it as the current version of the spec matching the build)

static-content

This is the folder where any manually authored files are located. It may have sub-directories. Some tools (see below) define special sub-directories.

Using Bundles

There's 2 different ways to use Bundles. The first way is examples of type Bundle. These are treated like any other resource. The second is where the bundle is a collection that contains a set of resources that need to be processed individually by the IG Publisher. To specify one of these bundles, use the "bundles" property:

   "bundles" : [
     "[id]"
   ]

The bundles property is an array of string, where each entry is the id of a bundle. The bundle will be located using the standard resource location process, but once loaded, the bundle itself will be ignored, and the individual resources processed directly. Each resource in the bundle must have an entry in the resources section, and should be entered in the implementation guide.

Using Spreadsheets

For legacy reasons, it's possible to author resources using spreadsheets. This approach is deprecated. To get the IG publisher to process a spreadsheet:

   "spreadsheets" : [
     "[filename]"
   ]

This is an array of string, which each entry is the filename of the spreadsheet, relative to the control file. Each resource represented in the spreadsheet (profiles, value sets, search parameters) must have an entry in the resources section, and should be entered in the implementation guide.

There's some differences between the spreadsheets used in the build directly, and the spreadsheets used by the IG Publisher, and these are changes that must be made manually:

• Value Set references - use either
  • http(s)://... a reference to a value set from outside the IG
  • ValueSet/xxx a reference to a value set defined in the IG, and registered directly in the implemnentation guide resource
  • xxx where:
    • xxx is the name of a file found in the same directory as the spreadsheet
    • The filename must not have .xml or .json on it, but a file with either .xml or .json appended to it must exist
    • The file must be a ValueSet resource, with an id of xxx and the appropriate canonical URL

• Search Parameters
  • You have to provide a fluent path expression directly ("Expression")
  • you have to provide a description directly
  • you have to specify the target types directly

• Types
  • the build tool allows for the use of "SimpleQuantity" and other data type profiles (not that the build tool uses any other) as types, but they have to be invoked as profiles in the IG spreadsheets

Fragment Options

When deciding whether to produce a particular kind of fragment, the IG Publisher will look for a property of type boolean with the name given below. It will look in the following places, in order:

• on the resource entry for the resource in question
• on the defaults entry for the resource type in question
• on the defaults entry for "Any"

if it doesn't find anything, it will produce the fragment.

Fragment Codes

• xml: XML version of the resource (all resource types)
• json: JSON version of the resource (all resource types)
• ttl: Turtle version of the resource (all resource types)
• xml-html: html representation of XML version of the resource (all resource types)
• json-html: html representation of JSON version of the resource (all resource types)
• ttl-html: html representation of Turtle version of the resource (all resource types)
• html: narrative of resource as html
• summary: An html summary for the resource (all conformance resources)
• content: An HTML representation of the content in resource (code system, concept map, structure map)
• xref: A list of all the places where the resource is used (all conformance resources)
• cld: An HTML representation of the content in resource (value set)
• expansion: The expansion of the value set (Value set)
• shex: ShEx statement for the structure (Structure Definition)
• sch: schematron statement for the structure (Structure Definition)
• json-schema: JSON Schema statement for the structure (Structure Definition)
• header: Description of the identification of the structure (Structure Definition)
• diff: Logical Table of the diff (Structure Definition)
• snapshot: Logical Table of the snapshot (Structure Definition)
• template-xml: XML template for the snapshot (Structure Definition)
• template-json: JSON template for the snapshot (Structure Definition)
• template-ttl: Turtle template for the snapshot (Structure Definition)
• uml: UML diagram for the structure (Structure Definition)
• tx: Terminology Notes for the structure (Structure Definition)
• inv: invariant summary for the structure (Structure Definition)
• dict: Detailed Element Definitions (Structure Definition)
• maps: Presentation of the mappings (Structure Definition)

Build

Jekyll

type in config file: "jekyll":

   "tool": {
     "type" : "jekyll",
     "source-wrapper-template" : "wrapper.html"
   },

If you specify Jekyll as the tool, the the following outputs are created

• X (X is the nominated output directory) - untouched
• X\generation - the validation file, and the all the generated qa pages (one for each fragment, so you can see what the fragments are supposed to look like)
• X\html - the content for the final IG. This is the Jekyll root directory
• X\html\_includes - all the fragments, so you can {%include%} them
• X\html\_data - a data file fhir.json with additional properties so you can access them when templating

source-wrapper-template

source-wrapper-template is a file with a location relative to the configuration file. The content of the file is a jekyll source file (e.g. html or markdown etc). The file will be copied to the correct place for the xml/json/ttl wrapper for each resource. When copied, the following strings will be replaced:

• {{[title]}} - a description of the content of the resource (typical use: <h2>{{[title]}}</h2>)
• {{[name]}} - the path for the source fragment to include (proper use: {% include {{[name]}}.xhtml %})