FHIR Guide to Authoring Types

This is the technical documentation that describes what you do to author a shared type that will be part of the FHIR specification. Shared types are useful for defining structures that are used across multiple resources, but should only be defined when there is a clear benefit to doing so that offsets the additional maintenance and complexity of a base type.

Note: before attempting to author shared types, you MUST be able to successfully run the FHIR build process. You must also sign up to the FHIR Committers Skype chat (contact an FMG member or other known FHIR developer to get added).

Background

FHIR Shared types are defined similarly to FHIR resources, and you should be familiar with the process for authoring resources before attempting to author shared types.

Creating a new shared type

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

Note: talk to Grahame before following this process. This documentation was added by Bryn (thanks!) after following the process, but there's variations to it to plan.

1. test and make sure your local copy of the build process completes without errors (so that if something breaks, you can be confident it's your fault . . .)
2. add the base description of the type to the "source/datatypes" folder
   1. copy /template/template-spreadsheet.xml to /source/datatypes/[name].xml
   2. open it and replace "[ResourceOrDataTypeName]" in the first column of the Data Elements tab with [Name]
   3. change the value of the Type column to "Type" instead of "DomainResource"
3. copy /template/template-html.xml to /source/datatypes/[name]-notes.xml and /source/datatypes/[name]-introduction.xml
4. copy /template/template-example.xml /source/datatypes/[name]-example.xml
5. Add the source html pages for the type to the "source" folder
   1. See elementdefinition or modulemetadata for examples
      1. [name].html
      2. [name]-definitions.html
      3. [name]-mappings.html
      4. [name]-examples.html
   2. Change the content and processing tags in these pages as appropriate
      1. ElementDefinition uses "edheader", ModuleMetadata uses "mmheader"
      2. Tags are processed in PageProcessor:
         1. tools/java/org.hl7.fhir.tools.core/src/org/hl7/fhir/tools/publisher/PageProcessor.java
6. Add the type to /fhir.ini in the following sections:
   1. add [name] to the [shared] section
   2. add [name]=[name] to the [type-pages] section
   3. add [name]=committee to workgroups section
   4. add [Name]=tla the tlas section
7. edit /heirarchy.xml and add your page under the correct place within the site's navigation
8. Add the type pages to /publish.ini in the [pages] section:
   1. [name].html=
   2. [name]-definitions.html=
   3. [name]-mappings.html=
   4. [name]-examples.html=
9. test and make sure the build completes without errors
10. commit all changes to SVN

Editing a FHIR shared type

Instructions for how to make use of the FHIR resource spreadsheet can be found here. Instructions on using the notes and introduction HTML pages are embedded as comments within the XHTML templates. If you run into issues, ask a question on the FHIR Committers list.