FHIR Custom Resources

Changes:

• update for removal of IG package - just flat
• document $activate/$deactivate
• only issue prefixes, always use prefix- (= FHIRPath same name)
• HL7 published IGs (including by affiliates) can only use custom resources with FMG approval
• refine rules about id,name,canonicalUrl
• document use in fhirpath (switch "-" to "." for type specifier - prefix = namespace)
• HL7 can define custom resources without a prefix (fhirpath type system is "FHIR")

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, and there has been a lot of interest in doing so. This page documents the FHIR Community policy for custom resources (and is a candidate for elevation into the specification)

Definition of Custom Resource

A custom resource is any 'resource' not defined in the specification that is used in one of the following places:

• referred to in Conformance.rest.resource.code or ElementDefinition.type.code
• referred to from a resource reference
• included directly in DomainResource.contained, Bundle.entry.resource, and Parameters.parameter.resource

Implementers may choose to allow additional resources not defined in the specification to be used in one of these places. These are described as 'Custom Resources' and this policy applies to their use.

Note that this policy does not apply to other entities that a server supports e.g. SCIM or oData resources - these are not affected by this policy.

A custom resource must be defined using the FHIR conformance resources - StructureDefinition, ValueSet, SearchParameter, and must conform to all the rules expressed in the FHIR specification about how these resources and the associated implementations work.

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 one or more custom resources.

For each custom resource, there is a structure that defines it, with the rules that:

• the structure definition has a kind of "resource"
• the baseDerivation is http://hl7.org/fhir/StructureDefinition/DomainResource
• the derivation kind is "specialization"
• The canonical URL cannot start with "http://hl7.org/fhir/StructureDefinition"
• The name of resource must be in StructureDefinition.type, and must also be the tail of the canonical URL
• for rules around Custom resource names, see below

In addition to the base definition, the implementation guide may also have:

• Search parameters (matching in SearchParameter.base)
• value sets and code systems that are used in the definition of the custom resource
• 1 or more examples of the custom resource

Note: there is no support in the FHIR specification for Custom Data Types, and custom resources cannot use any data types other than those defined in the FHIR specification.

Why use Custom Resources?

These are reasons to use custom 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)

Limitations of Custom Resources

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.

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.