FHIR Implementation Guide Publishing Requirements

Content on this page has been migrated to Confluence here: https://confluence.hl7.org/display/FHIR/FHIR+Implementation+Guide+Publishing+Requirements

Basic Requirements

These are for all FHIR implementation guides

SHALL

• declare a `publisher` and `contact` element in the ImplementationGuide instance and expose this information on the home (index) page or an obviously labeled page navigable to from the home page
• implementation guides SHALL use index.html as the root page, or redirect from there to the actual root
• implementation guides SHALL have an NPM package file describing the guide (see FHIR NPM Package Spec)
• implementation guides SHALL contain an openAPI file for each CapabilitiesStatement (see FHIR IG Swagger Documentation) (currently optional since Swagger documentation is not done)
• every page SHALL specify the IG Version
• every page SHALL specify the FHIR version
• Implementation guides SHALL include a downloadable zip file containing the full content of the IG so the content can be hosted locally.  The index.html page for the guide SHALL include a link to this or to a "downloads" page that includes such a link.

Maybe:

• every page SHALL include the FHIR flame Icon with trademark symbol
• every page SHALL include the HL7 Logo with trademark symbol

SHOULD

• implementation guides should only refer to a single location of FHIR (unless specifically cross version issues are being addressed)
• implementation guides should present information to the user such that by default, nothing is hidden unless there are clearly defined tabs for changing views
• Profiles should at least have the following elements presented:

 ** full metadata
 ** differential view
 ** snapshot view
 ** full description of contents with details

• Value Sets should have the following elements presented:

 ** full metadata
 ** logical definition
 ** at least one expansion (default)

• it should be possible to print pages for review/display

HL7/FHIR Foundation Requirements

These are for all implementation guides published (including balloted) on hl7.org or fhir.org

Note that all IGs published by HL7 or the FHIR Foundation are assigned a canonical URL which is the ongoing home of the implementation guide across multiple versions.

SHALL

• Have a FHIR implementation guide proposal in place (see http://wiki.hl7.org/index.php?title=Category:FHIR_IG_Proposal)
• HL7 published implementation guides shall identify the ImplementationGuide.publisher as "HL7 International - <workgroup full name>" and ImplementationGuide.contact as the work group home page (i.e. http://www.hl7.org/Special/committees/[committee code])
• Implementation Guides shall reference [canonical]/history.cfml as the source of information about other releases of the guide, and SHALL do at least from index.html (note: authoring the history.cfml page is not done by the IG; that's publishing infrastructur. it is built by cold fusion from the package-list.json file)
• implementation guides shall present information to the user such that by default, nothing is hidden unless there are clearly defined tabs for changing views
• implementation guides shall not contain any server side active content except that required by redirects for canonical URL management
• it shall be possible to print pages from the IG for review/display
• implementation guides shall include a downloadable version so people can host it locally, and it SHALL be referenced from the home page (potentially by a link to another page)
• the IG must not refer to build.fhir.org at all
• for HL7 IGs:
  • the realm in the canonical URL (http://hl7.org/fhir/[realm]/[code]/...) matches the specified jurisdiction in the IG resource (and uses the correct two letter abbreviation)
  • the realm in the ig resource matches the announced realm in the ballot
  • the package name (hl7.fhir.[realm].[code]) matches the realm and code in the canonical URL
  • the version is as agreed with the FHIR product director, and specified in fixed-business-version
  • information in the page header/footer must be consistent about realm, code, and version
  • the page footer must contain a copyright HL7 statement
• implementation guides shall be designed to enable product/standard differentiation as described below

Header

The Header (see diagram below) SHALL include:

• The FHIR icon
• the HL7 Icon
• the name of the IG
• the publication name of the IG
• the version of the IG

Footer

The Footer (see diagram below) SHALL include:

• A copyright claim (© HL7.org 2011+)
• the sponsoring WG
• the package id and version.
• the date generated
• a link to the license + statement of the what the license is
• a link to propose a change
• a link to the history/directory of published versions

Process

Note also these process requirements for submitting an IG for publishing by HL7:

• the content must live in a github repository in the HL7 organization (or another TSC approved location)
• the IG must build on the CI build, and must say which ballot/publication it is correctly in the page header and the
• package-list.json (see FHIR IG PackageList doco) must exist in the repository, and have a correctly populated entry for the proposed release (except for date)

SHOULD

(nothing)

HL7 HTML Standards considerations

When HTML specifications are published on hl7.org, or fhir.org, the content of the pages is divided into 'product' and 'standard'.

Product

This is content that is under the ongoing control of the product manager, and the publication committee. The content may be changed on an ongoing basis for the following reasons: - new subsequent releases of the IG are published, and the status changes - subsequent changes to web infrastructure require new links/styles/content - external content changes require fixes to links / descriptions - restyling decisions require syle updates

Publish Box

Every HL7 implementation guide contains a publish box on every page that contains status information about the release status of the IG as a whole:

This header is updated any time a new version of the IG is published - e.g. the old published versions of the IG are updated. In order to facilitate such actions, the IG - when presented for publication - SHALL have this literal HTML fragment in an appropriate place in the HTML source of the page:

<'!--ReleaseHeader--><'p id=\"publish-box\">Publish Box goes here<'/p><'!--EndReleaseHeader-->

Note: Remove spurious ' characters that had to be added to stop the wiki trashing the HTML fragment

The publication tools will manage the actual content of this publish-box paragraph

This must present in the product section of the page (see below) and must be rendered as a yellow box with a maroon border (as shown above). This is the standard CSS for this look:

 #publish-box {  list-style: none;  padding: 0; }
 p#publish-box { background-color: yellow; border:1px solid maroon; padding: 5px; }
 img#publish-box { text-align: baseline; }

Note that the IG publisher auto bulld infrastructure requires that this box be present for all IGs, irrespective of whether they are HL7 implementation guides or not. For non HL7 guides, the publish box must be present and clearly visible, but styling is at the discretion of the author. The publish-box does not need to be present when the IG is published anywhere else, but HL7 recommends that other publishers user the same approach to manage status.

Standard

This is controlled content; changes to this content are only ever made as formal technical corrections with careful change control and announcements through HL7/FHIR Foundation formal channels. The only exception to this is to correct external links that are not explicitly visible in the text of the IG.

Differentation

In order to make management simple, all HTML guides are split on the page into header, footer, and content. The header and footer are 'product' and the content is 'standard', as shown on this diagram, where the shaded yellow is the content: