Firely valida FHIR em .NET? Pegou 120 de 180 e um erro meu

O validador da Firely 3.6.0 reprovou 120 de 180 recursos FHIR com defeito, contra 80 do HealthChain. Só 20 dos 100 de conteúdo caíram pelo defeito plantado; a referência quebrada foi reprovada em 0 de 20.

Rogério Rodrigues

Rogério Rodrigues

Engenheiro de IA · mestrando em Informática em Saúde (UFSC)

Planta técnica azul: o Firely Validator 3.6.0 em .NET 8 reprovou 120 de 180 recursos FHIR R4B com defeito, contra 80 do HealthChain. Invariante obs-6: 20 de 20. Referência quebrada com UUID válido: 0 de 20. Outros 20 Bundles caíram porque o fullUrl urn:uuid:pac-000 do gabarito não é UUID.

O validador da Firely, em C#, reprovou 120 dos 180 recursos FHIR com defeito. Nos mesmos dados, o HealthChain tinha reprovado 80. São os mesmos 240 recursos sintéticos do teste do HealthChain. Os 80 de forma, de novo. E 40 dos 100 de conteúdo.

Só que, desses 40, apenas 20 caíram pelo defeito que eu plantei: a invariante obs-6. Os outros 20 caíram por um erro meu, no gabarito. Corrigido o erro, a referência quebrada que eu queria testar foi reprovada em 0 de 20. Nos 60 recursos válidos, nenhum falso positivo.

Código, dados e saída gravada: demos/15-firely-validacao-fhir, no nursia-research-lab.

De onde veio a pergunta?

Em 30/10 eu mostrei que o validate_resource() do HealthChain 0.16.1 pega erro de forma e deixa passar todo erro de conteúdo: LOINC inventado, unidade fora do UCUM, referência pra paciente que não existe, CPF com dígito errado e a invariante obs-6. O próprio módulo avisa, no docstring, que não checa binding de código, invariante FHIRPath, perfil nem integridade de referência, e manda usar o $validate de um servidor FHIR.

Ficou a pergunta: e um validador de verdade? Rodei o do Firely .NET SDK nos mesmos 240 arquivos, com o mesmo gabarito. O parser, quando recusa, devolve o recurso parcial, e o validador roda em cima dele.

Como eu rodei?

  • .NET 8 (runtime 8.0.34), CPU, sem chave, sem conta.
  • Hl7.Fhir.R4B 6.8.0 e Firely.Fhir.Validation.R4B 3.6.0, publicado no NuGet em 29/10/2026. Os dois em BSD-3-Clause. O pacote da especificação R4B (Hl7.Fhir.Specification.Data.R4B 6.8.0) vem como um specification.zip local.
  • R4B, não R4. Os 240 recursos da demo 11 são R4B, e rodar com o pacote R4 poderia dar outro resultado.
  • Os dados são uma cópia do recursos.jsonl da demo 11, conferida por SHA-256 no teste: 60 válidos e 180 com um defeito cada, 20 por categoria, em 9 categorias.
  • Terminologia só local. Nenhum servidor de terminologia, nenhum referenceResolver, nenhum perfil além do base.

Cada recurso passa por duas camadas: o deserializador estrito do SDK e o Validator. Conto como reprovado se qualquer uma acusar erro. O miolo, simplificado:

var fonte = new CachedResolver(ZipSource.CreateValidationSource());
var terminologia = LocalTerminologyService.CreateDefaultForCore(fonte);
var validador = new Validator(fonte, terminologia);
var parser = new FhirJsonDeserializer();

var ok = parser.TryDeserializeResource(json, out var recurso, out var errosParser);
var issues = validador.Validate(recurso).Issue;
var reprovou = !ok || errosParser.Any() || issues.Any(i => i.Severity is OperationOutcome.IssueSeverity.Error
                             or OperationOutcome.IssueSeverity.Fatal);

O que eu esperava?

Minha aposta, anotada na pauta do texto: a invariante obs-6 e a referência quebrada dentro do Bundle, o validador pegaria. LOINC inventado e unidade fora do UCUM, só com servidor de terminologia. CPF, não, porque dígito verificador de CPF não é regra do FHIR.

Acertei a obs-6 e o CPF. Errei a referência. E a de LOINC e UCUM eu acertei pelo motivo errado, como vocês vão ver mais abaixo.

O que deu?

Números de results/tabela.md, com os rótulos reescritos e o HealthChain do lado:

