Vai al contenuto
Richiedi una demo

Blog / Integrazione HL7

Integrazione HL7 · 19/10/2026 · Marco Volpe

PDF in Base64 nei messaggi HL7: la stessa stringa, cinque decoder, verdetti diversi

Un referto PDF incorporato in un OBX, con qualche spazio nel Base64: alcune librerie lo scartano, altre accettano senza obiezioni anche un file troncato. Perché la lunghezza non dice se l'allegato è completo, cosa prevedono MIME, la RFC 4648 e la guida v2-to-FHIR, e come si verifica davvero.

Questo è il segmento OBX di un referto di laboratorio sintetico che abbiamo preparato come caso di prova. Il campo OBX-5 contiene il PDF del referto, incorporato nel messaggio e codificato in Base64. Lo riportiamo accorciato:

OBX|1|ED|11502-2^Laboratory report^LN||^AP^PDF^Base64^JVBERi0xLjQKJeLjz9MK…IFIgPj4K ZW5kb2JqCjIgMCBv…CnN0YXJ0eHJlZgo1MzgKJSVFT0Y =||||||F

OBX-2 vale ED, cioè dati incapsulati; i componenti di OBX-5 dicono che si tratta di un PDF codificato in Base64. Nel testo Base64 ci sono però sei spazi, sparsi in cinque punti: alcuni fra un blocco di quattro caratteri e l’altro, due in mezzo a un blocco, uno subito prima del carattere = finale. Tolti gli spazi, la stringa si decodifica in un PDF di 752 byte che comincia con %PDF-1.4 e finisce con %%EOF, identico byte per byte al file di riferimento: lo abbiamo verificato confrontando l’impronta SHA-256.

Il referto, quindi, c’è. La domanda è se arriva a destinazione, e la risposta dipende da una riga di codice che di solito nessuno guarda: la funzione che decodifica il Base64.

Tre librerie, tre verdetti

Abbiamo dato la stessa stringa ai decoder Base64 delle librerie standard di tre linguaggi molto usati nei motori di integrazione: Python 3.13, Java 21 e Node.js 22. Poi abbiamo ripetuto la prova con due varianti dello stesso PDF: una senza il carattere di riempimento = alla fine, l’altra troncata a circa due terzi della lunghezza, come succede quando un messaggio viene tagliato lungo il percorso.

Decoder Con gli spazi Senza = finale Troncato
Python, modalità rigorosa rifiutato rifiutato rifiutato
Python, modalità predefinita PDF integro rifiutato rifiutato
Java, decoder di base rifiutato PDF integro 503 byte, senza %%EOF
Java, decoder MIME PDF integro PDF integro 503 byte, senza %%EOF
Node.js PDF integro PDF integro 503 byte, senza %%EOF

Gli esiti peggiori sono due, ed esattamente opposti. Un decoder rigoroso scarta un referto integro per colpa di uno spazio. Un decoder tollerante accetta senza obiezioni un PDF troncato: 503 byte che cominciano con l’intestazione giusta e si interrompono a metà. Python rifiuta il file troncato, ma per il motivo sbagliato: segnala un problema di riempimento, e con lo stesso errore rifiuterebbe anche il PDF integro arrivato senza =.

Cosa dicono le regole

Le librerie seguono due regole diverse, ed entrambe esistono. La tabella HL7 v2 delle codifiche (tabella 0299, nella versione pubblicata su HL7 Terminology) definisce Base64 come la codifica dello standard MIME, rimandando alla RFC 1521. Quella RFC è stata sostituita nel 1996 dalla RFC 2045, che fissa righe di al massimo 76 caratteri e chiede al decoder di ignorare ogni carattere che non appartiene all’alfabeto Base64, a capo compresi. Per un messaggio v2, quindi, un decoder che salta gli spazi è in linea con la norma a cui la tabella rimanda.

La RFC 4648, la specifica generale delle codifiche Base64 del 2006, dice il contrario: un’implementazione deve rifiutare i caratteri estranei all’alfabeto e deve includere il riempimento, a meno che la specifica che la richiama non stabilisca altro. E cita proprio MIME come esempio di specifica che lo stabilisce. I decoder rigorosi seguono questa.

Un testo Base64 senza = finale non rispetta nessuna delle due RFC, ma resta decodificabile senza ambiguità quando la sua lunghezza, divisa per quattro, lascia un resto di 2 o 3: sono i due casi in cui la RFC 4648 aggiunge rispettivamente due o un =. Solo un resto di 1 non può corrispondere a nessun dato. La lunghezza, quindi, dice se una stringa è decodificabile, non se il file che contiene è completo: il nostro PDF troncato ha una lunghezza con resto 3 ed è Base64 valido.

