This page describes the process for making use of Excel (or OpenOffice) spreadsheets to design and maintain FHIR data types, resources and profiles. If you haven't already, please read FHIR Guide to Authoring Resources or FHIR_Spreadsheet_Profile_Authoring for important contextual information on how to set up the build environment to make use of the spreadsheet you're about to edit, where to find the appropriate template, etc.

The use of spreadsheets to develop and maintain profiles is expected to be a near term solution with more sophisticated (and user-friendly) tooling currently under development. There are no plans to invest in similar enhanced tooling for authoring resources because there aren't going to be that many and they'll all be developed within HL7.

A single set of documentation has been provided because most of the tabs and columns are identical regardless of what type of artifact is being created or maintained. Where the rules don't apply everywhere, this page will flag the rule as Resource/Data Type-only or Profile-only.

Contents

Excel Spreadsheet

The Excel spreadsheet contains the main logical definitions of the resource, data type or profile. 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 (e.g. 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).

Some general notes on the formatting of the spreadsheet:

Additional notes:

Tabs

The Excel spreadsheet contains the following tabs:

NOTE: The order of the tabs is unimportant. Additional tabs can be added and (except as documented under Structure and Code List) will be are ignored. Extra tabs might be useful as play-spaces, locations for extra documentation, places to keep old versions, etc. Within each tab, 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. Rows must be contiguous - don't leave blank rows.

Metadata Tab

(Profile-only) This tab captures definitional information about the profile - who made it, what it's called, what it's for, etc. This information is not needed for resources and data types because they are not separately maintained and published. The metadata for all FHIR resources and data types is fixed.

Data Elements Tab

Resource/Data Type-only - required

This is the tab that defines the content of the data type or resource. Most of the columns used here can be found in the #Element Definition Columns which are shared across multiple tabs. There are, however, three additional columns:

Structure Tab

Profile-only - optional

When defining resources or data types, you'll use the Data Elements tab. When defining profiles, you'll use a "structure" tab (or possibly several structure tabs). Structures that are referenced from the metadata tab (as a "Published.structure") will appear as "published" structures that are externally referencable. Those that are not referenced from the metadata tab (but only from other structures) will show up as "non-published". Structure tabs that are not reachable by traversing references from one of the published structures will be ignored.

The name of a Structure is the name of the structure tab. The maximum length of an Excel tab name is 31 (go figure). Because an invariant tab will need to be associated with the structure and the invariant tab name is "[structureName]-Inv", that means that structure names need to be 27 characters or less.

Most of the columns used here can be found in the #Element Definition Columns which are shared across multiple tabs. There are, however, a few additional columns:

Note: While columns might be generally marked as "required", most of these rules are ignored when profiling elements as the definitions are expressed in differential mode. This means that only the Element column and those columns that are being overridden within the context of the profile need to be present in the spreadsheet. Note that though validation rules won't be enforced by the spreadsheet, they still need to be respected. For example, declaring a fixed value if the inherited type includes a choice of multiple data types is still not allowed, even though the data type element might be blank in the profile (because you're inheriting from the resource or an ancestor profile.)

Extensions Tab

Extensions are defined on the Extensions tab. Most of the columns used here can be found in the #Element Definition Columns which are shared across multiple tabs. There are, however, a few additional columns:

The following is an example of the definition of a complex extension:.


codeContext TypeContextCard.
complexExtensionResourceSomeResource.element0..1
complexExtension.node1

1..1
complexExtension.node2

0..*

Element Definition Columns

Invariants Tab

This tab defines constraints that apply to a resource (or to one of the structures defined within a profile. All constraints defined must be evaluatable within the context of the instance, not taking into account any external state information (date, previously received data, other resources, etc.)

Search Tab

In resources, there's a single Search tab. In profiles, there can be a search tab for each structure (with the tab name [profilename]-search)

The Search tab contains the search operations for a resource or supplemental search operations based on extensions. 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:

Operations Tab

The Operations tab defines operations related to the resource as well as their parameters.

The rows of this tab are used for both defining operations as well as parameters. The first row (below the heading row) must define an operation. Subsequent rows define the parameters for that operation. Then a second operation can be defined, etc.

For "operation definition" rows, the following columns are used:

For "operation parameter definition" rows, the following columns are used:

Events Tab

The use of the Events tab (for defining messaging events) is currently incomplete. If you need to use it, please discuss with the FHIR tooling team (post to the Committers list).

Packages Tab

The Packages tab lists all conformance packages (combinations of structure, extension and/or search criteria definitions) that are associated with the current resource (or data type). This allows the profiles associated with a given resource for linkage in the publication. "Related" means defining extensions, search criteria or structures for the resource/data type.

The tab can contain the following columns:

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:

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. Bindings may be used in multiple resources, data types and/or profiles, but should only be defined in one spreadsheet.

This tab contains the following columns:

Notes:

Code list tab

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: