FHIR Guide to Authoring Resources

This is the technical documentation that describes what you do to author a resource that will be part of the FHIR specification. There is a also a Design Guide that addresses how resources should be designed.

Note: before attempting to author resources, you must be able to successfully run the FHIR build process.

Background

All FHIR resources have both a lowercase name [name], and an title case name [Name]. Each resource has a sub-directory [name] in the source folder of the FHIR svn hierarchy, which contains all the files related to the resource. The build process looks for the following files:

• an excel spreadsheet [name]-spreadsheet.xml that defines the content and behavior of the resource
• several xhtml files that allow additional text documentation to be added for the resource
  • [name]-notes.xml - text documentation that goes below the formal resource definition on the resource page
  • [name]-introduction.xml - text documentation that goes above the formal resource definition on the resource page
  • others yet to be documented
• [name]-example.xml which is an example of the resource

Only the first file must exist, though at least one example must exist. Managing examples is discussed further below.

Creating a new resource

Creating a new resource is only done by the FHIR project team once a new resource has been proposed and accepted. This section documents the process that the project team follows. paths are relative to the source directory.

1. create the directory [name] in the source directory
2. copy /template/template-spreadsheeet.xml to /[name]/[name]-spreadsheet.xml (and open it, and replace "Template" in the first column of the Data Elements tab with [Name])
3. copy /template/template-html.xml to /[name]/[name]-notes.xml and /[name]/[name]-introduction.xml
4. copy /template/template-example.xml /[name]/[name]-example.xml
5. edit /fhir.ini
   1. add [name]=[Name] to the [resources] section
   2. add [name]={desc} to the [status] section. desc is agreed as part of the resource proposal
6. for some special resources, you may need to register the resource in /navigation.xml. But not for normal resources

Excel Spreadsheet

The Excel spreadsheet contains the main logical definitions of the resource. In order to support version control, and other forms of text processing, the spreadsheet is stored as an XML document. In excel, this format is chosen by saving as an XML Spreadsheet 2003. Any other software that can edit this format (i.e. OpenOffice) can also be used, or a text editor can be used, but this is not recommended. (Note: the project team is not committed to excel. Alternatives can be considered, as long as the same logical content can be defined).

The excel spreadsheet contains the following tabs:

• Data Elements - defines the actual contents of the resource
• Invariants - documents additional rules about the resource such as co-occurence constraints
• Events - defined messaging events for the resource
• Search - defined search parameters for the restful interface
• Examples - define multiple examples for the resource
• Bindings - vocabulary bindings for the resource contents

The order of the tabs is not important, and other tabs can be defined. Except as documented below, other tabs are ignored. In addition, for every page, additional columns can be defined at the discretion of the editor; they will be ignored. Additional rows other than those containing the defined contents cannot be added.