This page provides the detailed specifications for catalogs of laboratory diagnostic services.

Resources and Profiles

The figure below shows the resources and profiles used to represent catalogs of laboratory diagnostic services

When method 1 is chosen by the custodian for the catalog of laboratory services, the catalog references its items: the Composition resource constrained by the Catalog profile to represent the whole catalog, references the items of this catalog from its Composition.section.entry elements.

When method 2 is chosen instead, the catalog is referenced by its items: Each PlanDefinition resource constrained by the LabServiceDefinition profile, and representing an item of the catalog, references the Composition resource constrained by the CatalogHeader profile to represent the catalog header. This catalog header holds only the general properties of the catalog.

An item of the catalog is a laboratory service instantiated as a PlanDefinition, which represents either a test (type=test) or a panel (type=panel). A panel is a set of tests and/or panels.

At order entry time the computerized physician order entry applies the PlanDefinition to the current patient context, producing one or more ServiceRequest resources to convey the order for the laboratory service in case FHIR is used for placing orders, or feeding a v2 laboratory order message (OML) in case HL7 v2 is used for the same purpose.

The PlanDefinition conveys the general properties of the item: identification, names and codings, orderability, applicability, jurisdictions, billing, status, possible replacement by another item, gender or species restrictions, goals, bibliographic references and justifications, expected input documents (such as patient consent for genetic testing).

If present, PlanDefinition.action.definitionCanonical references the instance of ActivityDefinition representing the main operational procedure performed to carry this laboratory service. PlanDefinition.action.definitionCanonical may be not present, in which case, the top-level action has sub-actions referencing multiple instances of ActivityDefinition. This is illustrated by action[.action[.action]].definitionCanonical in the diagram, which potentially represents more than one action.

PlanDefinition.action:SpecimenRequested (0..*) conveys the requirements for biological specimens needed as input by the laboratory service.

PlanDefinition.action.definitionCanonical references one instance of ActivityDefinition representing the main operational procedure performed to carry this laboratory service. ActivityDefiniton is constrained by the LabProcedureDefinition profile . It references the observations expected by the laboratory as input alongside the order, and the observations that will be produced as output of the procedure.

In most cases the PlanDefinition.action has no sub-action, and therefore PlanDefinition references a single ActivityDefinition.

In some cases the laboratory service (panel or super-panel) embeds other services (panels and/or tests), which are already described in the catalog as standalone services (orderable or not). These nested services have, each, their own instance of PlanDefinition referenced from PlanDefinition.relatedArtifact (type = composed-of) of the embedding service. And in addition, each of the embedded tests or panels is described as a sub-action (PlanDefinition.action.action), which references an ActivityDefinition representing the nested laboratory procedure with its own observations, which will be added to those of the embedding service.

When a PlanDefinition of a laboratory service has multiple sub-actions, these sub-actions are assembled in a logical group (groupingBehavior = logical-group), with a selection behavior specified by the selectionBehavior element. Each of these sub-actions either references an ActivityDefinition or is redefined as a nested logical group introducing sub-sub-actions referencing ActivityDefinition instances.

Some of the sub-actions may also correspond to reflex procedures, triggered by a particular event or result in the parent procedure.

The sub-actions (and possibly sub-sub-actions) are assembled in logical groups, with a selection-behavior expressing which logic applies:

• all: all sub-actions of the group are taken
• exactly-one: one and only one sub-action of the group is taken (choice)
• any: any number of reflex sub-actions of the group is taken, depending on which trigger associated with each comes true.

