On this page

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](/content/docs/compliance/clia-cap/index.html)
- [Streamlined billing](/content/docs/compliance/clia-cap/index.html)

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.

## 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 HBA1c percentage.

The [`Observation`](/content/docs/api/fhir/resources/observation/index.html) is the primary _operational_ resource used to record a clinical quantity for a specific patient. [`ObservationDefinition`](/content/docs/api/fhir/resources/observationdefinition/index.html) is the corresponding _administrative_ counterpart, and is used to define how an [`Observation`](/content/docs/api/fhir/resources/observation/index.html) should be measured, interpreted, and reported.

### Example: Blood Sodium Level

```ts
{
  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".

### Example: Capillary Blood Sample

```ts
{
  resourceType: 'SpecimenDefinition',
  id: 'fingerprick-capillary-blood',
  typeCollected: {
    coding: [
      {
        system: SNOMED,
        code: '122554006',
        display: 'Capillary Blood Specimen',
      },
    ],
  },
  collection: [
    {
      coding: [
        {
          system: SNOMED,
          code: '278450005',
          display: 'Finger-prick sampling',
        },
      ],
    },
  ],
  typeTested: [
    {
      preference: 'preferred',
      container: {
        type: {
          coding: [
            {
              system: SNOMED,
              code: '467989009',
              display: 'Capillary blood collection tube, no-additive',
            },
          ],
        },
      },
    },
  ],
};
```

## Define your services
The next step is to roll up your individual tests into **orderable services** that your patients can order.

### Example: Men's Health Panel

```ts
{
  resourceType: 'PlanDefinition',
  id: 'example-lab-service-mens-health',
  status: 'active',
  url: 'http://example.org/PlanDefinition/lab-service-mens-health',
  identifier: [
    {
      use: 'official',
      value: 'mens_health_panel_test',
    },
  ],
  name: 'mens-health-panel',
  title: "Men's Health Panel",
  description: "Men's health-related laboratory tests",
  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',
          },
        ],
      },
    },
  ],
};
```

### Define your lab procedures
Now that you have represented your service menu as [`PlanDefinitions`](/content/docs/api/fhir/resources/plandefinition/index.html) , you will use [`ActivityDefinition`](/content/docs/api/fhir/resources/activitydefinition/index.html) resource to define your corresponding procedures to fulfill each service.

### Example: Electrolyte Panel

```ts
{
  resourceType: 'ActivityDefinition',
  id: 'lab-procedure-electrolytes-panel-blood',
  status: 'active',
  name: 'electrolytes-panel-blood-measurement-procedure',
  title: 'Procedure - Electrolytes panel measurement in blood',
  url: 'http://example.org/lab-procedure-electrolytes-panel-blood',
  identifier: [
    {
      use: 'official',
      value: 'electrolytes_panel_test',
    },
  ],
  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' }],
};
```

## Querying your catalog
You can query all [`PlanDefinitions`](/content/docs/api/fhir/resources/plandefinition/index.html) that represent a laboratory procedure using TypeScript, CLI, or cURL.

### TypeScript Example

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

### cURL Example

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

## Putting it all together
Now we'll put all these concepts together to model a basic lab catalog.