Extensões FHIR

Nesta página, explicamos como a API Cloud Healthcare oferece suporte a extensões FHIR.

Informações gerais

O FHIR permite extensões definidas pelo usuário em recursos e tipos de dados. A API Cloud Healthcare é oferece suporte ao armazenamento e à recuperação dessas extensões.

Valores de extensão

Um elemento de extensão é um par de chave-valor. A chave, armazenada no campo url, indica o URL canônico de uma definição de extensão que define o conteúdo e o significado da extensão. O campo value é um elemento de opção que pode conter muitos tipos de dados do FHIR diferentes.

Esse mecanismo é o mesmo em todas as versões do FHIR, mas as versões anteriores têm menos tipos de dados disponíveis. Os tipos de dados disponíveis para extensões podem ser encontrados no padrão FHIR (DSTU2, STU3, R4).

O exemplo a seguir mostra um recurso Patient com duas extensões, cor do cabelo e cidadania, no elemento raiz:

{
  "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"
        }]
      }
    }
  ]
}

Tipos de dados complexos e elementos com campos filhos também podem ter extensões. Por exemplo, este Patient contém uma extensão no campo identifier que é um tipo de dados complexo, e uma extensão no campo communication que tem outros campos filhos:

{
  "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
        }
      ]
    }
  ]
}

Cada elemento de extensão pode ter apenas um campo de valor. Para definir uma extensão que tenha uma matriz de valores, defina vários elementos de extensão com o mesmo url.

Não é possível definir extensões no elemento raiz para os seguintes tipos de recursos:

• Binary
• Bundle
• Parameters

Extensões complexas

As extensões podem conter extensões para definir uma estrutura aninhada. O nome url da extensão filha é relativo à extensão externa. Cada elemento de extensão precisa ter um elemento de valor ou uma extensão filha aninhada, mas não ambos.

O exemplo a seguir mostra um recurso Patient que tem uma extensão patient-citizenship complexa com extensões filhas code e 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"
          }
        }
      ]
      }
  ]
}

Extensões em tipos primitivos

Os tipos de dados primitivos no FHIR também podem ter extensões. Quando representadas no formato JSON, as extensões são representadas em outra propriedade JSON com _ anexado ao nome do elemento primitivo, conforme definido na representação JSON do FHIR.

No exemplo a seguir, no formato JSON, mostramos um recurso Patient com uma extensão no campo birthDate:

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

Se o elemento primitivo for repetido, a propriedade com _ também será processada como uma matriz, com valores nulos, usados para alinhar os valores de extensão com os primitivos correspondentes.

No exemplo a seguir, mostramos um recurso Patient com uma extensão no segundo valor de name.given, mas nenhuma extensão no primeiro valor:

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

Como definir uma extensão com um StructureDefinition

Para fins de interoperabilidade, o nome e o significado de uma extensão podem ser definidos com um recurso StructureDefinition que pode ser publicado ou distribuído para permitir que os consumidores dos dados os interpretem. Isso é opcional ao usar extensões na API Cloud Healthcare.

A identidade dessa definição é indicada pelo URL canônico no campo "URL". Para dados trocados entre organizações, é recomendável usar um URL que os consumidores de dados possam seguir para conseguir o StructureDefinition. A API Cloud Healthcare não valida esse URL nem tenta resolvê-lo.

O conteúdo de um recurso StructureDefinition pode ser complexo e geralmente é definido usando ferramentas para criar perfis FHIR.

Extensões modificadoras

Extensões modificadoras são semelhantes a extensões, mas são armazenadas no campo modifierExtension. Uma extensão modificadora é o dado adicional que não pode ser ignorado porque pode invalidar a interpretação do elemento que o contém.

Por exemplo, uma extensão modificadora pode indicar que o paciente não tem a condição especificada ou que um medicamento não pode ser prescrito.

A API Cloud Healthcare armazena e recupera extensões modificadoras, mas não tenta interpretar o significado delas. Recomendamos que sejam adotadas medidas adequadas pelos aplicativos ao encontrar uma extensão modificadora que eles não entendam, possivelmente exibindo um aviso ou rejeitando completamente o recurso. Os implementadores precisam evitar o uso de extensões modificadoras sempre que possível.