Nesta página, explicamos como a API Cloud Healthcare oferece suporte a extensões FHIR.
Visão geral
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 "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.