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 resources. 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 disadvantage 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

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, and 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 implemnetation 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

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

Users or systems creating instances of custom resources cannot claim to be conformant with FHIR. Instead, they can only claim to be conformant to "Custom-FHIR"