Defining your Diagnostic Catalog

A diagnostic catalog contains all the pertinent information about the diagnostic services you provide, including your analytes, reference ranges, panels, specimen requirements, and laboratory procedures.

Having a well-defined, structured catalog enables:

Robust access controls
Higher quality analytics
Smoother CLIA/CAP certification
Streamlined billing

At the end of this guide, you will understand how to represent your diagnostic catalog in FHIR at a detailed level an example of which is shown in this diagram.

Follow the guide step-by-step to build up the components shown:

Define your clinical observations
Define your specimens
Define your orderable services
Define your laboratory procedures

Our recommendations are informed by the Order Catalog Implementation Guide implementation guide, which developed with contributions from Labcorp, Quest Diagnostics, and other industry leaders.

Sample Data

You can download the examples in this guide as a FHIR bundle here, and upload them to your project using the Medplum Batch Upload Tool

Define your clinical observations

The first step in building your catalog is to define which clinical quantities, or "observations", you will measure. In a lab context, an example of a clinical observation would be an an HBA1c percentage. For a given patient, this observation might have a value such as 5.3%.

The Observation is the primary operational resource used to record a clinical quantity for a specific patient. ObservationDefinition is the corresponding administrative counterpart, and is used to define how an Observation should be measured, interpreted, and reported.

Observations and ObservationDefinitions are linked by sharing a common code element, which should include a LOINC code in most cases.

A great ObservationDefinition contains the following:

Element	Description	Code System	Example
`code`	Code representing the observation type.	LOINC (see LOINC codes)	2951-2 - Sodium [Moles/volume] in Serum or Plasma
`quantitativeDetails.unit`	Units expressing the observation value.	UCUM	mmol/L
`quantitativeDetails.decimalPrecision`	Number of places of precision to the right of the decimal point		2 (e.g. `0.11`)
`qualifiedInterval`	Range of valid or reference values for the observation, to be used during interpretation. See our guide on reference ranges for more info.		Low: <= 134.00 mmol/L Normal: 135.00 mmol/L - 145.00 mmol/L High: >= 146.00 mmol/L
`preferredReportName`	Patient-friendly name used for reporting the observation result.		Sodium Level

Key amongst these is the qualifiedInterval element, which is used to define how results should be interpreted. See our guide on reference ranges for more information.

Example: Blood Sodium Level

{
  resourceType: 'ObservationDefinition',
  id: 'observation-blood-sodium',
  code: {
    coding: [
      {
        system: LOINC,
        code: '2947-0',
        display: 'Sodium [Moles/volume] in Blood',
      },
    ],
  },
  preferredReportName: 'Sodium Level',
  quantitativeDetails: {
    unit: {
      coding: [
        {
          system: UCUM,
          code: 'mmol/L',
          display: 'millimoles per liter',
        },
      ],
    },
    decimalPrecision: 2,
  },
  qualifiedInterval: [
    {
      condition: 'Normal',
      range: {
        low: {
          value: 135,
          unit: 'mmol/L',
        },
        high: {
          value: 145,
          unit: 'mmol/L',
        },
      },
    },
  ],
};

Define your specimens

In the context of laboratory use cases, it's essential to recognize that observations are based on samples extracted from patients, known as "specimens". A well constructed diagnostic catalog links the specimen requirements for each test to the test definition to provide lab operators a complete picture of the collection process.

The Specimen resource resource refers to a specific specimen, like a tube of blood, usually belonging to a patient. As with Observations, Specimen has a corresponding administrative resource, called SpecimenDefinition.

SpecimenDefinition describes the type of specimen material to be collected, as well as details about the collection process, storage, handling, and preparation for testing.

The SpecimenDefinition allows you to specify many details about your specimen, but the most relevant are:

Field	Description	Code System	Example
`typeCollected`	Type of material collected.	SNOMED (children of 123038009 - Specimen)	122554006 - Capillary Blood Specimen
`collection`	Procedure used for collection.	SNOMED (children of 118292001 - Removal)	278450005 - Finger-prick sampling
`typeTested.container`	Details about the container storing the specimen.	Specimen Container Type	467989009 - Capillary blood collection tube, no-additive
`typeTested.handling`	Duration of storage at different temperature ranges	Handling Condition	Store refrigerated at 2-8°C for up to 48 hours
`typeTested.preference`	Whether this collection output is the preferred form, or an alternate	preferred \| alternate	preferred

typeCollected vs typeTested

Material that is collected from a patient may be split up, prepared, and handled different ways. The typeTested elements describe all the potential outputs of the collection process, and contains a lot more information about the containment vessel, rejection criteria, and temperature restrictions for each output.

Details

Example: Capillary Blood Sample

