Format

The package-list.json is a json file that is published at the root location of an IGs web presence that lists the available published versions, and their details. The web history file (usually history.html) is automatically built off the package-list.json file, and exists to allow tools to discover the history of the IG.

Note that the file is maintained by publication tooling, and editors never edit this file directly. In case there is wrong content in the package-list.json file, the only way to address issues with it is via the webmaster for the publication URL. (In case of HL7, that's the FHIR Product Director)

Base Object

The file contains a single Base object:

 {
   "package-id" : "[id]", // mandatory
   "title" : "[title]", // mandatory
   "canonical" : "[canonical]", // mandatory
   "introduction" : "[intro]", // optional
   "category" : "[category]", // mandatory
   "language" : "[language],  // optional
   "list" : [
     1..* Publication objects (see below)
   ]
 }

Doco:

  • id: The NPM package id for the IG, (i.e., format of hl7.fhir.[realm].[name])
  • title: a human readable name for the IG
  • canonical: the URL at which this package-list.json will be published. For HL7 IGs, this will match the base URL of the IG (see NPM Package Specification#ImplementationGuideCanonical)
  • intro: an optional common markdown describing the purpose and contents of the IG
  • category: a category for the IG for use by the ig-registry at http://fhir.org/guides/registry/
  • language: The language to use when generating text associated with the package list (typically: in the publish box at the top of published pages). Default language is en. Supported language list: en. Contact the FHIR product director to add your language to this list


Note: for HL7 IGs, the the contents of these elements are all derived from the IG proposal agreed to by FMG

Publication Object

Note: the order of publication objects is important - must be ordered with most recent at the top

 {
   "version" : "[version]",   // mandatory
   "milestoneName" : "[name],  // optional
   "date" : "[date]",    // mandatory, except for ci-build entry 
   "desc" : "[desc]",   // mandatory
   "path" : "[path]",   // mandatory
   "changes" : "[changes]", // optional
   "status" : "[status]",   // mandatory
   "sequence" : "[sequence]",   // mandatory, except for ci-build entry
   "fhirversion" : "x.x.x",   // mandatory, except for ci-build entry
   "current" : [?current]   // optional, default false
  }

Doco:

  • version: the stated version of the IG for the publication. The first instance will be "current" for the ci-build entry, subsequent entries are n.n.n e.g. 1.1.0
  • date: the date at which the publication was made [yyyy-mm-dd]
  • path: where the publication is or will be found. Usually at [canonica]/version or similar (absolute URL)
  • desc: a text description of the publication (e.g. reason for publication). Some use descmd to support a more robust description
  • changes: a link within the published spec that details the changes in this version (relative URL to path)
  • status: the status of the publication - one of:
    • ci-build - the continuous integration build release (not stable)
    • draft - draft version
    • qa-preview - frozen snapshot for non-ballot feedback
    • ballot - frozen snapshot for ballot
    • trial-use - official release with 'trial use' status
    • informative - official release with an 'informative' status
    • release - official release for use.  (Not permitted for HL7 International publications - use a more specific status.)
    • update - official release with 'trial use' status - posted as an un-ballotedSTU update
    • normative+trial-use - official release with mixture of trial use and normative content
    • (NOTE: this list of codes must not be changed without also updating the HL7 IG template scripts.)
  • sequence: which group to publish this as part of (typically, 'STU 1' etc). Groups all the ballot publications and the final publication for the ballot sequence
  • fhirversion: the version of FHIR on which the IG is based
  • milestoneName: the name for this release. This is used when generating page indexes like this:  - the versions that are listed are those that have milestoneNames
  • current: true if this version should be listed in the current versions summary at the top of the history page. True for the CI-Build, and the version currently posted to the canonical URL

Note: the order of publication entries matters. The list should be ordered, with the ci-build entry first, then grouped by sequence and then from most recent to oldest in each sequence

CI Build

The first entry SHALL be a reference to the CI build. This has current = true, no date, 'current' for the version, etc:

 {
   "version" : "current",
   "desc" : "Continuous Integration Build (latest in version control)",
   "path" : "http://build.fhir.org/ig/HL7/[xxxx]",
   "status" : "ci-build",
   "current" : true
 }

where [xxxx] is the repository name.

Template

{
 "package-id" : "id",
 "title" : "title", 
 "canonical" : "url", 
 "introduction" : "md",
 "category" : "category",
 "list" : [{
  "version" : "current",
  "desc" : "Continuous Integration Build (latest in version control)",
  "path" : "http://build.fhir.org/ig/HL7/xxx",
  "status" : "ci-build",
  "current" : true
 },{
  "version" : "version",  
  "date" : "date", 
  "desc" : "desc",   
  "changes" : "link",
  "path" : "url",   
  "status" : "status",   
  "fhirversion" : "4.0.1",
  "sequence" : "sequence"
 }]
}
  • No labels