No artigo anterior, vimos o problema que o FHIR resolve e como ele se posiciona na história da interoperabilidade em saúde. Antes de entrar nos aspectos técnicos do padrão — o que faremos a partir do próximo artigo —, vale parar em um detalhe de design que costuma passar despercebido por quem chega à especificação vindo de outras APIs: o FHIR foi construído para ser lido, e não só consumido programaticamente.
O princípio de design: recursos legíveis por humanos
Boa parte das APIs que um desenvolvedor encontra no dia a dia é pensada exclusivamente para máquinas conversarem entre si. Os nomes dos campos são abreviados, a estrutura é otimizada para performance ou para conveniência de quem implementou o backend, e ninguém espera que uma pessoa de fora da área técnica abra o JSON e entenda alguma coisa.
O FHIR toma uma decisão diferente. Um dos princípios mais repetidos por quem já trabalhou com a especificação é que os recursos são modelados para refletir conceitos clínicos reconhecíveis — não abstrações de banco de dados. Um recurso chamado Patient representa um paciente. Um recurso chamado Condition representa uma condição clínica. Um MedicationRequest representa a prescrição de um medicamento. Não há tradução necessária entre “o que o sistema chama isso” e “o que isso significa clinicamente” — o nome técnico e o conceito do mundo real coincidem.
Essa escolha não é um acaso. Ela existe para que um profissional de saúde — alguém que nunca escreveu uma linha de código — consiga olhar para uma representação de um recurso FHIR e reconhecer a informação clínica ali dentro, sem precisar de um desenvolvedor para “traduzir” a estrutura.
Um exemplo prático: o mesmo JSON, dois olhares diferentes
Para tornar isso concreto, veja um trecho simplificado de um recurso Patient:
{
"resourceType": "Patient",
"name": [
{ "text": "Maria Aparecida da Silva" }
],
"gender": "female",
"birthDate": "1985-03-22",
"address": [
{ "city": "Recife", "state": "PE" }
]
}Um desenvolvedor olha para esse trecho e enxerga um objeto JSON: uma string aqui, um array ali, um campo de data em formato ISO. Um médico ou enfermeiro que nunca viu uma chave ou colchete na vida olha para o mesmo trecho e enxerga outra coisa: uma paciente chamada Maria Aparecida, do sexo feminino, nascida em 22 de março de 1985, residente em Recife. A estrutura técnica e a leitura clínica coexistem no mesmo artefato — e essa é exatamente a intenção por trás do design do recurso.
Isso se torna ainda mais evidente em recursos clínicos como Observation, que representa um resultado de exame ou uma medição: campos como code (o que foi medido), value (o resultado) e effectiveDateTime (quando foi medido) são nomeados de um jeito que qualquer pessoa que já leu um resultado de exame reconhece a lógica, mesmo sem saber o que é um “recurso FHIR”.
A dualidade oficial: introdução para desenvolvedores e introdução clínica
Esse cuidado com múltiplos públicos não é uma interpretação livre da comunidade — está na própria porta de entrada da especificação. A página inicial da spec FHIR direciona explicitamente para dois caminhos de leitura distintos: uma introdução voltada a desenvolvedores, focada em como consumir a API, nos formatos de dados e nos detalhes de implementação; e uma introdução clínica, que explica os mesmos conceitos a partir da perspectiva de quem presta cuidado em saúde, sem exigir conhecimento prévio de programação.
Essa dualidade declarada é um bom indicador de que a legibilidade multi-público não é um efeito colateral, mas um objetivo de design perseguido conscientemente pela HL7 desde a concepção do padrão — algo raro em especificações técnicas, que normalmente assumem um único tipo de leitor.
Onde essa legibilidade encontra seus limites
Dito isso, seria um exagero afirmar que qualquer recurso FHIR é 100% autoexplicativo para um leigo em tecnologia. Essa legibilidade tem fronteiras claras:
- Terminologias codificadas: muitos campos clínicos não trazem texto livre, mas códigos de sistemas de terminologia (como LOINC ou SNOMED CT) — um código como
"code": "85354-9"não diz nada a ninguém sem o contexto do sistema que o define. Vamos aprofundar esse tema no artigo 4, sobre CodeSystems. - Cardinalidade e regras de obrigatoriedade: entender que um campo pode se repetir, ser opcional, ou depender de outro campo é uma camada de leitura técnica que a spec formaliza, e que não é óbvia a partir do JSON isolado.
- Extensões: campos customizados, identificados por URLs canônicas em vez de nomes legíveis, são propositalmente técnicos — tema do artigo 6.
Ou seja: a legibilidade clínica convive com a formalidade técnica do padrão, mas não a substitui. Um médico consegue reconhecer o quê está sendo dito em um recurso; entender as regras por trás daquela estrutura ainda é trabalho de quem desenvolve.
Por que isso importa na prática
Esse detalhe de design tem uma consequência prática direta em qualquer projeto de integração em saúde: ele reduz a distância entre times clínicos e times de engenharia. Quando um analista de negócio ou um profissional de saúde consegue olhar para um payload de exemplo e validar se a informação ali representada faz sentido clinicamente — sem depender inteiramente de um desenvolvedor para explicar cada campo —, o processo de levantamento de requisitos, validação de mapeamento de dados e revisão de casos de uso fica mais rápido e com menos ruído de comunicação.
Isso não elimina a necessidade de conhecimento técnico para implementar uma integração FHIR — mas ajuda a evitar um problema comum em projetos de saúde digital: o de times clínicos e técnicos falando sobre a mesma informação usando vocabulários completamente diferentes.
