Maintaining FHIR Core

This page provides guidance on what files contain the source for managing different types of core maintenance tasks.

Git

All changes to the core specification are managed using Git. All changes must be managed by submitting a pull request against the https://github.com/HL7/fhir.git project (or for technical corrections or special release like R4B, one of the branches to that project). Within the project, almost all maintenance will happen within the 'source' folder. Other folders contain either generated content, tooling infrastructure or files that most individuals won't need to change or modify.

Before attempting to make changes to any FHIR resources, the first thing to do is to ensure that your environment is set up to properly build. Guidance for doing this can be found on the FHIR Build Process page.

Normative content

WARNING: The file location process described below has not been fully implemented yet.

Resources and pages that have passed ballot such that all or part of their content is now normative are managed slightly differently from everything else.

First, all such files live in sub-folders called 'normative'. Thus regular spec pages that are normative will live in the source/normative folder and pages that contain normative content for a particular resource will live in the source/[ResourceName]/normative folder. (Note that when a resource is normative, not all of the resource will be normative, so it will be common for a normative resource folder to contain content in both the 'base' folder (e.g. examples, non-normative operations & extensions) as well as a normative folder containing the resource, intro and notes pages as well as any normative operations, value sets and code systems.

Maintaining Pages

Maintaining stand-alone pages is the 'simpler' aspect of maintaining FHIR content. Any pages that aren't directly associated with a specific resource, pattern, extension or profile are managed as [root]/source/*.html with the file name as it will be in the published specification (generally) the same as what the page name will be in the published specification. For example, [root]/source/index.html corresponds to [root]/publish/index.html.

All such files are XHTML files, though many of them also contain embedded rendering commands, of the form [% some command %]. The location of these commands sometimes result in the source files not being valid XHTML. The most common of these commands - [%file somename%], causes the file with the name somename.html to be included at that location. Note that some of the included files are not maintained in [root]/source, but are instead maintained in [root]/tools/templates.

In order for a file to be propagated to the publication, it must be listed in the [pages] or [special-pages] section of [root]/publish.ini. "[pages]" is used for 'regular' pages that have maturity levels and ballot levels (and which will throw an error if the relevant table isn't present), while "[special-pages]" is used for pages that do not have such information (and will throw an error if the table is present). In addition, the [root]/source/hierarchy.xml also needs an entry. The location of the page in the hierarchy determines where it will appear in the table of contents.

Where a page references image content or other 'static' content that needs to be propagated unchanged to the publish folder, such content should be placed in the source/images folder and an entry must be placed in [root]/publish.ini under the [images] or [files] entries to cause the image or file to be propagated.

Maintaining Resources

Resources fall into two categories - infrastructure resources that are tightly incorporated into FHIR tooling, and everything else. Descriptive changes (definitions, comments, short descriptions, mappings, etc.) can be made to any resource without going through special processes, however substantive changes to 'infrastructure' resources (renaming resources or elements, changing data types, changing cardinality or other constraints, etc.) will often result in a need to make changes to the Java code used to manage core publication, shared Java libraries, and/or the IG Publisher. At some point, we may document how to manage changes to these resources, but for now, it's best to assign issues involving substantive changes to conformance resources to Grahame, Mark or one of the other tooling committers.

This section will focus on descriptive changes to all resources and substantive changes to non-infrastructure resources. In addition to the basic rules for changing resources, there are a few types of changes that require 'extra' steps. Consult this additional guidance if you are Adding new resources, Renaming resources, or Deprecating resources.

Resource content consists of a variety of resource types as well as supplemental files. All content can be managed as XML resources instances or XHTML files. This is the 'source of truth' content that is actually maintained inside Git. In addition, some content can be managed using an Excel interface.

Using Excel

The Excel interface is provided as an integrated 'simpler' mechanism for maintaining resource content. It's intended to be used by non-technical editors which may be uncomfortable editing XML. Also, for certain types of bulk changes or for quickly scanning a resource, the Excel view can be more efficient. However, working with Excel files adds complexity, so for simple changes, it is often more straight-forward to directly edit the XML files and ignore the Excel files entirely. If you wish to use the Excel files, the name of the spreadsheet will be [resourcename]-spreadsheet.xlsx. There will be a companion file called [resourcename]-spreadsheet.datestamp that captures when the spreadsheet was last generated. The process is as follows:

1. Generate the Excel files

The Excel files will not exist when the core build is first cloned from Git. In order to see Excel files (or to ensure Excel files are up-to-date after pulling down new changes), you must run a local build. This will generate Excel files that reflect the 'current' state of the source files in the build directory. Note that it is essential to run a local copy of the build after pulling down a new copy if you plan to work with Excel. That's because the publication process proceeds on a basis of timestamp comparison. If the publisher determines that XML files are newer than the spreadsheet.datestamp file, then it will force the spreadsheet to be regenerated, meaning you'll need to re-do your work. Also, don't run the build with any of the Excel resource files open in Excel - the build process won't be able to update them and will fail.

2. Edit the Excel files

All of the Excel content is generated and will be re-generated, so don't fuss too much with changing formatting and don't try to introduce new columns - they'll just go away.

The Excel files consist of a set of tabs. Some pertain directly to the resource. Others deal with managing the list of content that is 'related' to the resource (profiles, extensions, examples, etc.). Full guidance on the content of the Excel file can be found in FHIR Resource Excel Files.

If you're editing Excel files don't mess around with the XML files at the same time unless you really know what you're doing. Some of the XML files are safe (e.g. example files), but any XML files that are used to generate the Excel file can't be touched until all changes you've made from Excel have been propagated back to XML. If you edit both XML and Excel, the publisher will fail and you'll be faced with rolling back your Excel changes and re-generating the Excel file.

Once you're finished editing, save and close Excel

3. Re-generate XML files from the Excel files

Excel files are not committed in Git. In order for the changes made in Excel to be committed, they must first be propagated into the relevant XML file(s). To do this, the core build must be run again. (This is always a good idea even if you're not using Excel as it's generally better to catch issues locally than to submit a pull request when your build has a problem.) Running the build will update all of the XML files to align with the changes made in Excel to allow the content to be checked in

4. Commit the changed XML files

To make the changes available to others, the content needs to be committed to a branch, then pushed to core and a pull request created and, once it builds successfully, the pull request needs to be merged.

Where content lives

The resource folder will contain a large number of files (possibly into the hundreds). The following section describes what file(s) contain the content needed to maintain certain sections of the resource page.

Content	File	Spreadsheet	Comments
Tabs - Examples	[resource]-examples-header.xml	N/A	This is introductory text for the examples tab. It might provide an overview, provide links to places where there are additional examples, provide guidance on figuring out what examples are likely relevant to you, or might say something relatively useless such as "Examples for the XYZ resource."
	list-[Resource]-examples.xml	Examples tab	This is the list of examples associated with the resource. Sticking an example file in the resource folder and not including it in this file won't do anything. This is also where metadata like title and description for the examples are maintained
	[resource]-example*.xml	N/A	Individual example instances. Technically, nothing requires the files to be named this way, but please do so that all of the examples sort together and so the examples are easily distinguished from other files.
Tabs - Detailed Descriptions	part of StructureDefinition-[resource].xml	Resource, Bindings & Invariants tab	Pretty much all of the data element content shows up on the Detailed Descriptions tab
Tabs - Mappings	part of StructureDefinition-[resource].xml	N/A	If you want to define a new specification mapped to for all of FHIR, that's done using [root]/mappingSpaces.xml file. In the XML, mapping types must be declared at the root using the <mapping/> tag directly on StructureDefinition and then on the mapped elements.
Tabs - Profiles & Extensions	list-[Resource]-packs.xml	N/A	A List resource that has an entry for each 'pack' associated with the resource. Most of the time, there will only be one entry - the 'core' pack which defines the content of the Profiles & Extensions tab. However, a few resources have "extra" packs beyond the 'core' pack (see below)
	implementationguide-[Resource]-core.xml	Pack core tab	This lists all of the profiles and extensions that will show up in the Profiles & Extensions tab for the resource. It may also indicate if introductions or notes exist to appear on the tab (via the introduction and notes extensions) and, if no introduction is present, provides the descriptive text to provide prior to the list of profiles and extensions (via `StructureDefinition.description`)
	StructureDefinition-extension-*.xml	N/A	These are the definitions of each individual extension (differential only). All extensions need to be referenced in one of the 'pack' ImplementationGuides to actually be recognized and used.
	*-introduction.xml	N/A	This overrides the StructureDefinition.description of the ImplementationGuide to determine what content appears as the "introduction" for a package of profiles and extensions (for example referencing material defined elsewhere). The content is expressed as XHTML. The name of this file doesn't technically even need to end in "-introduction" - all that matters is that the full name is referenced by the introduction extension in the implementation guide file for the pack. (However, please do follow the naming convention to avoid confusion.) These files can also be introductions for individual profiles or extensions. If the filename is
	[resource]-[profileid]-extension-introduction.xml	N/A	This defines introductory content to appear on the page of the profile with the specified id
	[resource]-[profileid]-extension-notes.xml	N/A	This defines supplementary usage note content to appear on the page of the profile with the specified id
	*-notes.xml	N/A	This XHTML content appears following the list of any extensions and profiles defined in a particular 'pack' implementation guide. Again, the name of this file doesn't technically even need to end in "-introduction" - all that matters is that the full name is referenced by the notes extension in the implementation guide file for the pack.
	StructureDefinition-profile-*.xml	N/A	These are the XML StructureDefinition instances that define any 'core' profiles for the resource. They must also be referenced in one of the
(special)	implementationguide-[Resource]-*.xml	Pack ??? tabs	Other 'pack' files may be defined in the list-[Resource]-packs.xml file. The content listed here will not appear under the Profiles & Extensions tab for the resource. However, the pack will show up in the master list of Profiles in the red main menu at the top of the spec. Typically these additional packs will be also be referenced by the introduction or notes sections for the resource. All of the file structures listed above (StructureDefinition-extension-.xml, -introduction.xml, -notes.xml and StructureDefinition-profile-.xml can all be associated with 'other' pack files, just as they can be associated with the 'core' package for a resource.
Tabs - Operations	list-[Resource]-operations.xml	Operations tab	This provides a list of references to all operations associated with the resource
	OperationDefinition-[resource]-*.xml	Operations tab	These define the supplemental operations for the resource. Note that operations must be listed in the list-[Resource]-operations.xml to be processed.
	*.txt	N/A	These are operation example instances (or descriptive instances) that explain how to use operations. They must be referenced by the `example/content` extensions within the OperationDefinition.
Tabs - R3 Conversions	implementations/r3maps//.map	N/A	All of the R4↔R5 maps will be created late in the publication cycle, shortly before final publication, so changing these map files should only be done as part of an R4 technical correction.
Metadata	source/fhir.ini	N/A	Workgroup, maturity, ballot status, normative date, and security category all appear in the extensions declared at the root of the structure definition. However, they are not maintained here. If you make a change to these extensions in the StructureDefinition-[resource].xml file, they'll be ignored. To change the workgroup, find the resource under the `[workgroups]` entry in the ini file. (The workgroup codes are themselves maintained in the same file under the `[wg-info]` entry.) Maturity is managed using the `[fmm]` entry. (Note that maturity sometimes gets auto-demoted based on QA results.) Ballot status is driven by the `[standards-status]` entry. (Note that there's an alignment expectation between maturity and ballot status.) When relevant, 'normative date' is determined by the `[first-normative-version]` element Security category is managed under the `[security-categorization]` entry The "ANSI" section that indicates which 'package' a specification went normative as part of is captured as part of the `[normative-package]` entry.
Metadata	source/compartments.xml	N/A	This manages what Compartments the resource is listed as part of.
Definition	part of StructureDefinition-[resource].xml	Definition column of first row of Resource tab	The Definition for the overall resource is taken as the 'definition' of the root element of the resource.
Intro text	[resource]-intro.xml	N/A	This XHTML file defines all of the HTML content between the resource's definition and the paragraph that starts with "This resource is referenced by...". (That paragraph is auto-generated and driven by the publisher based on references to the resource declared elsewhere.). This will include the "Scope and Usage" and "Boundaries and Relationships" sections and may include others.
Data elements	part of StructureDefinition-[resource].xml	Resource, Bindings and Invariants tabs	All information about the individual data elements in the resource are managed here.
Terminology Bindings	part of StructureDefinition-[resource].xml	Bindings tab	Terminology bindings are managed by the 'binding' element within each ElementDefinition in the resource definition
	source/status-codes.xml	N/A	If the set of status codes for an element are changed, then the status codes listed in this 'mapping' table must also be updated.
	source/bindings.ini		You shouldn't need to maintain this file - it ought to be auto-generated on the definition of a new code systems. However, expect this file to change as new content is added (to generate numbers used in calculating OIDs).
	source/terminologies/bindings.xml		This file maintains a list of cross-resource bindings. I.e. bindings that appear on multiple resources. It is an Excel spreadsheet managed as an XML file (so open and maintain using Excel). You must run the build before committing the file.
	source/terminologies/valueset-*.xml		These are shared value sets referenced by the cross-resource bindings.xml file
	source/terminologies/codesystem-*.xml		These are shared code systems referenced by one of the shared value sets
(Special)	ValueSet*.xml	N/A	Value sets used in resource-specific bindings need to appear in the resource folder with a name driven by the value set URL (i.e. "ValueSet-x" where x is the id of the ValueSet which follows "ValueSet/" in the canonical URL.
(Special)	CodeSystem*.xml	N/A	Resource-specific code systems are defined directly in the resource folder. So long as the code system is referenced by a resource-specific value set. Again, the name of the code system must match the id.
Constraints	part of StructureDefinition-[resource].xml	Invariants tab	All of the constraints defined within the resource are managed here.
Usage notes	[resource]-notes.xml	N/A	This XHTML file defines all of the HTML content between the "Constraints" section and the "Search Parameters" section.
Search Parameters	bundle-[resource]-search-params.xml	Search tab	All search parameters are defined in a single bundle.
(Special)	[root]/fhir.ini	N/A	Any image, binary or other content that just needs to be propagated directly to the 'publish' folder (e.g. images or other hyperlinks referenced by 'introduction' or 'notes' content) nee
(Special)	.	N/A	Absolutely any file not covered above sitting in a resource folder that is listed in the fhir.ini file under 'images' or 'files' will automatically be propagated.

Adding new resources

Adding new resources is a complex process involving changes to many files. The full process is described Here

Renaming resources

Todo

Deprecating resources