Questa pagina spiega come l'API Cloud Healthcare supporta le estensioni FHIR.
Panoramica
FHIR consente estensioni definite dall'utente per risorse e tipi di dati. L'API Cloud Healthcare supporta l'archiviazione e il recupero di queste estensioni.
Valori delle estensioni
Un elemento di estensione è una coppia chiave-valore. La chiave, memorizzata nel campo url, indica l'URL canonico di una definizione di estensione che definisce i contenuti e il significato dell'estensione. Il campo value è un elemento di scelta
che può contenere molti tipi di dati FHIR diversi.
Questo meccanismo è lo stesso in tutte le versioni di FHIR, tranne per il fatto che le versioni precedenti hanno meno tipi di dati disponibili. I tipi di dati disponibili per le estensioni sono riportati nello standard FHIR (DSTU2, STU3, R4).
L'esempio seguente mostra una risorsa Patient con due estensioni, colore dei capelli
e cittadinanza, nell'elemento principale:
{
"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"
}]
}
}
]
}
Anche i tipi di dati complessi e gli elementi con campi secondari possono avere estensioni. Ad esempio, questo Patient contiene un'estensione del campo identifier, che è un tipo di dati complesso, e un'estensione del campo communication, che ha altri campi secondari:
{
"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
}
]
}
]
}
Ogni elemento dell'estensione può avere un solo campo del valore. Per definire un'estensione che contiene un array di valori, devi definire più elementi di estensione con lo stesso url.
Non puoi definire estensioni nell'elemento principale per i seguenti tipi di risorse:
BinaryBundleParameters
Estensioni complesse
Le estensioni possono contenere estensioni per definire una struttura nidificata. Il nome url
dell'estensione secondaria è relativo all'estensione esterna. Ogni elemento di estensione deve avere un elemento di valore o un'estensione secondaria nidificata, ma non entrambi.
L'esempio seguente mostra una risorsa Patient che contiene un'estensione patient-citizenship complessa con estensioni secondarie 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"
}
}
]
}
]
}
Estensioni sui tipi primitivi
Anche i tipi di dati primitivi in FHIR possono avere estensioni. Quando sono rappresentate in formato JSON, le estensioni sono rappresentate in un'altra proprietà JSON con _ anteposto al nome dell'elemento primitivo, come definito nella rappresentazione JSON di FHIR.
Il seguente esempio, in formato JSON, mostra una risorsa Patient con un'estensione nel 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 l'elemento primitivo viene ripetuto, la proprietà con _ viene gestita anche come array, con valori null utilizzati per allineare i valori dell'estensione ai relativi elementi primitivi.
L'esempio seguente mostra una risorsa Patient con un'estensione per il secondo valore di name.given, ma nessuna estensione per il primo valore:
{
"resourceType": "Patient",
"name": {
"given": [
"ABC",
"DEF"
],
"_given": [
null,
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/display",
"valueString": "XYZ"
}
]
}
]
}
}
Definire un'estensione con un StructureDefinition
Ai fini dell'interoperabilità, il nome e il significato di un'estensione possono essere definiti con una risorsa StructureDefinition che può essere pubblicata o distribuita per consentire ai consumatori dei dati di interpretarla. Questo passaggio è facoltativo
quando utilizzi le estensioni nell'API Cloud Healthcare.
L'identità di questa definizione è indicata dall'URL canonico
nel campo "url". Per tutti i dati scambiati tra le organizzazioni,
è consigliabile utilizzare un URL che i consumatori di dati possono seguire
per ottenere il StructureDefinition. L'API Cloud Healthcare non convalida questo URL né tenta di risolverlo.
I contenuti di una risorsa StructureDefinition possono essere complessi e spesso vengono definiti utilizzando strumenti per la creazione di profili FHIR.
Estensioni dei modificatori
Le estensioni modificatori
sono simili alle estensioni, ma vengono memorizzate nel campo modifierExtension. Un'estensione del modificatore è costituita da dati aggiuntivi che non possono essere ignorati perché potrebbero invalidare l'interpretazione dell'elemento che li contiene.
Ad esempio, un'estensione del modificatore potrebbe indicare che il paziente non ha la condizione specificata o che un farmaco non deve essere prescritto.
L'API Cloud Healthcare archivia e recupera le estensioni dei modificatori, ma non tenta di interpretarne il significato. È consigliabile che le applicazioni intraprendano azioni appropriate quando rilevano un'estensione del modificatore che non comprendono, ad esempio mostrando un avviso o rifiutando completamente la risorsa. Gli implementatori devono evitare l'uso di estensioni di modificatori, se possibile.