The following examples defines a fingerprick blood sample that is distributed into two collection tubes: a red cap and a green cap.

{
  resourceType: 'SpecimenDefinition',
  id: 'fingerprick-capillary-blood',
  // Specimen Material Type
  typeCollected: {
    coding: [
      {
        system: SNOMED,
        code: '122554006',
        display: 'Capillary Blood Specimen',
      },
    ],
  },
  // Collection Procedure
  collection: [
    {
      coding: [
        {
          system: SNOMED,
          code: '278450005',
          display: 'Finger-prick sampling',
        },
      ],
    },
  ],
  // Two "outputs" of the collection procedure
  typeTested: [
    // First output is a red-capped tube
    {
      preference: 'preferred',
      container: {
        type: {
          coding: [
            {
              system: SNOMED,
              code: '467989009',
              display: 'Capillary blood collection tube, no-additive',
            },
          ],
        },
        cap: {
          coding: [
            {
              system: 'http://terminology.hl7.org/CodeSystem/container-cap',
              code: 'red',
            },
          ],
          text: 'red cap',
        },
      },
      // Storage durations for room temperature and frozen conditions
      handling: [
        {
          temperatureQualifier: {
            text: 'room temperature',
            coding: [
              {
                system: 'http://terminology.hl7.org/CodeSystem/handling-condition',
                code: 'room',
                display: 'room temperature',
              },
            ],
          },
          maxDuration: {
            value: 7,
            unit: 'day',
            system: UCUM,
            code: 'd',
          },
        },
        {
          temperatureQualifier: {
            text: 'frozen',
            coding: [
              {
                system: 'http://terminology.hl7.org/CodeSystem/handling-condition',
                code: 'frozen',
                display: 'frozen',
              },
            ],
          },
          maxDuration: {
            value: 28,
            unit: 'day',
            system: UCUM,
            code: 'd',
          },
        },
      ],
    },
    // Second output is a green-capped tube
    {
      preference: 'preferred',
      container: {
        type: {
          coding: [
            {
              system: SNOMED,
              code: '467989009',
              display: 'Capillary blood collection tube, no-additive',
            },
          ],
        },
        cap: {
          coding: [
            {
              system: 'http://terminology.hl7.org/CodeSystem/container-cap',
              code: 'green',
            },
          ],
          text: 'green cap',
        },
      },
    },
  ],
};

Define your services

The next step is to roll up your individual tests into orderable services that your patients can order. These can be thought of as your diagnostic "product offerings," and are commonly known as "panels" in a lab context.

These products are represented as PlanDefinition resources. The PlanDefinition is primarily a grouping resource that stores metadata about the service and references the ActivityDefinitions you will create in the next section.

PlanDefinition's important fields:

Field	Description	Code System	Example
`name`	The computer-friendly name of the service.		mens-health-panel
`title`	The human-friendly name of the service.		Men's Health Panel
`identifier`	Business identifier for the service (i.e. product or SKU code)		dx-panel-12345
`type`	Whether the service is a single test or a panel	Laboratory service types	panel
`useContext`	How this `PlanDefinition` should be interpreted. For diagnostic procedures, this is a fixed value: Lab Order Entry		Lab Order Entry
`status`	Whether or not the`PlanDefinition` is active		active
`action.code`	The code for lab procedure corresponding	LOINC	55231-5 - Electrolytes panel - Blood
`action.definitionCanonical`	The "canonical url" of the the `ActivityDefinition` representing the procedure (see below)		http://example.org/ActivityDefinition/electrolyte-panel

In the next section, we'll learn more about the PlanDefinition.action element, which represents the lab procedures used to fulfill the diagnostic service order.

Define your lab procedures

Now that you have represented your service menu as PlanDefinitions , you will use ActivityDefinition resource to define your corresponding procedures to fulfill each service.

While PlanDefinitions are patient facing resources, ActivityDefinitions are primarily used by lab operators to aid them in fulfilling the order. To link the two, each entry in PlanDefinition.action references an individual lab procedure, with PlanDefinition.action.definitionCanonical referencing an ActivityDefinition resource for details.

Note: Canonical References

PlanDefinitions and ActivityDefinitions are linked via what is known as a canonical reference, not a standard reference as with most other resources. PlanDefinition.action.definitionCanonical is a URL string, that must match the url field of the ActivityDefinition it references.

There is a bit of an art to determining divide the individual tests into procedures, and it requires an understanding of your lab operations. Some considerations to help guide you:

Are there reusable groups of tests that are always performed together?
Do these groups have their own LOINC codes?
Do your analyzers have a single input to order this group of results?

ActivityDefinitions

The ActivityDefinition resource stores detailed information about each procedure, and is the resource that links PlanDefinition.action, to the ObservationDefinitions and SpecimenDefinitions we defined earlier.

The most important fields for ActivityDefinition are summarized below:

Element	Description	Code System	Example
`code`	The LOINC code corresponding to this procedure. Should match the code used in `PlanDefinition.action`	LOINC	55231-5 - Electrolytes panel - Blood
`url`	Known as the "canonical URL" for the resource. This should be a fully qualified, globally unique URL. FHIR recommends for many administrative resources (aka "definitional resources") to have canonical URLs to provide a globally unique business identifier. Read more about canonical URLs here A recommended pattern for constructing this URL is: `http://[your-company-url]/ActivityDefinition/[test-name]`		http://example.org/ActivityDefinition/electrolyte-panel
`observationResultRequirement`	References to the `ObservationDefinition` resources for the test results produced by this procedure (see above).	See above
`specimenRequirement`	References to the `SpecimenDefinition` resources for the test results produced by this procedure (see above).	See above
`name`	A computer-friendly name for the procedure		electrolytes-panel-blood-measurement
`title`	A human-friendly name for the procedure		Electrolytes panel measurement in blood
`kind`	The kind of resource that will represent the lab order. For diagnostics, this is always `ServiceRequest`.		ServiceRequest
`status`	Whether or not the`ActivityDefinition` is active		active

The Simple Case

In most cases, each service will only require a single laboratory procedure. In these cases, you will only need a single PlanDefinition.action and ActivityDefinition, representing the main operational procedure performed to fulfill this laboratory service.

Details

Example: Electrolyte Panel

In the example below, a patient can order an Electrolyte Panel, which is a single laboratory procedure

Patient-facing service

{
  resourceType: 'PlanDefinition',
  id: 'example-lab-service-electrolytes-panel-blood',
  status: 'active',
  // Canonical URL
  url: 'http://example.org/PlanDefinition/lab-service-electrolytes-panel-blood',
  // Business Identifier
  identifier: [
    {
      use: 'official',
      value: 'electrolytes_panel_test',
    },
  ],
  // Machine-friendly name
  name: 'electrolytes-panel-blood-measurement',
  // Human-friendly name
  title: 'Electrolytes panel measurement in blood',
  description: 'Electrolytes panel measurement on blood specimen',
  // 'test' or 'panel'
  type: {
    coding: [
      {
        system: 'http://hl7.org/fhir/uv/order-catalog/CodeSystem/laboratory-service-definition-type',
        code: 'panel',
        display: 'collection of tests and panels performed on one or more in vitro biologic specimens',
      },
    ],
  },
  // This service contains a single action since only one procedure is required for fulfillment
  action: [
    {
      code: [
        {
          coding: [
            {
              system: LOINC,
              code: '55231-5',
              display: 'Electrolytes panel - Blood',
            },
          ],
        },
      ],
      definitionCanonical: 'http://example.org/lab-procedure-electrolytes-panel-blood',
    },
  ],
  // 'LABOE' indicates that this PlanDefinition is represents a Lab service
  useContext: [
    {
      code: {
        system: 'http://terminology.hl7.org/CodeSystem/usage-context-type',
        code: 'task',
      },
      valueCodeableConcept: {
        coding: [
          {
            system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode',
            code: 'LABOE',
            display: 'laboratory test order entry task',
          },
        ],
      },
    },
  ],
};

Laboratory Procedure

{
  resourceType: 'ActivityDefinition',
  id: 'lab-procedure-electrolytes-panel-blood',
  status: 'active',
  name: 'electrolytes-panel-blood-measurement-procedure',
  title: 'Procedure - Electrolytes panel measurement in blood',
  // Canonical URL
  url: 'http://example.org/lab-procedure-electrolytes-panel-blood',
  identifier: [
    {
      use: 'official',
      value: 'electrolytes_panel_test',
    },
  ],
  // LOINC Code
  code: {
    coding: [
      {
        system: LOINC,
        code: '55231-5',
        display: 'Electrolytes panel - Blood',
      },
    ],
  },
  kind: 'ServiceRequest',
  observationResultRequirement: [
    {
      reference: 'ObservationDefinition/observation-blood-potassium',
    },
    {
      reference: 'ObservationDefinition/observation-blood-chloride',
    },
    {
      reference: 'ObservationDefinition/observation-blood-carbon-dioxide',
    },
    {
      reference: 'ObservationDefinition/observation-blood-sodium',
    },
  ],
  specimenRequirement: [{ reference: 'SpecimenDefinition/fingerprick-capillary-blood' }],
};

Reusing Procedures

In some cases, a product offering might embed multiple procedures that are reused across service offerings. In these cases, we can define multiple entries in PlanDefinition.action, each with their own ActivityDefinition.

This allows you to reuse the data definition of your procedures, while allowing you to compose them into different patient-facing product offerings.

Example: Men's Health Panel

This PlanDefinition reuses the Electrolyte Panel from the previous example, and but adds a free testosterone test.

Patient-facing service

{
  resourceType: 'PlanDefinition',
  id: 'example-lab-service-mens-health',
  status: 'active',
  // Canonical URL
  url: 'http://example.org/PlanDefinition/lab-service-mens-health',
  // Business Identifier
  identifier: [
    {
      use: 'official',
      value: 'mens_health_panel_test',
    },
  ],
  // Machine-friendly name
  name: 'mens-health-panel',
  // Human-friendly name
  title: "Men's Health Panel",
  description: "Men's health-related laboratory tests",
  // 'test' or 'panel'
  type: {
    coding: [
      {
        system: 'http://hl7.org/fhir/uv/order-catalog/CodeSystem/laboratory-service-definition-type',
        code: 'panel',
        display: 'collection of tests and panels performed on one or more in vitro biologic specimens',
      },
    ],
  },
  action: [
    {
      code: [
        {
          coding: [
            {
              system: LOINC,
              code: '41018-3',
              display: 'Testosterone.free+weakly bound [Moles/volume] in Serum or Plasma',
            },
          ],
        },
      ],
      definitionCanonical: 'http://example.org/lab-procedure-testosterone-serum',
    },
    {
      code: [
        {
          coding: [
            {
              system: LOINC,
              code: '55231-5',
              display: 'Electrolytes panel - Blood',
            },
          ],
        },
      ],
      definitionCanonical: 'http://example.org/lab-procedure-electrolytes-panel-blood',
    },
  ],
  useContext: [
    {
      code: {
        system: 'http://terminology.hl7.org/CodeSystem/usage-context-type',
        code: 'task',
      },
      valueCodeableConcept: {
        coding: [
          {
            system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode',
            code: 'LABOE',
            display: 'laboratory test order entry task',
          },
        ],
      },
    },
  ],
};

Laboratory Procedures

Testosterone Procedure

{
  resourceType: 'ActivityDefinition',
  status: 'active',
  id: 'lab-procedure-testosterone-free-weakly-bound-serum',
  name: 'testosterone-free-weakly-bound-measurement-procedure',
  title: 'Procedure - Testosterone free & weakly bound measurement in in vitro serum',
  url: 'http://example.org/lab-procedure-testosterone-free-weakly-bound-serum',
  identifier: [
    {
      use: 'official',
      value: 'Testosterone_free_weakly_bound_test',
    },
  ],
  code: {
    coding: [
      {
        system: LOINC,
        code: '41018-3',
        display: 'Testosterone.free+weakly bound [Moles/volume] in Serum or Plasma',
      },
    ],
  },
  kind: 'ServiceRequest',
  observationResultRequirement: [
    {
      reference: 'ObservationDefinition/observation-serum-testosterone-free-weakly-bound',
    },
  ],
  specimenRequirement: [{ reference: 'SpecimenDefinition/fingerprick-capillary-blood' }],
};

Electrolytes Procedure

{
  resourceType: 'ActivityDefinition',
  id: 'lab-procedure-electrolytes-panel-blood',
  status: 'active',
  name: 'electrolytes-panel-blood-measurement-procedure',
  title: 'Procedure - Electrolytes panel measurement in blood',
  // Canonical URL
  url: 'http://example.org/lab-procedure-electrolytes-panel-blood',
  identifier: [
    {
      use: 'official',
      value: 'electrolytes_panel_test',
    },
  ],
  // LOINC Code
  code: {
    coding: [
      {
        system: LOINC,
        code: '55231-5',
        display: 'Electrolytes panel - Blood',
      },
    ],
  },
  kind: 'ServiceRequest',
  observationResultRequirement: [
    {
      reference: 'ObservationDefinition/observation-blood-potassium',
    },
    {
      reference: 'ObservationDefinition/observation-blood-chloride',
    },
    {
      reference: 'ObservationDefinition/observation-blood-carbon-dioxide',
    },
    {
      reference: 'ObservationDefinition/observation-blood-sodium',
    },
  ],
  specimenRequirement: [{ reference: 'SpecimenDefinition/fingerprick-capillary-blood' }],
};

Sub actions

Beyond flat lists of procedures, FHIR PlanDefinitions can be used to represent sub-procedures, mutually exclusive groups of procedures, reflex tests, and other complicated arrangements.

These advanced scenarios are out of scope for this guide, but you can check out the this implementation guide for examples of how these might be implemented

