|
|
| (19 intermediate revisions by 7 users not shown) |
| Line 4: |
Line 4: |
| | 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 [[FHIR Guide to Designing Resources|Design Guide]] that addresses how resources should be designed. | | 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 [[FHIR Guide to Designing Resources|Design Guide]] that addresses how resources should be designed. |
| | | | |
| − | <b>Note: before attempting to author resources, you MUST be able to successfully [[FHIR Build Process|run the FHIR build process]].</b> | + | <b>Note: before attempting to author resources, you MUST be able to successfully [[FHIR Build Process|run the FHIR build process]]. You must also sign up to the FHIR Committers Zulip chat at https://chat.fhir.org/#narrow/stream/committers |
| | | | |
| | == Background == | | == 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: | + | All FHIR resources have both a lower case name [name], and a Pascal-case name [Name]. For example, for the StructureDefinition resource, the lower case name is structuredefinition and the Pascal-case name is StructureDefinition. Each resource has a sub-directory [name] in the source folder of the FHIR git repository, 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 | | * an excel spreadsheet [name]-spreadsheet.xml that defines the content and behavior of the resource |
| Line 17: |
Line 17: |
| | * 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. | | * 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. | + | 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== |
| Line 23: |
Line 23: |
| | 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. | | 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. |
| | | | |
| − | # 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 . . .) | + | # 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 . . .) |
| | # create the directory [name] in the source directory | | # create the directory [name] in the source directory |
| − | # 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]) | + | # copy templates/template-spreadsheet.xml to [name]/[name]-spreadsheet.xml |
| − | # copy /template/template-html.xml to /[name]/[name]-notes.xml and /[name]/[name]-introduction.xml | + | ## open it and replace "[ResourceOrDataTypeName]" in the first column of the Data Elements tab with [Name]) |
| − | # copy /template/template-example.xml /[name]/[name]-example.xml | + | ## select an appropriate w5 category (e.g. clinical.general) (see source/w5.ini for a list of categories) |
| − | # add the new directory and its files to SVN | + | # copy templates/template-notes.xml to [name]/[name]-notes.xml |
| − | # edit /fhir.ini | + | # copy templates/template-introduction.xml to [name]/[name]-introduction.xml |
| | + | # copy templates/template-example.xml [name]/[name]-example.xml |
| | + | # add the new directory and its files to git |
| | + | # edit fhir.ini |
| | ## add [name]=[Name] to the [resources] section | | ## add [name]=[Name] to the [resources] section |
| − | # edit /heirarchy.xml and add your page under the correct place within the site's navigation | + | ## add [name]=committee to workgroups section |
| − | # 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) | + | ## add [name]=0 to fmm section |
| − | # add your resource to /resourcelist.html (both in the right category and under the right caption letter) | + | ## add [Name]=tla the tlas section |
| | + | # edit heirarchy.xml and add your page under the correct place within the site's navigation |
| | + | # open compartments.xml with Excel and specify which search parameters can be used to place the resource in a Patient or Practitioner compartment (or leave empty if N/A) |
| | + | # if your resource has an element named "status", open status-codes.xml with Excel and add the appropriate mappings to the status. Use other resources in the same category (definition, request, event) as a pattern for the mappings. |
| | + | # add your resource to resourcelist.html and /resourceguide.html (both in the right category and under the right caption letter) |
| | + | # add your resource as appropriate in source/administration-module.html, source/clinicalreasoning-module.html, source/clinicalsummary-module.html, source/conformance-module.html, source/diagnostics-module.html, source/financial-module.html, source/foundation-module.html, source/implsupport-module.html, source/medication-module.html, source/ontology-module.html, source/secpriv-module.html, source/terminology-module.html, and/or source/workflow-module.html |
| | # add a translation for your resources name to implementations/translations.xml | | # add a translation for your resources name to implementations/translations.xml |
| − | # for some special resources, you may need to register the resource in /navigation.xml. But not for normal resources. | + | # edit the example to fill out the [Name] on the base node and add a <id value="xxx"/> where xxx is what you're going to call the example (usually "example") |
| | # test and make sure the build completes without errors | | # test and make sure the build completes without errors |
| − | # commit all changes to SVN | + | # commit all changes to a git branch, push to GitHub, and create a Pull Request (see https://github.com/hl7/fhir/wiki/Get-Started-with-FHIR-on-GitHub]). |
| | | | |
| − | == Excel Spreadsheet == | + | == Editing a FHIR resource== |
| − | | + | Instructions for how to make use of the FHIR resource spreadsheet can be found [[FHIR Spreadsheet Authoring | 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. |
| − | 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
| |
| − | * '''Bindings''' - vocabulary bindings for the resource contents
| |
| − | * '''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
| |
| − | * '''Profiles''' - identifies any profiles that should be listed as associated with this resource
| |
| − | | |
| − | '''NOTE''': The order of the tabs is not important, and other tabs can be defined. Except as documented below, other tabs are ignored. In addition, 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.
| |
| − | | |
| − | === Data Elements Tab ===
| |
| − | | |
| − | *'''Element''': Required - string. This defines the full-path name for the element row. Nodes within the path are separated by ".". E.g. ''Patient.contact.name''. Rows must be listed in the order they will appear in the instance. The first row will be the name of the resource or data type. Subsequent rows will be prefixed with the resource name. I.e. All elements listed in a given spreadsheet tab will start with the same prefix.
| |
| − | *'''Card.''': Required. This indicates the minimum and maximum number of repetitions allowed for the element. For resources, this is constrained to 0..1, 0..*, 1..1 or 1..*. For profiles, any cardinality may be specified, so long as it is a proper constraint on the underlying resource. To prohibit an element, use 0..0. Please refer to the [[TODO methodology guidelines for cardinalities]] before constraining.
| |
| − | *'''Inv.''': Optional. This is a reference to an invariant that governs the appearance of this element. (I.e. whether the element is allowed to be present or not). It must be one of the values in the "id" column from the [[#Invariants_Tab]]. If multiple invariants apply to a single element, they can be separated with ",".
| |
| − | *'''Is Modifier''': Optional. This indicates whether the element is considered to change the meaning of other elements in the resource/data type. It must be either "Y" or "N". If unspecified, it will be defaulted to "N" by the tool.
| |
| − | *'''UML''': Optional. This overrides the default placement of the element in the UML layout. It can only be specified on "complex" elements (those without a declared type). The format is "x;y", where "x" is the horizontal coordinate in pixels and the "y" is the vertical coordinate in pixels. (The general methodology is play around with values and keep re-generating until the diagram looks the way you want it to.)
| |
| − | *'''Type''': Conditional. This indicates the data type(s) for this particular element. It must be omitted for complex types (those where the following element is nested inside the current element). It must be present for simple types. The type is one of the allowed data types. For resource references, the allowed type of resource may be constrained by listing the allowed resources in following brackets. E.g. "Resource(Patient|Practitioner)". Multiple types can also be specified by separating values with vertical bars. E.g. "string | integer | CodeableConcept | Resource(Patient | Practitioner)". If the data type is unrestrained, simply specify "*" which allows all possible types.
| |
| − | *'''Binding''': Conditional. This must be specified for any data element that allows a type of code, Coding or CodeableConcept (including "*"). It should not be present for other elements. It must refer to a Binding name from either the [[#Bindings Tab]] in the current spreadsheet or one of the other resource spreadsheets. (Note - the order in which resources are first loaded into memory is controlled by the ''build/source/fhir.ini'' file. Resources that define bindings must be listed before other resources that use them.
| |
| − | *'''Short Name''': Optional. This is the definition that appears in the XML form as a comment guiding the implementer. If the data type is ''code'', the short name *must* be in the form "code1 | code2 | code 3 . . . .". If there are more than 5-6 codes, list the first 5 or 6 and then add a "+". E.g "code5 | code6 +". The short name can be ommitted if there's absolutely *nothing* useful that can be said to expand on the meaning of the element name, but usually something should be provided, even if just an example or two. The short name should generally be 50 characters or less.
| |
| − | *'''Definition''':Required. This is the full definition of the element. It should not be redundant with either the element name or short name. Examples should be given, if appropriate. This element may be expressed using [[TODO mark down]] to allow hyperlinking to other elements in the specification, including bullets and other formatting.
| |
| − | *'''Aliases''': Optional. This is a list of semi-colon separated alternate names for the element. These might be realm-specific or domain-specific or just other common-practice names used in industry. The names here need not have identical scope. The objective is to ensure that someone looking for the resource or an element in the resource will be able to find the appropriate name by matching on an alias.
| |
| − | *'''Summary''': Optional. This indicates whether the element should be included in a query response for which "summary" elements have been requested. It must be set to either "Y" or "N". (The tool will default it to "N" if omitted.)
| |
| − | *'''Requirements''': Optional. This provides explanation about why the resource, data type or data element within the resource/data type is necessary and/or why it has been constrained as it has. It is optional - only fill it in if the requirements won't be obviousto those with minimal industry experience. (E.g. No need to explain why there's a "name" element on Patient, but Patient.multipleBirth[x] should probably have some explanation.) This element may be expressed using [[TODO mark down]] to allow hyperlinking to other elements in the specification, including bullets and other formatting.
| |
| − | *'''Comments''': Optional. This element provides additional usage notes associated with the element that are not definitional in nature and don't belong in requirements. These should be element-specific. Usage notes that apply across elements or that span more than a couple of paragraphs should be handled in the usage notes HTML file for the overall resource. This element may be expressed using [[TODO mark down]] to allow hyperlinking to other elements in the specification, including bullets and other formatting.
| |
| − | *'''V3 Mapping''': Conditional. This contains the mapping of the resource, data type or element to the V3 RIM. The resource level must always be specified, though it can be set to "N/A". If not set to "N/A", all subsequent elements must also be specified, though some of those may also be expressed as "N/A". If present, mappings are generally expressed as pseudo-xpaths. E.g. "Observation[classCode=OBS, moodCode=EVN]". Mappings are expressed relative to the parent element. They are intended for human understandability purposes, not for automated processing or mapping.
| |
| − | *'''V2 Mapping''': Conditional. This contains the mapping of the resource, data type or element to the V2 specification (most current release). The resource level must always be specified, though it can be set to "N/A". If not set to "N/A", all subsequent elements must also be specified, though some of those may also be expressed as "N/A". If present, mappings are generally expressed in dot notation. E.g. PID.3.1 They are intended for human understandability purposes, not for automated processing or mapping.
| |
| − | *'''xx Mapping''': Optional. Additional mapping columns may also be added. The set of allowed mappings and guidance on required column headings and mapping format is defined in the ''build/source/mappingSpace.xml'' file.
| |
| − | *'''To Do''': Optional. This column is for work group convenience. It does not propagate to the resource XML definition nor into the specification. We may cause warnings to be spit out for resources that claim to be at DSTU-level with content in this column.
| |
| − | *'''Committee Notes''': Optional. This column is for work group convenience. It does not propagate to the resource XML definition nor into the specification. It might include design notes not intended for publication
| |
| − | | |
| − | === 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.)
| |
| − | | |
| − | * '''Id''': This is a unique identifier for the constraint within the Resource/Data Type/Profile. It is used to reference the constraint from data elements whose appearance is controlled by the constraint (if any).
| |
| − | * '''Name''': This is a short descriptive name for the constraint. It is used in OCL, Schematron and certain other technologies to display information about the constraint
| |
| − | * '''Context''': This indicates the scope (or scopes) in which the constraint should be applied. For data types or resources, this should be the full element path name. E.g. ''Patient.contact.name''. For extensions, this should be the full URI of the extension (i.e. the base URI + "#" plus the extension code.) The context determines what the root node is when evaluating the XPath or other formal expression of the constraint.
| |
| − | * '''English''': This is the human-friendly expression of the constraint. It should ideally be appropriate to expose to the end-user (human) of an interacting system.
| |
| − | * '''OCL''': This is the formal expression of the constraint in OCL. It is not generally being populated at this time.
| |
| − | * '''XPath''': This is the formal expression of the constraint expressed using XPath 2.0. If you're not familiar with XPath 2, ask Lloyd to write it for you . . .
| |
| − | | |
| − | === 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:
| |
| − | * '''Binding Name''', a string. Must begin with an Uppercase letter. Must be unique across the FHIR specification
| |
| − | * '''Definition''', a string
| |
| − | * '''Binding''', a choice. Allowed values are:
| |
| − | ** "unbound" - This should only be used when example codes from an external terminology do not exist and none of the others apply. (This should be VERY rare.)
| |
| − | ** "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
| |
| − | | |
| − | ===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:
| |
| − | * '''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
| |
| − | | |
| − | === Events Tab ===
| |
| − | === 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"
| |
| − | | |
| − | === 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.
| |
| − | | |
| − | === Profiles Tab ===
| |
| − | The Profiles tab lists all profiles that are associated with the current resource (or data type) <!-- TODO (or profile) -->. 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:
| |
| − | * ''''''
| |