Defeito colocado Tipo HealthChain 0.16.1 Firely 3.6.0
Campo obrigatório ausente forma 20 de 20 20 de 20
Data em dd/mm/aaaa forma 20 de 20 20 de 20
Campo que não existe no recurso forma 20 de 20 20 de 20
Valor fora do conjunto obrigatório (code) forma 20 de 20 20 de 20
Código inventado sob o sistema LOINC conteúdo 0 de 20 0 de 20
Unidade que não é UCUM válida conteúdo 0 de 20 0 de 20
Referência pra um Patient que não está no Bundle conteúdo 0 de 20 20 de 20 (*)
CPF com dígito verificador errado conteúdo 0 de 20 0 de 20
Valor e dataAbsentReason juntos (obs-6) conteúdo 0 de 20 20 de 20
Controle: recurso válido – 0 de 60 0 de 60

(*) Pelo motivo errado. Explico abaixo.

Forma: 80 de 80. Conteúdo: 40 de 100. Total: 120 de 180.

Duas coisas que a tabela não mostra e o raw.jsonl mostra. Primeiro, o parser sozinho já recusa os 80 de forma. Pra esses quatro defeitos, nem precisa do validador. Segundo, a obs-6 é a única categoria que só o validador pega. O parser deixa passar as 20, e o validador responde assim:

Error 1012 Observation
Instance failed constraint obs-6 "dataAbsentReason SHALL only be present if Observation.value[x] is not present"

Esse é o ganho real sobre o HealthChain: invariante FHIRPath do perfil base, conferida de verdade.

Que erro o validador achou no meu gabarito?

Quando vi 20 de 20 na referência quebrada, fui ler a mensagem. Não era a referência:

string 'urn:uuid:pac-000' is not a correct literal for a uri. At Bundle.entry[0].fullUrl

Confesso que esse erro é meu. Quando montei os Bundles da demo 11, usei urn:uuid:pac-000 como fullUrl. Parece UUID, mas não é. Um urn:uuid: pede um UUID de verdade, com 32 dígitos hexadecimais. O HealthChain aceitou sem reclamar, e eu nem percebi. A Firely recusou no parser, antes de olhar a referência.

Ou seja: o 20 de 20 mede o fullUrl, não a referência. Pra medir a referência, fiz um controle. Troquei o fullUrl por um UUID válido (derivado do id, pra ser reprodutível) e rodei os 20 Bundles em duas variantes:

  • A: a Observation aponta pra Patient/fantasma-N, que não está no Bundle. É o defeito que eu queria testar.
  • B: a Observation aponta pro fullUrl do Patient que está no Bundle. É o controle, deve passar.

Resultado do controle-referencia.jsonl: A, 0 de 20 reprovados e 0 com aviso. B, 0 de 20. Com a configuração padrão, a referência pra um paciente que não existe passa limpa.

Fui conferir no próprio pacote da especificação se isso é bug. Pelo perfil base, não é. O script conferir_perfil.py lê o specification.zip que o NuGet trouxe e lista as invariantes do Bundle no perfil base R4B (results/perfil-base.txt). Nenhuma delas exige que a referência de uma entrada resolva pra outra entrada. Os meus Bundles são do tipo collection. O validador seguiu o perfil base.

É como o fiscal que confere se o crachá está no formato certo e não confere se o nome está na lista que ele tem na mão. O formato errado ele pegou. O nome que não está na lista, não, porque ninguém mandou ele conferir.

O que o validador NÃO pega sozinho?

  • Referência que não resolve. Nenhuma invariante do Bundle exige isso. Sem referenceResolver e sem perfil que exija aggregation bundled, ninguém confere. Não testei nenhum dos dois; com eles o resultado pode mudar.
  • Código LOINC inventado. No perfil base, o binding de Observation.code é só de exemplo (example). Por isso FC-0000 sob http://loinc.org passou sem aviso. Minha aposta era “falta servidor de terminologia”. Pode até faltar, mas o primeiro motivo é o perfil. Não testei com servidor.
  • Unidade fora do UCUM. Quantity.code não tem binding no perfil base, e a única regra é a qty-3: se tem código, tem que ter sistema. batimentos/minuto com sistema UCUM cumpre a regra e passa.
  • CPF com dígito errado. Não é regra do FHIR. Só um perfil brasileiro com regra própria pegaria, e eu não validei contra perfil BR. O dígito você confere fora do FHIR, como mostrei no texto do HealthChain.

Ou seja: pra pegar conteúdo, o validador precisa de um perfil que peça. O base pede pouco.

Quanto custa no pipeline?

Montar o validador levou 240 ms. O primeiro recurso de cada tipo paga a compilação do perfil: o primeiro Patient levou 2,4 s, a primeira Observation 2,9 s, a primeira Condition 0,29 s e o primeiro Bundle 0,33 s. Sem contar o primeiro recurso, mediana de 1,42 ms por recurso. Os 240 levaram 6,3 s somados. Rodei mais duas vezes na mesma máquina e a mediana ficou entre 1,37 e 1,59 ms, com as mesmas contagens (results/rodadas.txt).

Pra API que valida na entrada, isso pede um validador quente, criado uma vez e reaproveitado. Só que o README do pacote avisa: o Validator e os resolvers não são thread-safe. Em servidor com várias threads, é uma instância por thread.

Pra quem serve e quando eu não usaria?

Serve pra quem já está em .NET e quer validar FHIR dentro do processo, sem chamar servidor: os quatro defeitos de forma que testei, binding obrigatório e a invariante obs-6 do perfil base, em cerca de 1,4 ms por recurso depois de aquecido. Foi melhor que o HealthChain no que o HealthChain promete não fazer, e acertou os 60 válidos.

O que não foi bom: na configuração padrão ele não confere se a referência resolve, e eu esperava que conferisse. Estava na minha aposta. Só que o perfil base nem pede isso.

Eu não usaria só com o perfil base quando o risco é código clínico errado: o LOINC inventado passa. Aí entra um perfil que amarre o código e, provavelmente, um servidor de terminologia. Também não usaria num pipeline Python puro só por causa disso. Lá, o caminho é o $validate de um servidor FHIR ou o validador Java da HL7, que eu não rodei aqui.

Pra mim, o achado mais útil foi outro: o meu gabarito tinha um defeito que um validador deixou passar e o outro pegou.

Limites

  • O gabarito é meu. 9 categorias, 20 casos cada, escolhidas por mim. O 120 de 180 descreve este conjunto, não FHIR real.
  • Configuração padrão: perfil base R4B, terminologia local, sem resolver de referência, sem perfil próprio. Só o caminho POCO, com o deserializador estrito. Não testei modo permissivo nem Validate(ElementNode).
  • Não rodei o validador Java da HL7 nem servidor de terminologia.
  • Tempo de uma máquina na nuvem, CPU. O seu vai ser outro.
  • Todo dado é sintético. O CPF passa no dígito verificador, mas é sorteado com semente fixa e não pertence a ninguém.

Fonte e como reproduzir

Clone https://github.com/rogeriorrodrigues/nursia-research-lab e entre em demos/15-firely-validacao-fhir. Precisa do .NET 8 SDK e de Python só pro teste. Três comandos:

dotnet run -c Release --project src -- data/recursos.jsonl results
pip install -r requirements.txt
python3 -m pytest tests -q -s

O teste roda a demo do zero numa pasta temporária e confere os números deste texto: 80 de 80, 40 de 100, 0 de 60 e o controle da referência em 0 de 20.

E vocês, validam FHIR no pipeline ou só na entrada da API? E alguém aí liga o resolver de referência em produção?

In English

Firely’s .NET validator (Firely.Fhir.Validation.R4B 3.6.0, Hl7.Fhir.R4B 6.8.0, base R4B profiles, local terminology only) rejected 120 of 180 defective synthetic FHIR resources, against 80 for HealthChain 0.16.1 on the same data: 80/80 structural and 40/100 content. Only 20 of those 40 hit the planted defect (invariant obs-6); the other 20 caught a non-UUID urn:uuid: in my own fixture. With valid UUIDs, a reference to a Patient outside the Bundle was flagged in 0/20. Invented LOINC code, non-UCUM unit and bad CPF check digit passed: the base profile does not ask for any of them. Median 1.42 ms per resource after a cold start.

Demo publicada no repositório do NursIA (PPGINFOS/UFSC, bolsa FAPESC). Publicado em 17/11/2026.

Conhece alguém que precisa ler isso?

Manda pra essa pessoa. Leva dez segundos e é o que mais ajuda esse trabalho a chegar em quem usa IA com dado de verdade.

Rogério Rodrigues

Rogério Rodrigues

Engenheiro de IA há 20 anos em software, mestrando em Informática em Saúde na UFSC. Escrevo o que rodei: IA com dado de saúde, FHIR e LGPD, com código aberto.

Ficou uma dúvida? Discorda de algo? Me chama.

Ver publicações científicas