Querying your catalog

You can query all PlanDefinitions that represent a laboratory procedure using the and the associated ActivityDefinitions with this query:

Typescript
CLI
cURL

await medplum.searchResources('PlanDefinition', { context: 'LABOE' });

medplum get 'PlanDefinition?context=LABOE'

curl 'https://api.medplum.com/fhir/R4/PlanDefinition?context=LABOE' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \

Another common query is to get all the ObservationDefinition and SpecimenDefinitions in a single service. Unfortunately, there is currently no way to do this using a single query. However, this can be done in two parts:

Query all ActivityDefinitions for a given PlanDefinition using _include directive

Typescript
CLI
cURL

await medplum.search('PlanDefinition', { _id: '[serviceId]', _include: 'definition' });

medplum get 'PlanDefinition?_id=[serviceId]&_include=definition'

curl 'https://api.medplum.com/fhir/R4/PlanDefinition?_id=[serviceId]&_include=definition'' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \

For each resulting ActivityDefinition, read each ObservationDefinition and SpecimenDefinition. This operation is well suited to GraphQL

GraphQL
TypeScript

{
  ActivityDefinition(id: "[procedureId]") {
    resourceType
    url
    name
    code { coding { code } }
    title
    # Fetch Required Specimens
    specimenRequirement {
      resource {
        ... on SpecimenDefinition {
          # Extracted Material
          typeCollected {
            coding {
              code
            }
          }
          # Extraction Outputs
          typeTested {
            # Container Type
            container {
              cap {coding {code}}
            }
            # Handling Instructions
            handling {
              temperatureRange {
                low {value, unit},
                high {value, unit}
              }
            }
          }
        }
      }
    }
    # Fetch Output Observations
    observationResultRequirement {
      resource {
        ...on ObservationDefinition{
          preferredReportName
          code { coding {code} }
          # Precision and Units
          quantitativeDetails {
            unit {coding {code}}
            decimalPrecision
          }
          # Reference Ranges
          qualifiedInterval {
            condition
            age {
              low {value, unit}
              high {value, unit}
            }
            range {
              low {value unit}
              high {value unit}
            }
          }
        }
      }
    }
  }
}

await medplum.graphql(`
{
  ActivityDefinition(id: "[procedureId]") {
    resourceType
    url
    name
    code { coding { code } }
    title
    # Fetch Required Specimens
    specimenRequirement {
      resource {
        ... on SpecimenDefinition {
          # Extracted Material
          typeCollected {
            coding {
              code
            }
          }
          # Extraction Outputs
          typeTested {
            # Container Type
            container {
              cap {coding {code}}
            }
            # Handling Instructions
            handling {
              temperatureRange {
                low {value, unit},
                high {value, unit}
              }
            }
          }
        }
      }
    }
    # Fetch Output Observations
    observationResultRequirement {
      resource {
        ...on ObservationDefinition{
          preferredReportName
          code { coding {code} }
          # Precision and Units
          quantitativeDetails {
            unit {coding {code}}
            decimalPrecision
          }
          # Reference Ranges
          qualifiedInterval {
            condition
            age {
              low {value, unit}
              high {value, unit}
            }
            range {
              low {value unit}
              high {value unit}
            }
          }
        }
      }
    }
  }
}`);

Putting it all together

Now we'll put all these concepts together to model a basic lab catalog. The diagram below illustrates the setup we will be modeling:

We have two orderable services, a "Men's Health Panel" and a "Women's Health Panel"
Each service has a shared procedure, the "Electrolyte Panel"
Each service also has a sex-specific procedure: "Testosterone" for men and "Estradiol" for women
The Men's health panel will produce the following clinical measurements:
- Free Testosterone Level
- Sodium Level
- Potassium Level
- Chloride Level
- Total CO2 Level
The Women's health panel will produce the following clinical measurements:
- Estradiol E2 Level
- Sodium Level
- Potassium Level
- Chloride Level
- Total CO2 Level

Services (PlanDefinition)

Men's Health

