Implementation Note: This is not the complete set of FHIRPath extensions for FHIR. Most extensions remain defined in the core R6 specification, only a subset was extracted for potential further refinement.

The Terminology Service API is more mature and has some implementation support.
The Type Factory has seen minor/partial implementation. The base FHIRPath specification, published in STU3, supports native structure creation in a more natural way, and we are seeking implementer feedback on whether some of these functions should be removed.
The General Service API has not seen any implemenation as yet.

Terminology Service API

In order to support terminological reasoning in FHIRPath statements, FHIR defines a general %terminologies object that FHIRPath implementations should make available. Calls to this object are passed through a standard FHIR terminology service.

Summary:

%terminologies : TerminologyServer // default terminology server (application controls context)
%terminologies.at(url) : TerminologyServer // terminology server at specified address

%terminologies.expand(valueSet, params) : ValueSet
%terminologies.lookup(coded, params) : Parameters
%terminologies.validateVS(valueSet, coded, params) : Parameters
%terminologies.validateCS(codeSystem, coded, params) : Parameters
%terminologies.subsumes(system, coded1, coded2, params) : code
%terminologies.translate(conceptMap, code, params) : Parameters

For all these functions, if any of the parameters are empty, or a collection with more than one value, or one or more of the parameters are not valid, the return value is empty.

---

%terminologies.at(url) : TerminologyServer

Get a terminology server object pointing at a particular server. Note: The %terminologies object points to the default terminology server as specified by the application evaluating the FHIRPath.

Parameters:

• url: A URL that points to a FHIR RESTful API.

Return Value: A terminology server that points at the specified URL. No errors - they will come when/if the terminology server object is used.

---

%terminologies.expand(valueSet, params) : ValueSet

This calls the Terminology Service $expand operation (formal definition).

Parameters:

• valueSet: either an actual ValueSet, or a canonical URL reference to a value set.
• params: a URL encoded string with other parameters for the expand operation (e.g., 'displayLanguage=en&activeOnly=true')

Return Value: a ValueSet with an expansion. If an error occurs, the return value is empty.

---

---

%terminologies.lookup(coded, params) : Parameters

This calls the Terminology Service $lookup operation (formal definition).

Parameters:

• coded: either a Coding, a CodeableConcept, or a resource element that is a code
• params: a URL encoded string with other parameters for the lookup operation (e.g., 'date=2011-03-04&displayLanguage=en')

Return Value:

---

%terminologies.validateVS(valueSet, coded, params) : Parameters

This calls the Terminology Service $validate-code operation on a value set (formal definition).

Parameters:

• valueSet: either an actual ValueSet, or a canonical URL reference to a value set.
• coded: either a Coding, a CodeableConcept, or a resource element that is a code
• params: a URL encoded string with other parameters for the validate-code operation (e.g., 'date=2011-03-04&displayLanguage=en')

Return Value: A Parameters resource with the results of the validation operation.

---

%terminologies.validateCS(codeSystem, coded, params) : Parameters

This calls the Terminology Service $validate-code operation on a code system (formal definition).

Parameters:

• codeSystem: either an actual CodeSystem, or a canonical URL reference to a code system.
• coded: either a Coding, a CodeableConcept, or a resource element that is a code
• params: a URL encoded string with other parameters for the validate-code operation (e.g., 'date=2011-03-04&displayLanguage=en')

Return Value: A Parameters resource with the results of the validation operation.

---

%terminologies.subsumes(system, coded1, coded2, params) : code

This calls the Terminology Service $subsumes operation (formal definition).

Parameters:

• system: the URI of a code system within which the subsumption testing occurs
• coded1: A Coding or a resource element that is a code
• coded2: A Coding or a resource element that is a code
• params: a URL encoded string with other parameters for the validate-code operation (e.g., 'version=2014-05-06')

Return Value: a code as specified for the subsumes operation.

---

%terminologies.translate(conceptMap, coded, params) : Parameters

This calls the Terminology Service $translate operation (formal definition).

Parameters:

• conceptMap: either an actual ConceptMap, or a canonical URL reference to a value set.
• coded: The source to translate: a Coding or a resource element that is a code
• params: a URL encoded string with other parameters for the validate-code operation (e.g., 'source=http://acme.org/valueset/23&target=http://acme.org/valueset/23')

Return Value: A Parameters resource with the results of the translation operation.

Type Factory

The variable %factory is a reference to a class factory that provides the following type methods. Note that a future version of FHIRPath may provide a factory framework directly, in which case this factory API may be withdrawn or deprecated.

This API provides specific methods for constructing common types, and some general methods for constructing any type.

