Questa pagina spiega in che modo l'API Cloud Healthcare supporta le estensioni FHIR.
Panoramica
FHIR consente le estensioni definite dall'utente su risorse e tipi di dati. L'API Cloud Healthcare supporta l'archiviazione e il recupero di queste estensioni.
Valori estensione
Un elemento estensione è una coppia chiave-valore. La chiave, memorizzata nel campo url, indica l'URL canonico della definizione di un'estensione che ne definisce i contenuti e il significato. Il campo value è un elemento a scelta
che può contenere molti tipi diversi di dati FHIR.
Questo meccanismo è lo stesso per tutte le versioni FHIR, ma le versioni precedenti hanno meno tipi di dati disponibili. I tipi di dati disponibili per le estensioni sono disponibili nello standard FHIR (DSTU2, STU3, R4).
L'esempio seguente mostra una risorsa Patient con due estensioni, colore dei capelli e cittadinanza, sull'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 per il campo identifier, che è un tipo di dati complesso, e un'estensione nel campo communication, che contiene 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 estensione può avere un solo campo valore. Per definire un'estensione che contiene un array di valori, devi definire più elementi dell'estensione con lo stesso url.
Non puoi definire le 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 valore o un'estensione figlio 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 rappresentate in formato JSON, le estensioni vengono rappresentate in una proprietà JSON aggiuntiva con _ anteposto al nome dell'elemento primitivo, come definito nella rappresentazione JSON FHIR.
L'esempio seguente, 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, anche la proprietà con _ viene gestita come un array, con valori null utilizzati per allineare i valori delle estensioni alle rispettive primitive corrispondenti.
L'esempio seguente mostra una risorsa Patient con un'estensione sul secondo valore di name.given ma nessuna estensione sul primo:
{
"resourceType": "Patient",
"name": {
"given": [
"ABC",
"DEF"
],
"_given": [
null,
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/display",
"valueString": "XYZ"
}
]
}
]
}
}
Definizione di 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 interpretarli. Questa operazione è facoltativa quando si utilizzano estensioni nell'API Cloud Healthcare.
L'identità di questa definizione è indicata dall'URL canonico nel campo "url". Per i dati scambiati tra organizzazioni,
è consigliabile utilizzare un URL che i consumatori di dati possono seguire
per ottenere l'StructureDefinition. L'API Cloud Healthcare non convalida questo URL o non tenta di risolverlo.
I contenuti di una risorsa StructureDefinition possono essere complessi e vengono spesso definiti utilizzando strumenti per la creazione di profili FHIR.
Estensioni di modifica
Le estensioni di modifica
sono simili alle estensioni, ma vengono memorizzate nel campo modifierExtension. Un'estensione di modifica è un dato aggiuntivo che non può essere ignorato perché potrebbe invalidare l'interpretazione dell'elemento che la contiene.
Ad esempio, un'estensione di modifica potrebbe indicare che il paziente non presenta la condizione specificata o che non deve essere prescritto un farmaco.
L'API Cloud Healthcare archivia e recupera le estensioni di modifica, ma non cerca di interpretarne il significato. Si consiglia alle applicazioni di intraprendere le azioni appropriate quando incontrano un'estensione di modifica che non comprendono, ad esempio mostrando un avviso o rifiutando completamente la risorsa. Se possibile, gli implementazioni dovrebbero evitare di utilizzare le estensioni di modifica.