{
  resourceType: 'PlanDefinition',
  id: 'example-lab-service-mens-health',
  status: 'active',
  // Canonical URL
  url: 'http://example.org/PlanDefinition/lab-service-mens-health',
  // Business Identifier
  identifier: [
    {
      use: 'official',
      value: 'mens_health_panel_test',
    },
  ],
  // Machine-friendly name
  name: 'mens-health-panel',
  // Human-friendly name
  title: "Men's Health Panel",
  description: "Men's health-related laboratory tests",
  // 'test' or 'panel'
  type: {
    coding: [
      {
        system: 'http://hl7.org/fhir/uv/order-catalog/CodeSystem/laboratory-service-definition-type',
        code: 'panel',
        display: 'collection of tests and panels performed on one or more in vitro biologic specimens',
      },
    ],
  },
  action: [
    {
      code: [
        {
          coding: [
            {
              system: LOINC,
              code: '41018-3',
              display: 'Testosterone.free+weakly bound [Moles/volume] in Serum or Plasma',
            },
          ],
        },
      ],
      definitionCanonical: 'http://example.org/lab-procedure-testosterone-serum',
    },
    {
      code: [
        {
          coding: [
            {
              system: LOINC,
              code: '55231-5',
              display: 'Electrolytes panel - Blood',
            },
          ],
        },
      ],
      definitionCanonical: 'http://example.org/lab-procedure-electrolytes-panel-blood',
    },
  ],
  useContext: [
    {
      code: {
        system: 'http://terminology.hl7.org/CodeSystem/usage-context-type',
        code: 'task',
      },
      valueCodeableConcept: {
        coding: [
          {
            system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode',
            code: 'LABOE',
            display: 'laboratory test order entry task',
          },
        ],
      },
    },
  ],
};

Women's Health

const womensHealthService: PlanDefinition = {
  resourceType: 'PlanDefinition',
  status: 'active',
  id: 'example-lab-service-womens-health',
  // Canonical URL
  url: 'http://example.org/PlanDefinition/lab-service-womens-health',
  // Business Identifier
  identifier: [
    {
      use: 'official',
      value: 'womens_health_panel_test',
    },
  ],
  // Machine-friendly name
  name: 'womens-health-panel',
  // Human-friendly name
  title: "Women's Health Panel",
  description: "Women's health-related laboratory tests",
  // 'test' or 'panel'
  type: {
    coding: [
      {
        system: 'http://hl7.org/fhir/uv/order-catalog/CodeSystem/laboratory-service-definition-type',
        code: 'panel',
        display: 'collection of tests and panels performed on one or more in vitro biologic specimens',
      },
    ],
  },
  action: [
    {
      code: [
        {
          coding: [
            {
              system: LOINC,
              code: '14715-7',
              display: 'Estradiol (E2) [Moles/volume] in Serum or Plasma',
            },
          ],
        },
      ],
      definitionCanonical: 'http://example.org/lab-procedure-estradiol-e2-serum',
    },
    {
      code: [
        {
          coding: [
            {
              system: LOINC,
              code: '55231-5',
              display: 'Electrolytes panel - Blood',
            },
          ],
        },
      ],
      definitionCanonical: 'http://example.org/lab-procedure-electrolytes-panel-blood',
    },
  ],
  useContext: [
    {
      code: {
        system: 'http://terminology.hl7.org/CodeSystem/usage-context-type',
        code: 'task',
      },
      valueCodeableConcept: {
        coding: [
          {
            system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode',
            code: 'LABOE',
            display: 'laboratory test order entry task',
          },
        ],
      },
    },
  ],
};

Procedures (ActivityDefinition)

Testosterone

{
  resourceType: 'ActivityDefinition',
  status: 'active',
  id: 'lab-procedure-testosterone-free-weakly-bound-serum',
  name: 'testosterone-free-weakly-bound-measurement-procedure',
  title: 'Procedure - Testosterone free & weakly bound measurement in in vitro serum',
  url: 'http://example.org/lab-procedure-testosterone-free-weakly-bound-serum',
  identifier: [
    {
      use: 'official',
      value: 'Testosterone_free_weakly_bound_test',
    },
  ],
  code: {
    coding: [
      {
        system: LOINC,
        code: '41018-3',
        display: 'Testosterone.free+weakly bound [Moles/volume] in Serum or Plasma',
      },
    ],
  },
  kind: 'ServiceRequest',
  observationResultRequirement: [
    {
      reference: 'ObservationDefinition/observation-serum-testosterone-free-weakly-bound',
    },
  ],
  specimenRequirement: [{ reference: 'SpecimenDefinition/fingerprick-capillary-blood' }],
};

Estradiol

{
  resourceType: 'ActivityDefinition',
  status: 'active',
  id: 'lab-procedure-estradiol-e2-serum',
  name: 'estradiol-e2-measurement-procedure',
  title: 'Procedure - Estradiol (E2) measurement in in vitro serum',
  url: 'http://example.org/lab-procedure-estradiol-e2-serum',
  identifier: [
    {
      use: 'official',
      value: 'Estradiol_E2_test',
    },
  ],
  code: {
    coding: [
      {
        system: LOINC,
        code: '14715-7',
        display: 'Estradiol (E2) [Moles/volume] in Serum or Plasma',
      },
    ],
  },
  kind: 'ServiceRequest',
  observationResultRequirement: [
    {
      reference: 'ObservationDefinition/observation-serum-estradiol-e2',
    },
  ],
  specimenRequirement: [{ reference: 'SpecimenDefinition/fingerprick-capillary-blood' }],
};

