使用Firely .NET SDK调用EPIC FHIR API创建患者的结构错误问题

问题详情 #

我在EPIC沙箱的FHIR R4 Patient端点创建患者时遇到结构错误：Postman使用官方示例Payload能成功创建，但Firely .NET SDK生成的JSON存在两个问题——每个字段多了一层value嵌套，且缺少resourceType字段，导致EPIC API返回结构解析失败的致命错误。

Postman可成功的Payload #

{"resourceType": "Patient","identifier": [{"use": "usual","system": "urn:oid:2.16.840.1.113883.4.1","value": "000-00-0000"}],"name": [{"use": "usual","family": "family","given": ["firstName","lastName"]}],"gender": "male","birthDate": "2000-01-01"}

Firely SDK生成的错误Payload #

{"identifier": [{"system": {"value": "urn:oid:2.16.840.1.113883.4.1"},"value": {"value": "000-00-0000"}}],"name": [{"family": {"value": "family"},"given": [{"value": "firstName"},{"value": "lastName"}]}],"gender": {"value": "male"},"birthDate": {"value": "2000-10-10"}}

创建患者的代码 #

public Patient CreatePatient(){
    Patient newPatient = new Patient();
    // Add identifier
    newPatient.Identifier.Add(new Identifier{
        Use = Identifier.IdentifierUse.Usual,
        System = "urn:oid:2.16.840.1.113883.4.1",
        Value = "000-00-0000"
    });
    // Add name
    newPatient.Name.Add(new HumanName{
        Use = HumanName.NameUse.Usual,
        Family = "family",
        Given = new string[] { "firstName", "lastName" }
    });
    // Set gender
    newPatient.Gender = AdministrativeGender.Male;
    // Set birth date
    newPatient.BirthDate = "2000-10-10";
    // Send FHIR request to create patient on the server
    var response = _fhirService.Execute(client => client.Create(newPatient));
    if (response is NewPatient patient){
        return patient;
    }else{
        throw new Exception("Failed to create patient");
    }
}

尝试的序列化代码 #

// Serialize the Patient instance to JSON
var serializer = new FhirJsonSerializer();
string json = serializer.SerializeToString(newPatient);

收到的错误响应 #

<OperationOutcome xmlns="http://hl7.org/fhir">
<issue>
    <severity value="fatal" />
    <code value="structure" />
    <diagnostics value="Failed to parse; structural issues in the content." />
    <expression value="$this" />
</issue>
</OperationOutcome>

解决方案 #

问题根源是Firely SDK默认启用了元素模式（Element Mode），这种模式会将FHIR元素序列化为带value嵌套的结构，而EPIC FHIR API需要标准的资源模式（Resource Mode）。解决步骤如下：

1. 配置序列化器为资源模式
   初始化FhirJsonSerializer时，关闭元素模式并指定FHIR R4版本：

var serializerSettings = new SerializerSettings
{
    Format = Format.Json,
    UseElementMode = false, // 关键：禁用元素模式
    Pretty = true
};
var serializer = new FhirJsonSerializer(serializerSettings, ModelInfo.ModelInspector);
string json = serializer.SerializeToString(newPatient);

2. 配置FhirClient使用资源模式
   如果用Firely的FhirClient发送请求，需在客户端设置中同步配置序列化参数，确保请求体格式正确：

var clientSettings = new FhirClientSettings
{
    PreferredFormat = ResourceFormat.Json,
    SerializerSettings = new SerializerSettings { UseElementMode = false }
};
var client = new FhirClient("https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4", clientSettings);
var response = client.Create(newPatient);

3. 验证生成的JSON结构
   修改后生成的JSON应包含resourceType字段，且所有字段不再有value嵌套，与Postman的示例结构完全一致。

原因说明 #

Firely SDK的元素模式主要用于序列化单个FHIR元素（如单独的Identifier对象），而创建患者需要序列化完整的Patient资源，必须使用资源模式。资源模式会自动添加resourceType字段，并直接输出字段原始值，符合FHIR REST API的格式要求。

内容的提问来源于stack exchange，提问作者Fayaz shaik