FHIR Custom Resources

Custom resource policy

What is FHIR:

1. a framework for defining resources and using them restfully + a conformance framework for managing use
2. a set of resources that represent agreed content to support interoperability between systems

The first part - the infrastructure - may be useful to people for defining their own custom resources. A custom resource is a resource defined using the FHIR conformance resources - StructureDefinition, ValueSet, SearchParameter, and that conforms to all the rules expressed in the FHIR specification, and the FHIR Data types, and that can be used natively on the FHIR RESTful API, or in bundles, just like any other resource.

Why would you define your own resources?

• prototyping resources that will be brought to HL7 to be part of the specification
• using FHIR to do things HL7 hasn't or won't do (the space of all things to exchange is larger than the space of things HL7 can deal with)
• using FHIR outside Healthcare (not what we're about, but there has been some interest in this)

Obviously, only implementers that know the particular custom resources will be able to partake in exchange using the custom resources - so they will only be useful to a small community. These communities are variable in size - they might be a single company making use of FHIR within their own product, or a particular provider institution, or they may as large as national programs that wish to define their own content.

There's an obvious risk in having any community define their own content: it serves to divide the community - and many people have a legitimate concern that this division within the community will become a problem for users - they'll acquire products that are supposed to interoperate, and they won't, or FHIR will come to be associated with division and chaos. While HL7 will surely get the blame for this, refusing to cater for custom use just externalizes the cost of the fact that HL7 cannot impose consistency on the entire community of interest.

One particular concern is that implementers might use custom resources to exchange content instead of using the already defined FHIR resources - e.g. An implementer could use their own patient resource. As part of this policy then, it is explicitly noted that doing this is not a conformant use of the FHIR specification, and will not be made conformant.

This policy strives to strike a balance between allowing productive use of custom resources, while maintaining market confidence in FHIR as a standard.

How custom resources work, technically

To define a custom resource, an author must do the following:

• Define an ImplementationGuide resource. The narrative of the implementation guide contains a text description of the rationale for the custom resource(s) in the bundle
• the implementation guide contains a series of packages. Each package contains a structure definition that declares a custom resource along with one of more of the following supporting resources:
  • value sets and code system
  • structure maps
  • search parameters
  • compartment definitions

• the structure definition has a kind of "resource", and a baseType of "DomainResource", and a derivationKind of "specialization". For naming policy, see below. The canonical URL cannot start with "http://hl7.org/fhir/StructureDefinition". The id of the resource must be the same as the name

• in addition, the implementation guide package may contain 1 or more examples of the custom resource. These must be listed in the package *after* their structure definition and other terminology resources

The implementation guide and all the referenced resources may be packaged in a bundle, or stored in a repository

The Basic Resource

The FHIR Specification includes a resource called "Basic" that is introduced to serve in an extensibility role, and could be considered as an alternative to using custom resources. The key advantage of using Basic for extensibility is that it is supported by the schema and reference implementations without any of the difficulties associated with the use of custom resources. However experience with using the Basic resource has shown that while it works well for simple concepts, as the breadth and depth of the functionality associated with the concept and it's use grows, the Basic resource gets progressively more costly as a choice compared to the relatively flat costs of using a custom resource.

Implementers should consider using the Basic resource in preference to Custom resources when the information in the custom resource is fairly simple (e.g. no nested extensions).

Naming Policy

All resources are identified by a name which is the type of the resource. All these names come out of the same namespace, and are assigned by HL7 in accordance with this policy. HL7 manages the single namespace to ensure that there is no name collision between resource names.

Aside: why not use namespaces? - the XML format, the apparently logical thing to would be to use the namespace implicit in the canonical URL as the namespace of the XML. However there are many other circumstances - the JSON format, the URLs, generated code, etc, where there is no space for a namespace. For this reason, names are assigned from a single namespace

All names assigned under this policy are valid according to the id data type defined in the FHIR specification. This means that resource names may consist of 1-64 characters 'a'..'z', 'A'..'Z', '0'..'9', '-', and '.'. In addition, all custom resource names will include at least one character '-' or '.', while official resources defined in the FHIR specification will never include the characters '-' or '.' in their name.

Anyone wishing to use a custom resource must apply to HL7 for a name to use. Applications are made online at [address to be supplied]. (internal note: applications are processed by the HL7 CTO or the FHIR Product director in accordance with this document). Applicants may apply for a custom name, or for a prefix that they can use with any custom resource that they define.

Applications for a custom resource name must contain the following information:

• contact details for applicant (individual name, org name, email address)
• scope of the resource
• size of the community expected to use the resource
• desired/suggested name

Applications for a prefix must contain the following information:

• organization name, contact details, and type
• one or more individual contacts (name, email address)
• type of organization (SDO, open source community, company, consortium etc)
• how resources defined by the organisation under this prefix will be managed and published. (note: it is not required that content be balloted or published openly)
• statement of intent with regard to use of existing resources
• desired/suggested prefix

When applications are granted a prefix, it is their responsibility to manage the space within that prefix appropriately.

The list of approved names or prefixes will be published in an JSON file that lives at http://fhir.org/custom-resources.json

Note that the public servers should be expected to only support custom resources that conform to this policy.

Implementers may choose to simply define their own resources without conforming to this policy and registering the name. This is neither conformant, nor wise, in that they have problems with name clashes, or retrospectively needing to share the resources in a wider community. HL7 does not charge for custom names, nor does it apply editorial control over the use of the names.

Conformance

Note that existing conformant use of custom resources as described by this policy may become non-conformant because of later updates to the FHIR specification. Any implementers using custom resources are therefore required to keep close alignment with the specification as it goes forward.