For the specific type constructors, all the parameters are optional. Note that since all variables / outputs in FHIRPath are collections, all the parameters are inherently collections, but when the underlying element referred to is a singleton element, the collection cannot contain more than one item. Use the value {} if there is no value to provide.

---

%factory.{primitive}(value, extensions) : {primitive}

Create an instance of the type with the value and possibly one or more extensions. e.g., %factory.code('final').

Parameters:

• value: a primitive type (string, or will be converted to a string if necessary) that contains the value for the primitive type.
• extensions: a collection of extensions for the primitive type

Return Value: the primitive type, or an error.

---

%factory.Extension(url, value) : Extension

Creates an extension with the given url and value: %factory.extension('http://hl7.org/fhir/StructureDefinition/artifact-copyrightLabel', 'CC0-1.0').

Parameters:

• url: a string value that identifies the extension
• value: the value of the extension (any valid type for extension.value[x]

Return Value: An extension with the specified properties.

---

%factory.Identifier(system, value, use, type) : Identifier

Creates an identifier with the given properties: %factory.Identifier('urn:ietf:rfc:3986', 'urn:oid:1.2.3.4.5', 'official').

Parameters:

• system: a string value that goes in Identifier.system
• value: a string value that goes in Identifier.value
• use: a string value that goes in Identifier.use
• type: a CodeableConcept that goes in Identifier.type

Return Value: An identifier with the specified properties .

---

%factory.HumanName(family, given, prefix, suffix, text, use) : HumanName

Create a human name with the given properties: %factory.HumanName('Smith', 'Julia', {}, {}, 'Julia Smith').

Parameters:

• family: a string value that goes in HumanName.system
• given: a collection of string values that goes in HumanName.given
• prefix: a string value that goes in HumanName.prefix
• suffix: a string value that goes in HumanName.suffix
• text: a string value that goes in HumanName.text
• use:a string value that goes in HumanName.use

Return Value: a HumanName.

---

%factory.ContactPoint(system, value, use) : ContactPoint

Creates a ContactPoint: %factory.ContactPoint('email', 'coyote@acme.com', 'work')

Parameters:

• system: a string value that goes in ContactPoint.system
• value: a string value that goes in ContactPoint.value
• use: a string value that goes in ContactPoint.use

Return Value: a ContactPoint.

---

%factory.Address(line, city, state, postalCode, country, use, type) : Address

Creates an Address: %factory.Address('5 Nowhere Road', 'coyote@acme.com', 'EW', '0000', {}, 'home', 'physical')

Parameters:

• line: a collection of string values that goes in Address.line
• city: a string value that goes in Address.city
• state: a string value that goes in Address.state
• postalCode: a string value that goes in Address.postalCode
• country: a string value that goes in Address.country
• use: a string value that goes in Address.use
• type: a string value that goes in Address.type

Return Value: An address.

---

%factory.Quantity(system, code, value, unit) : Quantity

Creates a Quantity: %factory.Quantity('http://unitsofmeasure.org', 'mg/dL', '5.03', 'mg/dL')

Parameters:

• system: a string value that goes in Quantity.system
• code: a string value that goes in Quantity.code
• value: a string or decimal value that goes in Quantity.value
• unit: a string value that goes in Quantity.unit

Return Value: a Quantity.

---

%factory.Coding(system, code, display, version) : Coding

Creates a Coding: %factory.Coding('http://loinc.org', '1234-5, 'An example test', '1.02')

Parameters:

• system: a string value that goes in Coding.system
• code: a string value that goes in Coding.code
• display: a string value that goes in Coding.display
• version: a string value that goes in Coding.version

Return Value: A coding.

---

%factory.CodeableConcept(coding, text) : CodeableConcept

Creates a CodeableConcept: %factory.CodeableConcept(%factory.Coding(...), "Example Test")

Parameters:

• coding: a collection of Coding that goes in CodeableConcept.coding
• text: a string value that goes in CodeableConcept.text

Return Value: a CodeableConcept.

For the general type constructors, all the parameters are mandatory. Note that since all variables / outputs in FHIRPath are collections, all the parameters are inherently collections, but when the underlying property referred to is a singleton element, the collection cannot contain more than one item. Use the value {} if there is no value to provide.

---

%factory.create(type) : {type}

Create an instance of the named type: %factory.create(SampledData)

Parameters:

• type: a value that is the type to create. This is a FHIRPath type specifier, and the default namespace is 'FHIR'

Return Value: an instance of the named type.

---

%factory.withExtension(instance : T, url : string, value) : T

Add an extension, and return the new type: %factory.withExtension(%factory.create(Money), 'http:/acme.com/extension/example', %factory.code('test'))

Parameters:

• instance: The instance to add the URL to
• url: a string value that goes in Extension.url
• value: the value of the extension

Return Value: A copy of the instance of the type with the extension added. Extensions that already exist with the same url are not removed.

---

%factory.withProperty(instance : T, name : string, value) : T

Set a property value, and return the new type: %factory.withProperty(%factory.create(Address), 'http:/acme.com/extension/example', %factory.create(Period))

Parameters:

• instance: The instance to set the property on
• name: a string value that identifies the property to set
• value: the value of the property

Return Value: A copy of the instance of the type with the named property set. Any existing value(s) for the named property will be deleted.

General Service API

In order to support interaction with a server in FHIRPath statements, FHIR defines a general %server object that FHIRPath implementations should make available. Calls to this object are passed through a FHIR RESTful framework.

Summary:

%server : Server // default server (application controls context)
%server.at(url) : Server // server at specified address

%server.read(type, id) : Resource
%server.create(resource) : Resource
%server.update(resource) : Resource
%server.delete(resource) : boolean
%server.patch(parameters) : Resource
%server.search(doPost, parameters) : Bundle
%server.capabilities(mode) : Resource
%server.validate(resource, mode, parameters) : OperationOutcome
%server.transform(source, content) : Resource
%server.everything(type, id, parameters) : Bundle
%server.apply(resource, subject, parameters) : Bundle

---

%server.at(url) : Server

Get a server object pointing at a particular server. Note: The %server object points to the default server as specified by the application evaluating the FHIRPath.

Parameters:

• url: A URL that points to a FHIR RESTful API.

Return Value: A server that points at the specified URL. No errors - they will come when/if the server object is used.

---

%server.read(type, id) : Resource

Get a resource from the server.

Parameters:

• type: The type of the resource to read.
• id: The id of the resource to read.

Return Value: The resource at type/id. If not found, the return value is empty.

---

%server.create(resource) : Resource

Create a resource on the server.

Parameters:

• resource: The resource to create. If the resource has an id, it will be ignored.

Return Value: The resource after it was stored. If the create operation failed, the return value is empty.

---

%server.update(resource) : Resource

Store a resource on the server.

Parameters:

• resource: The resource to create. The resource must have an id.

Return Value: The resource after it was stored. If the create operation failed, the return value is empty.

---

%server.delete(resource) : boolean

Delete a resource on the server.

Parameters:

• resource: The resource to delete (must have an id).

Return Value: true if the resource was deleted, or false.

---

%server.search(doPost, parameters) : Bundle

Perform a search on the server.

Parameters:

• doPost: A boolean value - true to use a POST, false to use a GET
• parameters: A parameters resource, or a string with URL parameters (name=value&etc.)

Return Value: A bundle with the search results. If the search fails, the return value is empty.

---

%server.patch(parameters) : Resource

Perform a patch operation on the server.

Parameters:

• parameters: A parameters resource for FHIRPath Patch

Return Value: The resource after the patch. If the patch fails, the return value is empty.

---

%server.capabilities(mode) : Resource

Get the capabilities from the server

Parameters:

• mode: Optional: the mode to fetch.

Return Value: The resource returned (CapabilitiesStatement or TerminologyCapabilities resource). If not available, the return value is empty.

---

%server.validate(resource, mode, parameters) : OperationOutcome

Validate a resource on the server.

Parameters:

• resource: The resource to validate.
• mode: how to validate - see Validation Operation.
• parameters: A parameters resource, or a string with URL parameters (name=value&etc.)

Return Value: An operation outcome with issues. If the validation couldn't be performed, the return value is empty.

---

%server.transform(source, content) : Resource

Run the $transform operation on the server.

Parameters:

• source: The structure map to use.
• content: The resource to convert (often a binary)

Return Value: The resource returned from the transform. If the transform fails, the return value is empty.

---

%server.everything(type, id, parameters) : Bundle

Get a resource from the server.

Parameters:

• type: The type of the resource to read.
• id: The id of the resource to read.
• parameters: A parameters resource, or a string with URL parameters (name=value&etc.)

Return Value: The Bundle for type/id. If not available, the return value is empty.

---

%server.apply(resource, subject, parameters) : Bundle

Get a resource from the server.

Parameters:

• resource: The resource to drive the $apply operation (PlanDefinition, ActivityDefinition).
• subject: The subject to apply to - can be a resource, or a string containing type/id for the subject.
• parameters: A parameters resource, or a string with URL parameters (name=value&etc.)

Return Value: The bundle from $apply. If the operation fails, the return value is empty.