Proposed new FHIR IG build Process

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

Summary

The publishing process is a 2 step process:

1. run the FHIR IG Publisher to validate all the resources & generate fragments
2. run a web site build tool to generate the final IG

FHIR IG Publisher

This is a java jar that can be run from the command line, or hosted in a process. Whether hosted in a process, or run from the command line, it works the following way:

• it takes 4 parameters:
  • the name of the control file to load (see below for documentation) (-ig)
  • URL of terminology server to use (-tx - defaults to http://fhir3.healthintersections.com.au)
  • path to the version of the specification to generate from (the validation zip has to be from be from this version) (-spec)
  • folder to output to (-out)

once running, it:

• loads all resources in the validation.zip
• 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
  • produce 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

On the command line, there is a 5th parameter (-reside), instructing the validator to stay loaded, and rerun the process anytime any of the source files are changed When run in process, the IG Publisher can be passed a resolver that is used to find content that is required when encountered (this is an alternative to specifying folders for the dependent implementation guides)

IG Publisher Dependencies

The IG publisher makes use of the following resources:

• NamingSystem
• CodeSystem
• ValueSet
• DataElement
• StructureDefinition
• ConceptMap
• StructureMap

When any of these resources change, the IG Publisher must be updated. for other resources the IG Publisher uses whatever definitions of them are in use in validation pack that it is passed

Control file

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

 {
   // this must be in the same directory
   "source" : "payerextract.xml",  
   
   // the common base canonical URL for all conformance artifacts defined by the IG
   // the IG will ensure that all URLs are [canonicalBase]/[type]/id 
   // and generate redirects accordingly
   "canonicalBase" : "...", 
   
   // yet to be done / documented
   "dependencies" [
       
   ],
   
   // a list of paths for each resource in the IG. This tells the 
   // IG publisher where links to a logical item should actually 
   // point to for cross-references within the IG
   // this is an array of object
   "paths" : [
      {
        "url" : "...", // either a simple [id], [type]/[id] or the full canonical URL 
        "base" : "[filename]", // the file name for which references should point in final IG
        "defns" : "[filename]", // the name of the file that will contain the formal definitions (structure definitions only)
      }
   ]
 }

This file must be maintained by the editor of the implementation guide

Output

The output consists of a set of files in /output:

• validation.html - the result of validating the resources
• instructions.txt - how to use the generated fragments in the second part of the build (including what must be placed in header of the html files that use the generated fragments (.js and .css includes)

In /output/content - anything in here goes in the final generated IG

• images and stylesheets - css file for all the generated content (copy from spec) + supporting images etc
• generated resources after post-processing, ready for distribution, in xml, json, turtle
• generated schema files (.shex, .schema.json, .sch)
• IG validation packs (validation.xml.zip and validation.json.zip) for the FHIR validator
• redirection files

In /output/_includes

• variables.json : an array of "name" : "value" pairs that provide useful information about fhir (e.g. version) so they can be built into the generated pages
• different generated views of the resources
  • each file has name [id]-[type].html where [id] is the id of the resource, and [type] is the type of generated html fragment. Todo: enumerate the types

In /output/_data

• fhir.json: a set of data related to the build process for inclusion into an IG using Jekyll

in /output/pages

• a full html page, one for each generated fragment in /output/fragments
  • these are used for quality checking if there's problems with the fragment styling downstream

Output Fragments

These fragments are produced for each resource:

• [id]-html.xhtml: the narrative of the resource, as html
• [id]-gen-html.xhtml: the generated narrative of the resource, as html
• [id]-xml-html.xhtml: the xhtml rendering of the xml format of the resource, with hyperlinks
• [id]-json-html.xhtml: the xhtml rendering of the json format of the resource, with hyperlinks
• [id]-ttl-html.xhtml: the xhtml rendering of the turtle format of the resource, with hyperlinks

For specific types of resource:

• CodeSystem
  • [id]-cs-summary: narrative summary of the resource
  • [id]-cs-content: presentation of the content of the code system
  • [id]-cs-xref: list of all value sets where the code system is used
• ValueSet:
  • [id]-vs-summary: narrative summary of the resource
  • [id]-vs-cld: presentation of the content of the code system
  • [id]-vs-xref: list of all places where the value set is used
  • [id]-expansion: HTML representation of the expansion of the value set (or an error)
• ConceptMap:
  • [id]-cm-summary: narrative summary of the resource
  • [id]-cm-content: presentation of the content of the code system
  • [id]-cm-xref: list of all places where the concept map is used
• StructureDefinition:
  • [id]-sd-summary: narrative summary of the resource
  • [id]-shex: shex as html
  • [id]-sch: schematron as html
  • [id]-json-schema: json schema as html
  • [id]-diff: Logical table of Differential
  • [id]-snapshot: Logical table of Snapshot
  • [id]-xml: Xml template
  • [id]-jso: Json template
  • [id]-ttl: Turtle template
  • [id]-uml: UML as SVG
  • [id]-tx: Terminology Binding Summary
  • [id]-inv: invariant summary
  • [id]-dict: Formal definitions
  • [id]-maps: mappings
  • [id]-sd-xref: list of all places where the structure is used

Build

The build program (todo: investigate and choose the appropriate tool) builds from a series of html or markdown pages, and may be integrated as part of a server (e.g. GitHub). The html source files and build tool injects the files that the IG publisher generated into the final output.

todo: fill out the details of this