Cosa succede nella conversione in FHIR

La guida HL7 v2-to-FHIR prevede che un OBX con tipo ED e codifica Base64 diventi un allegato. In FHIR R4 l’Observation non ammette un valore di tipo Attachment, quindi la guida lo mette in un’estensione presa da R5; in alternativa esiste una mappa dall’OBX a DocumentReference, dove il PDF finisce in content.attachment. Nella mappa del tipo ED, il sottotipo dei dati diventa contentType e i dati vengono convertiti in Base64, con una nota che invita a controllare i dati stessi per stabilire il tipo di contenuto, perché le implementazioni non sono sempre accurate.

Copiare la stringa così com’è non funziona: in R4 il tipo base64Binary ammette spazi solo fra un blocco di quattro caratteri e l’altro, e la nostra stringa, con due spazi dentro un blocco, non rispetta la sua espressione regolare. Il PDF va decodificato, controllato e ricodificato. C’è poi un caso più banale: se il mittente dichiara in OBX-2 un tipo codificato come CE invece di ED, la guida instrada OBX-5 verso un CodeableConcept, e il PDF diventa il testo di un codice.

Come è venuto fuori

In una discussione pubblica su chat.fhir.org dedicata a una raccolta condivisa di casi di test per la conversione da v2 a FHIR, gli sviluppatori di un motore open source hanno raccontato di aver scoperto, su un insieme pubblico di messaggi di prova, che il loro decoder rifiutava i PDF con spazi nel Base64. Il messaggio finiva nel percorso dei valori codificati e il PDF usciva come testo di un codice. Hanno corretto il decoder; noi abbiamo fatto notare che anche il loro criterio per riconoscere un file troncato, basato sulla lunghezza, non reggeva, e lo hanno sostituito con un controllo sul contenuto. Il caso con gli spazi, con il PDF di riferimento e la sua impronta SHA-256, è ora nel repository pubblico dei casi di test che abbiamo aperto per quella raccolta.

La completezza si giudica dal contenuto

Se la lunghezza non basta, serve guardare dentro. Lo standard PDF (ISO 32000-1:2008) stabilisce che la prima riga del file sia un’intestazione che comincia con %PDF- e che l’ultima riga contenga soltanto il marcatore %%EOF. Un file aggiornato in modo incrementale ne contiene più d’uno, perché ogni aggiornamento chiude il proprio trailer con il suo %%EOF: conta l’ultimo, e un a capo dopo di esso va tollerato. È un controllo che un convertitore può fare da solo, e che avrebbe separato il nostro file troncato da quello integro in tutte e cinque le prove. Per un test si può fare di più: conservare accanto al messaggio l’impronta dei byte attesi, così il criterio di successo diventa un confronto, non un’impressione.

Lo stesso PDF in Base64 nel campo OBX-5 dato a cinque decoder. Con spazi nel testo, i decoder rigorosi lo rifiutano e quelli MIME o tolleranti lo decodificano integro in 752 byte. Senza il carattere = finale, Python lo rifiuta mentre Java e Node lo decodificano integro. Troncato, Python lo rifiuta per il motivo sbagliato e Java e Node accettano 503 byte senza il marcatore %%EOF.
Stessa stringa, verdetti diversi. La lunghezza non dice se il PDF è completo: l’intestazione %PDF- e il marcatore %%EOF sì.

Cosa portarsi a casa

  • La tolleranza del decoder è una decisione di progetto, non un default della libreria. Per i messaggi v2 la norma di riferimento è MIME: ignorare spazi e a capo, accettare la mancanza del riempimento con un avviso, rifiutare le lunghezze che non possono corrispondere a nessun dato.
  • Un allegato non si copia: si decodifica, si verifica e si ricodifica nel formato che FHIR accetta.
  • La completezza si giudica dal contenuto: per un PDF, intestazione %PDF- all’inizio e %%EOF alla fine. Dal contenuto si ricava anche il tipo, come suggerisce la stessa guida.
  • OBX-2 va controllato: un ED dichiarato come CE trasforma un referto in un codice.
  • Un allegato che non supera i controlli non deve sparire: resta testo, con un avviso nel report che dice perché.

Da cui due domande da fare all’avvio di un progetto. Al mittente: come vengono spezzati e riempiti i Base64 che inviate? A chi realizza la conversione: quale decoder usate e in quale modalità, e cosa dice il vostro report quando un allegato arriva troncato?

Un caso simile nel vostro progetto?

Scriveteci: partiamo dai vostri casi.