FHIR 擴充功能

本頁說明 Cloud Healthcare API 如何支援 FHIR 擴充功能。

總覽

FHIR 允許使用者在資源和資料類型上定義擴充功能。Cloud Healthcare API 支援儲存及擷取這些擴充功能。

擴充功能值

擴充元素是鍵/值組合，這個鍵值儲存在 url 欄位中，用於指出擴充功能定義的標準網址，該定義會定義擴充功能的內容和含義。value 欄位是選擇元素，可包含多種不同的 FHIR 資料類型。

所有 FHIR 版本都採用相同的機制，但早期版本可用的資料類型較少。如要查看擴充資料的可用資料類型，請參閱 FHIR 標準 (DSTU2、STU3、R4)。

以下範例顯示 Patient 資源，其中根元素含有兩個擴充功能：頭髮顏色和國籍：

{
  "resourceType": "Patient",
  "active": true,
  "gender": "male",
  "extension": [
    {
      "url": "http://example.com/fhir/StructureDefinition/hair-color",
      "valueString": "brown"
    },
    {
      "url": "http://example.com/fhir/StructureDefinition/patient-citizenship",
      "valueCodeableConcept": {
        "coding" : [{
          "system" : "urn:iso:std:iso:3166",
          "code" : "US"
        }]
      }
    }
  ]
}

複雜資料類型和含有子欄位的元素也可以有擴充功能；舉例來說，這個 Patient 包含 identifier 欄位的擴充功能，該欄位為複雜資料類型，以及 communication 欄位的擴充功能，該欄位含有其他子欄位：

{
  "resourceType": "Patient",
  "active": true,
  "gender": "male",
  "identifier": [
    "system": "MRN",
    "value": "AB1234",
    "extension": [
      {
        "url": "http://example.com/fhir/StructureDefinition/last-verified",
        "valueDateTime": "2021-01-01T00:00:00Z"
      }
    ]
  ],
  "communication": [
    {
      "language": {
        "coding": [{
          "system": "urn:iso:std:iso:639",
          "code": "EN"
        }]
      },
      "extension": [
        {
          "url": "http://example.com/fhir/StructureDefinition/fluency-level",
          "valueInteger": 7
        }
      ]
    }
  ]
}

每個擴充功能元素只能有一個值欄位。如要定義包含值陣列的擴充功能，您必須使用相同的 url 定義多個擴充功能元素。

您無法在下列資源類型的根元素中定義擴充功能：

  • Binary
  • Bundle
  • Parameters

複雜擴充功能

擴充資料可包含擴充資料，用於定義巢狀結構。子擴充功能的 url 名稱會相對於外部擴充功能。每個擴充功能元素都必須包含值元素或巢狀子擴充功能，但不能同時包含兩者。

以下範例顯示 Patient 資源，其中包含複雜的 patient-citizenship 擴充功能，以及子擴充功能 code 和 period：

{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
      "extension": [
        {
          "url": "code",
          "valueCodeableConcept": {
            "coding": [{
              "system": "urn:iso:std:iso:3166",
              "code": "CA"
            }]
           }
        },
        {
          "url": "period",
          "valuePeriod": {
            "start": "2010-01-01"
          }
        }
      ]
      }
  ]
}

原始類型的擴充功能

FHIR 中的原始資料類型也可能有擴充資料。以 JSON 格式表示時，擴充功能會以額外的 JSON 屬性表示，並在原始元素名稱前方加上 _，如 FHIR JSON 表示法所定義。

以下 JSON 格式範例顯示 Patient 資源，其中 birthDate 欄位有擴充功能：

{
  "resourceType": "Patient",
  "active": true,
  "gender": "male",
  "birthDate": "1970-01-01",
  "_birthDate": {
    "extension": [
      {
        "url": "http://example.com/fhir/StructureDefinition/date-type",
        "valueString": "A"
      }
    ]
  }
}

如果原始元素重複，含有 _ 的屬性也會視為陣列處理，其中的空值會用於將擴充功能值與對應的原始元素對齊。

以下範例顯示 Patient 資源，其中 name.given 的第二個值含有擴充資料，但第一個值則沒有：

{
  "resourceType": "Patient",
  "name": {
    "given": [
      "ABC",
      "DEF"
    ],
    "_given": [
      null,
      {
        "extension": [
          {
            "url": "http://hl7.org/fhir/StructureDefinition/display",
            "valueString": "XYZ"
          }
        ]
      }
    ]
  }
}

使用 StructureDefinition 定義擴充功能

為了達到互通性，擴充功能的名稱和意義可透過 StructureDefinition 資源定義，並發布或散發，讓資料的使用者能夠解讀。在 Cloud Healthcare API 中使用擴充功能時，這項操作為選用項目。

這個定義的 ID 會在「url」欄位中以「canonical url」表示。對於機構間交換的任何資料，建議使用資料消費者可以遵循的網址來取得 StructureDefinition。Cloud Healthcare API 不會驗證這個網址或嘗試解析該網址。

StructureDefinition 資源的內容可能相當複雜，通常會使用編寫 FHIR 設定檔的工具來定義。

修飾符擴充功能

修飾符擴充功能與擴充功能類似，但會儲存在 modifierExtension 欄位中。修飾符擴充功能是無法忽略的額外資料，因為這可能會使包含該資料的元素解讀無效。

舉例來說，修飾符擴充功能可以指出患者「沒有」特定病症，或是「不應」開立某種藥物。

Cloud Healthcare API 會儲存及擷取修飾符擴充功能，但不會嘗試解讀其含義。應用程式遇到不瞭解的修飾符擴充功能時，建議採取適當行動，例如顯示警告或完全拒絕資源。實作者應盡可能避免使用修飾符擴充功能。