This nesting of actions allows to build trees of laboratory services, reflecting the reality of some complex diagnostic panels. (e.g. LOINC's HIV susceptibility panel by Genotype method nesting 3 levels of panels and tests)

Input and output observations of the service are defined as instances of ObservationDefinition (constrained by the InputObservationDefinition profile for observations expected from the ordering clinician, or by the LabObservationDefinition profile for observations produced by the lab service and reported back to the clinician), with their quantitative (units, decimal precision, conversion factor, normal and therapeutic ranges) and/or qualitative (authorized values, normal values, critical values, preferred report name) characteristics.

Specimens required by the service are defined as instances of SpecimenDefinition conformant to the LabSpecimenDefinition profile, which enables to describe patient preparation requirements, collection procedures, types of containers to be used, minimum volume needed, rejection criteria, retention time, handling requirements before testing. An instance of SpecimenDefinition may specify one preferred testable specimen and multiple alternates, each with its proper physical characteristics, handlings, requirements and rejection criteria.

A laboratory service may provide more or less details about its billing. It may provide a textual billing summary as part of the PlanDefinition instance. It may also list the billing codes of a billing nomenclature, attached to it, still within the PlanDefinition instance. In addition, the service may specify for each billing code attached to it, what are the specific clinical focus that apply to this code, and what are its price components. These details are conveyed by a ChargeItemDefinition resource constrained by the LabChargeItemDefinition profile

Searching and retrieving Laboratory Services

Searching Approaches

The key searcheable assets in a laboratory compendium are the laboratory services exposed to the consumers of the compendium. Each laboratory service is represented by an instance of the PlanDefinition resource, constrained by the LabServiceDefinition profile.

• Two-step search: A client application browsing the content of the compendium may wish to first get the overview of a collection of services at first glance, and then retrieve the full details associated with the services it is interested in (including specimens, input observations, lab results). In this case, the first query will perform a simple search on PlanDefinition with the desirable criteria listed in the table below ; and then the second search will add the _include:iterate=* parameter, to retrieve the PlanDefiniton resource(s) associated with all supporting resources (ActivityDefinition, ChargeItemDefinition, Composition, SpecimenDefinition, ObservationDefinition ...) in the searchset Bundle.
• One-step search: Conversely a client application may wish to retrieve the full details of a service (or a set of services) at first glance. In this case, it uses the appropriate search criteria for PlanDefinition, in combination with the _include:iterate=* parameter, so as to obtain all the resources supporting each laboratory service which satisfies the criteria, assembled in the searchset Bundle.

Catalog servers may limit the iteration depth to an appropriate level for performance sake.

Search Parameters for Laboratory Services (PlanDefinition)

Name	Type	Description	Expression	Role
_lastUpdated	date	Last system point in time of PlanDefinition resource		can be used with =gt...
action-code	token	service code	PlanDefinition.action.code	LOINC code or local code of the service
billing-code	token	A billing code associated with the service	PlanDefinition.extension.where(url='http://hl7.org/fhir/uv/order-catalog/StructureDefinition/ServiceBillingCode').(value as Reference).reference(ChargeItemDefinition).resolve().code or PlanDefinition.extension.where(url='http://hl7.org/fhir/uv/order-catalog/StructureDefinition/ServiceBillingCode').(value as CodeableConcept)	The FHIRPath expression to be checked
catalog	reference	The reference to a Composition resource (profiled by CatalogHeader) owning this item	PlanDefinition.extension.where(url='http://hl7.org/fhir/uv/order-catalog/StructureDefinition/CatalogReference').valueReference.reference(Composition)	services of one catalog
composed-of	reference	lab service containing another lab service	PlanDefinition.relatedArtifact.where(type='composed-of').resource(PlanDefinition)	super-panels encompassing this test or panel
context	reference	use context assigned to the laboratory service	(PlanDefinition.useContext.value as CodeableConcept)
date	date	Publication date of service's business version	PlanDefinition.date	can be used with =gt...
description	string	The description of the laboratory service	PlanDefinition.description
gender	token	Services with a useContext representing a particular gender	(PlanDefinition.useContext.where(code='gender').value as CodeableConcept)	services restricted to a particular gender
jurisdiction	string	lab service jurisdiction	PlanDefinition.jurisdiction	e.g. country where service is usable
last-review-date	date	Last review date of the service	PlanDefinition.lastReviewDate	can be used with =gt...
name	string	The service computational name	PlanDefinition.name
orderable	token	(true: service with a useContext belonging to slice Orderable of LabServiceDefinition profile ; false: the opposite	PlanDefinition.useContext.slice(http://hl7.org/fhir/uv/order-catalog/StructureDefinition/LabServiceDefinition, Orderable).exists()	FHIRPath expression to be checked
publisher	string	lab service publisher	PlanDefinition.publisher
status	token	lab service status	PlanDefinition.status	narrow to active or retired services
task	token	Service with a useContext representing a particular task (e.g. LABOE for orderable service, LABRREV for service that can be added by the pathologist)	(PlanDefinition.useContext.where(code='task').value as CodeableConcept)	services associated with the particular task
title	string	The service title	PlanDefinition.title
topic	token	topic associated with the service	PlanDefinition.topic	various categorizations of the service
type	token	lab service type	PlanDefinition.type	narrow to type panel or type test
url	uri	The uri that identifies the laboratory service	PlanDefinition.url

Examples of searching and retrieving laboratory services

In all examples below, [base] represents the endpoint of the catalog server.

The answer of the server comes as a Bundle of type 'searchset' encapsulating the resources selected by the search.

There is one particular laboratory service catalog, which has Composition.id "a1" on the server.

List all catalogs of the server

GET [base]/Composition?type:text=Catalog&_summary=true

Obtains the summary of every catalog available on the server.The anwser Bundle contains one entry with a Composition resource for each catalog found.

List available laboratory service catalogs

GET [base]/Composition?type:text=Catalog&category=laboratory&_summary=true

Obtains the summary of every laboratory service catalog available on the server. The anwser Bundle contains one entry with a Composition resource for each catalog found.

List recently updated blood chemistry tests and panels of one catalog

GET [base]/PlanDefinition?catalog=Composition/a1&topic=http://snomed.info/sct|166312007&date=gt20200323T10:00:00Z+0100&_summary=true

Obtains the summary of the laboratory services from catalog of id a1, which are indexed by blood chemistry topic (coded in this example with SNOMED CT 166312007 |Blood chemistry| concept). The anwser Bundle contains one entry with a PlanDefinition resource for each laboratory service of catalog a1 associated with blood chemistry topic, and created or updated since March 23rd 10am.

Services of a catalog embedding a test or panel

GET [base]/PlanDefinition?catalog=Composition/a1&composed-of=PlanDefinition/s123&_summary=true

Lists the laboratory services from catalog of id a1, which embed laboratory service of id s123. The anwser Bundle contains one entry with a PlanDefinition resource for each service found with a relatedArtifact.where(type='composed-of').PlanDefinition/s123.

Retrieve all details for a laboratory service

GET [base]/PlanDefinition?_id=s123&_include:iterate=*

Obtains the full content of PlanDefinition of id s123, accompanied with all resources referenced by this PlanDefinition: {Composition, ActivityDefinition, ObservationDefinition, SpecimenDefinition, PlanDefinition (as related artifacts in case this service embeds other panels or tests)}. The anwser Bundle contains one entry with PlanDefinition resource s123, and below it, as many entries as resources referenced by this one (recursively). Thus the Bundle provides the fullly detailed description of this laboratory service.

Administering laboratory services

When the roles catalog owner and catalog custodian are played by two different systems the former is a FHIR client of the latter, granted with administration permissions (create, update, delete, patch) on the catalog content. The interactions between the two systems follow the transversal technical specifications exposed in section Administer a catalog through the FHIR API of the Interactions page of this guide.

The catalog owner updates the content of the catalog on the catalog custodian in a transactional manner, by posting a transaction Bundle containing all the updates to be performed synchronously:

POST [base]

with the transaction Bundle in the body of the request, as shown in example-lab-test-creation-transaction-request.

The catalog custodian performs the requested transaction and returns back a transaction-response Bundle, as shown in example-lab-test-creation-transaction-response.