Electrolytes

{
  resourceType: 'ActivityDefinition',
  id: 'lab-procedure-electrolytes-panel-blood',
  status: 'active',
  name: 'electrolytes-panel-blood-measurement-procedure',
  title: 'Procedure - Electrolytes panel measurement in blood',
  // Canonical URL
  url: 'http://example.org/lab-procedure-electrolytes-panel-blood',
  identifier: [
    {
      use: 'official',
      value: 'electrolytes_panel_test',
    },
  ],
  // LOINC Code
  code: {
    coding: [
      {
        system: LOINC,
        code: '55231-5',
        display: 'Electrolytes panel - Blood',
      },
    ],
  },
  kind: 'ServiceRequest',
  observationResultRequirement: [
    {
      reference: 'ObservationDefinition/observation-blood-potassium',
    },
    {
      reference: 'ObservationDefinition/observation-blood-chloride',
    },
    {
      reference: 'ObservationDefinition/observation-blood-carbon-dioxide',
    },
    {
      reference: 'ObservationDefinition/observation-blood-sodium',
    },
  ],
  specimenRequirement: [{ reference: 'SpecimenDefinition/fingerprick-capillary-blood' }],
};

Observations (ObservationDefinition)

Free Testosterone

{
  resourceType: 'ObservationDefinition',
  id: 'observation-serum-testosterone-free-weakly-bound',
  code: {
    coding: [
      {
        system: LOINC,
        code: '41018-3',
        display: 'Testosterone.free+weakly bound [Moles/volume] in Serum or Plasma',
      },
    ],
  },
  preferredReportName: 'Free Testosterone Level',
  quantitativeDetails: {
    unit: {
      coding: [
        {
          system: UCUM,
          code: 'nmol/L',
          display: 'nanomoles per liter',
        },
      ],
    },
    decimalPrecision: 2,
  },
  qualifiedInterval: [
    {
      condition: 'Normal',
      range: {
        low: {
          value: 10,
          unit: 'nmol/L',
        },
        high: {
          value: 30,
          unit: 'nmol/L',
        },
      },
    },
  ],
};

Estradiol

{
  resourceType: 'ObservationDefinition',
  id: 'observation-serum-estradiol-e2',
  code: {
    coding: [
      {
        system: LOINC,
        code: '14715-7',
        display: 'Estradiol (E2) [Moles/volume] in Serum or Plasma',
      },
    ],
  },
  preferredReportName: 'Estradiol (E2) Level',
  quantitativeDetails: {
    unit: {
      coding: [
        {
          system: UCUM,
          code: 'pmol/L',
          display: 'picomoles per liter',
        },
      ],
    },
    decimalPrecision: 2,
  },
  qualifiedInterval: [
    {
      condition: 'Normal',
      range: {
        low: {
          value: 40,
          unit: 'pmol/L',
        },
        high: {
          value: 200,
          unit: 'pmol/L',
        },
      },
    },
  ],
};

Sodium

{
  resourceType: 'ObservationDefinition',
  id: 'observation-blood-sodium',
  code: {
    coding: [
      {
        system: LOINC,
        code: '2947-0',
        display: 'Sodium [Moles/volume] in Blood',
      },
    ],
  },
  preferredReportName: 'Sodium Level',
  quantitativeDetails: {
    unit: {
      coding: [
        {
          system: UCUM,
          code: 'mmol/L',
          display: 'millimoles per liter',
        },
      ],
    },
    decimalPrecision: 2,
  },
  qualifiedInterval: [
    {
      condition: 'Normal',
      range: {
        low: {
          value: 135,
          unit: 'mmol/L',
        },
        high: {
          value: 145,
          unit: 'mmol/L',
        },
      },
    },
  ],
};

Potassium

{
  resourceType: 'ObservationDefinition',
  id: 'observation-blood-potassium',
  code: {
    coding: [
      {
        system: LOINC,
        code: '6298-4',
        display: 'Potassium [Moles/volume] in Blood',
      },
    ],
  },
  preferredReportName: 'Potassium Level',
  quantitativeDetails: {
    unit: {
      coding: [
        {
          system: UCUM,
          code: 'mmol/L',
          display: 'millimoles per liter',
        },
      ],
    },
    decimalPrecision: 2,
  },
  qualifiedInterval: [
    {
      condition: 'Normal',
      range: {
        low: {
          value: 3.5,
          unit: 'mmol/L',
        },
        high: {
          value: 5.1,
          unit: 'mmol/L',
        },
      },
    },
  ],
};

Chloride

{
  resourceType: 'ObservationDefinition',
  id: 'observation-blood-chloride',
  code: {
    coding: [
      {
        system: LOINC,
        code: '2069-3',
        display: 'Chloride [Moles/volume] in Blood',
      },
    ],
  },
  preferredReportName: 'Chloride Level',
  quantitativeDetails: {
    unit: {
      coding: [
        {
          system: UCUM,
          code: 'mmol/L',
          display: 'millimoles per liter',
        },
      ],
    },
    decimalPrecision: 2,
  },
  qualifiedInterval: [
    {
      condition: 'Normal',
      range: {
        low: {
          value: 96,
          unit: 'mmol/L',
        },
        high: {
          value: 106,
          unit: 'mmol/L',
        },
      },
    },
  ],
};

CO2

{
  resourceType: 'ObservationDefinition',
  id: 'observation-blood-carbon-dioxide',
  code: {
    coding: [
      {
        system: LOINC,
        code: '20565-8',
        display: 'Carbon dioxide, total [Moles/volume] in Blood',
      },
    ],
  },
  preferredReportName: 'Total CO2 Level',
  quantitativeDetails: {
    unit: {
      coding: [
        {
          system: UCUM,
          code: 'mmol/L',
          display: 'millimoles per liter',
        },
      ],
    },
    decimalPrecision: 2,
  },
  qualifiedInterval: [
    {
      condition: 'Normal',
      range: {
        low: {
          value: 22,
          unit: 'mmol/L',
        },
        high: {
          value: 29,
          unit: 'mmol/L',
        },
      },
    },
  ],
};

Specimen (SpecimenDefinition)

Finger-prick Capillary Blood

{
  resourceType: 'SpecimenDefinition',
  id: 'fingerprick-capillary-blood',
  // Specimen Material Type
  typeCollected: {
    coding: [
      {
        system: SNOMED,
        code: '122554006',
        display: 'Capillary Blood Specimen',
      },
    ],
  },
  // Collection Procedure
  collection: [
    {
      coding: [
        {
          system: SNOMED,
          code: '278450005',
          display: 'Finger-prick sampling',
        },
      ],
    },
  ],
  // Two "outputs" of the collection procedure
  typeTested: [
    // First output is a red-capped tube
    {
      preference: 'preferred',
      container: {
        type: {
          coding: [
            {
              system: SNOMED,
              code: '467989009',
              display: 'Capillary blood collection tube, no-additive',
            },
          ],
        },
        cap: {
          coding: [
            {
              system: 'http://terminology.hl7.org/CodeSystem/container-cap',
              code: 'red',
            },
          ],
          text: 'red cap',
        },
      },
      // Storage durations for room temperature and frozen conditions
      handling: [
        {
          temperatureQualifier: {
            text: 'room temperature',
            coding: [
              {
                system: 'http://terminology.hl7.org/CodeSystem/handling-condition',
                code: 'room',
                display: 'room temperature',
              },
            ],
          },
          maxDuration: {
            value: 7,
            unit: 'day',
            system: UCUM,
            code: 'd',
          },
        },
        {
          temperatureQualifier: {
            text: 'frozen',
            coding: [
              {
                system: 'http://terminology.hl7.org/CodeSystem/handling-condition',
                code: 'frozen',
                display: 'frozen',
              },
            ],
          },
          maxDuration: {
            value: 28,
            unit: 'day',
            system: UCUM,
            code: 'd',
          },
        },
      ],
    },
    // Second output is a green-capped tube
    {
      preference: 'preferred',
      container: {
        type: {
          coding: [
            {
              system: SNOMED,
              code: '467989009',
              display: 'Capillary blood collection tube, no-additive',
            },
          ],
        },
        cap: {
          coding: [
            {
              system: 'http://terminology.hl7.org/CodeSystem/container-cap',
              code: 'green',
            },
          ],
          text: 'green cap',
        },
      },
    },
  ],
};

Define your clinical observations​

Define your specimens​

Define your services​

Define your lab procedures​

ActivityDefinitions​

The Simple Case​

Patient-facing service

Laboratory Procedure

Reusing Procedures​

Patient-facing service

Laboratory Procedures

Testosterone Procedure

Electrolytes Procedure

Querying your catalog​

Putting it all together​

Men's Health

Women's Health

Testosterone

Estradiol

Electrolytes

Free Testosterone

Estradiol

Sodium

Potassium

Chloride

CO2

Finger-prick Capillary Blood

Define your clinical observations

Define your specimens

Define your services

Define your lab procedures

ActivityDefinitions

The Simple Case

Reusing Procedures

Querying your catalog

Putting it all together