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 lower camel case name [name], and an upper camel-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
• one or more [name]-(whatever)-example.xml which is an example of the resource (refer to #Example Elements Tab for guidance on naming example files.

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. test and make sure your local copy of the build process completes without errors (so that if something breaks, you can be condident it's your fault . . .)
2. create the directory [name] in the source directory
3. copy /template/template-spreadsheet.xml to /[name]/[name]-spreadsheet.xml (and open it, and replace "Template" in the first column of the Data Elements tab with [Name])
4. copy /template/template-html.xml to /[name]/[name]-notes.xml and /[name]/[name]-introduction.xml
5. copy /template/template-example.xml /[name]/[name]-example.xml
6. add the new directory and its files to SVN
7. 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
8. edit /heirarchy.xml and add your page under the correct place within the site's navigation
9. open /compartments.xml with Excel and indicate which elements can be used to place the resource in a Patient or Practitioner compartment (or leave empty if N/A)
10. add your resource to /resourcelist.html (both in the right category and under the right caption letter)
11. add a translation for your resources name to implementations/translations.xml
12. for some special resources, you may need to register the resource in /navigation.xml. But not for normal resources.
13. test and make sure the build completes without errors
14. commit all changes to SVN

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. It's even possible to use a text editor, though 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-occurrence 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 by the build process. Additional rows other than those containing the defined contents cannot be added.

Examples Tab

The Examples Tab lists the details for example files for a resource. If the tab does not hold any references to examples, the resource's source directory will be search for a file ending in "{resourcename}-example.xml" and this file is then used as an example instead.

The tab can contain the following columns:

• "Name", A string, may not be empty.
• "Identity", a string.
• "Type", a choice. Allowed values are:
  • (empty) or "xml"
  • "csv"
  • "tool"
• "Description", a string, may not be empty.
• "Filename", a string, may not be empty.
• "In Book", a boolean.

Search Tab

The Search tab contains the search operations for a resource. The standard search operations $page, $count and $id do not need to be specified, but are added automatically.

The Search Tab has the following columns:

• "Name", a string. May not end in "-before" or "-after", these suffixes are automatically added for time-based searches.
• "Description", a string.
• "Type", a choice. Allowed values are:
  • "integer"
  • "string"
  • "text"
  • "date"
  • "token"
  • "qtoken"
• "Repeats", a choice. Allowed values are:
  • "single"
  • "union"
  • "intersection"

Bindings Tab

The Binding tab contains the definition of the Bindings as mentioned in the definition of the data elements. The Binding column in the Data Elements Tab refers to the Binding Name.

This tab contains the following columns:

• "Binding Name", a string. Must begin with an Uppercase letter
• "Definition", a string
• "Binding", a choice. Allowed values are:
  • (empty) or "unbound" - this will be phased out soon
  • "code list" - an internal reference to a different tab, which enumerates a simple list of codes
  • "special" - used for infrastructural things by the project team. (usually bound to schema)
  • "reference" - a direct reference to an external standard (usually an RFC) (not bound to schema. typical examples: language, mime type)
  • "value set" - the name of a file in the same directory as the spreadsheet that has the value set for the attribute
• "Example" - to indicate the the value set binding is an example. only used with "value set" bindings
  • valid values "y" or blank
• "Reference", a string - either #[tab-name], or [valueset-file-name] or [http url] - use depends on the binding column
• "Description", a string used when the reference is rendered for reference bindings
• "v2" - the URI of a value set in v2 that the codes are mapped to (binding = code list only). see http://hl7.org/implement/standards/fhir/terminologies-v2.htm for valid values
• "v3" - the URI of a value set in v3 that the codes are mapped to (binding = code list only). see http://hl7.org/implement/standards/fhir/terminologies-v3.htm for valid values

Notes:

• if the data type is "code", you must choose either code list, special, or reference
  • the code choices will be bound by schema. You are allowed to define your own codes in this case, and they are subject to ballot
• if the data type is "coding" or "codeableConcept" you must choose "code list" or "value set" unless the core project team agrees otherwise (can't think of any cases for this)
  • a code list is just converted in a value set reference - it's a cheap and limited way to do an enumeration. Support for this will be removed in the future.
  • whether you use code list or value set, the value set should consist of codes defined elsewhere. Internal codes should not be defined unless suitable codes don't exist elsewhere, and use cases for this should be discussed with the core project team. In principle, these codes are required to be under either harmonisation or external authority

In case the Binding is of type "code list", the column "Reference" must contain the name of another tab containing the valueset for this binding, prefixed by '#'. This tab contains the following columns:

• "Id", a number - used for internal references to create subsumption heirarchies
• "System", a string - used to refer to codes from external systems (use the URI published in the FHIR ballot. if the URI is not published, consult the core project team)
  • note: provide either an ID or a system, but not both
• "Code", a string - the code that identifies the concept
• "Display", a string - do not provide "display" for internal codes that are going to be bound in schema. If the code is external, you *should* provide a display so the publishing tools can publish one for user convenience
• "Definition", a string - mandatory if the code is an internal code. Recommended if the code is external, so the tools can publish it for use convenience
• "Comment", a string - optional. usage guidance.
• "v2" and "v3" - v2 and v3 mappings, if there are mappings defined in the bindings tab (else ignored)
  • the syntax consists of a set of map statements, separated by "," (no spaces)
  • a map statement consists of a single character equivalence, then the table number of code system name, then a ".", and then the code, optionally with a comment in brackets following
  • the equivalent character is "=" - exact. "~" - equivalent. ">" - narrower (i.e. the v2/v3 code is narrower than the FHIR code). "<" - wider
  • e.g. ~0190.H - this code is equivalent to "H" in table 0190
  • e.g. >EntityNameUse.BAD(not sure about old) - this code maps to "BAD" in EntityNameUse, but the definition of "BAD" is narrower. the comment is an explanation of the issue (probably shouldn't be as cryptic as this comment). When you use the equivalence "<", you must make a comment