This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "FHIR Implementation Guide Publishing Requirements"

From HL7Wiki
Jump to navigation Jump to search
(migrate to Confluence and add links)
 
(23 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Basic 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
 
These are for all FHIR implementation guides
  
== SHALL ==
+
==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
+
*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 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 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]])
+
*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 IG Version
* every page shall specify the FHIR 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:  
 
Maybe:  
* every page shall include the FHIR flame Icon with trademark symbol
 
* every page shall include the HL7 Logo with trademark symbol
 
  
== SHOULD ==
+
*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:
  
* implementation guides should include a downloadable version so people can host it locally
 
* 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
 
   ** full metadata
 
   ** differential view
 
   ** differential view
 
   ** snapshot view
 
   ** snapshot view
 
   ** full description of contents with details
 
   ** full description of contents with details
* Value Sets should have the following elements presented:
+
 
 +
*Value Sets should have the following elements presented:
 +
 
 
   ** full metadata
 
   ** full metadata
 
   ** logical definition
 
   ** logical definition
 
   ** at least one expansion (default)
 
   ** at least one expansion (default)
* it should be possible to print pages for review/display
 
  
= HL7/FHIR Foundation Requirements =
+
*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
 
These are for all implementation guides published (including balloted) on hl7.org or fhir.org
Line 39: Line 46:
 
which is the ongoing home of the implementation guide across multiple versions.  
 
which is the ongoing home of the implementation guide across multiple versions.  
  
== SHALL ==  
+
==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
  
* 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])
+
===Footer===
* 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
+
 
* implementation guides shall present information to the user such that by default, nothing is hidden unless there are clearly defined tabs for changing views
+
The Footer (see diagram below) SHALL include:
* 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
+
*A copyright claim (© HL7.org 2011+)
* 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 sponsoring WG
* the IG must not refer to build.fhir.org at all
+
*the package id and version.
* for HL7 IGs:
+
*the date generated
** 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)
+
*a link to the license + statement of the what the license is
** the realm in the ig resource matches the announced realm in the ballot
+
*a link to propose a change
** the package name (hl7.fhir.[realm].[code]) matches the realm and code in the canonical URL
+
*a link to the history/directory of published versions
** 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
+
===Process===
** the page footer must contain a copyright HL7 statement
 
* implementation guides shall be designed to enable product/standard differentiation as described below
 
  
 
Note also these process requirements for submitting an IG for publishing by HL7:
 
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 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  
+
*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 must exist in the repository, and have a correctly populated entry for the proposed release (except for date)
+
*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==
== SHOULD ==
 
  
 
(nothing)
 
(nothing)
  
= HL7 HTML Standards considerations =
+
=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'.
 
When HTML specifications are published on hl7.org, or fhir.org, the content of the pages is divided into 'product' and 'standard'.
  
== Product ==
+
==Product==
  
 
This is content that is under the ongoing control of the product manager, and the publication committee. The content  
 
This is content that is under the ongoing control of the product manager, and the publication committee. The content  
Line 81: Line 112:
 
- restyling decisions require syle updates
 
- restyling decisions require syle updates
  
== Standard ==
+
===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:
 +
 
 +
[[File:releaseheader.png]]
 +
 
 +
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:
 +
 
 +
<code><'!--ReleaseHeader--><'p id=\"publish-box\">Publish Box goes here<'/p><'!--EndReleaseHeader--></code>
 +
 
 +
<nowiki/><nowiki/></p>
 +
'''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
 
This is controlled content; changes to this content are only ever made as formal technical corrections
Line 87: Line 140:
 
to this is to correct external links that are not explicitly visible in the text of the IG.
 
to this is to correct external links that are not explicitly visible in the text of the IG.
  
== Differentation ==
+
==Differentation==
  
 
In order to make management simple, all HTML guides are split on the page into header, footer, and content.
 
In order to make management simple, all HTML guides are split on the page into header, footer, and content.

Latest revision as of 16:11, 8 November 2019

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:

Releaseheader.png

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:

Fhir-standards-layout.png