将Apple DSTU2记录转FHIR R4时AWS Healthlake报错的排查修复

提交的Observation资源 #

{  
  "category": [    
    {      
      "text": "Vital Signs",      
      "coding": [        
        {          
          "system": "http://hl7.org/fhir/observation-category",          
          "code": "vital-signs"        
        }      
      ]    
    }  
  ],  
  "issued": "2017-03-18T00:00:00Z",  
  "status": "final",  
  "id": "49a1b0f9-34c2-472d-8b64-34447d307c56",  
  "code": {    
    "text": "Temperature",    
    "coding": [{ "system": "http://loinc.org", "code": "8310-5" }]  
  },  
  "encounter": { "reference": "Encounter/355" },  
  "subject": { "reference": "Patient/82146c45-a7cd-47ee-a5ba-8c588d4c5c9e" },  
  "valueQuantity": {    
    "code": "Cel",    
    "system": "http://unitsofmeasure.org",    
    "value": 37.6,    
    "unit": "Cel"  
  },  
  "resourceType": "Observation",  
  "meta": { "lastUpdated": "2023-01-30T09:17:54.772Z" }
}

服务器返回错误 #

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"This property must be an Array, not an array","location":["Observation.category[0]"]}]}

错误含义 #

这个错误提示措辞存在矛盾，但结合FHIR R4规范和Healthlake校验逻辑，实际指向Observation.category[0]的结构不符合预期：

• 大概率是JSON序列化/转换过程中，category[0]的类型被错误处理（比如单元素数组被转为单个对象，或结构嵌套不符合FHIR要求）；
• 也可能是Healthlake校验器的措辞bug，实际是指category[0]内部的coding字段需要严格的数组格式（尽管提交的JSON中coding已是数组，但可能存在序列化类型识别问题）。

修复方案 #

1. 验证JSON结构完整性：确认发送的原始请求中，category确实是数组结构，没有被转换工具误转为单个CodeableConcept对象。可通过打印请求payload或抓包验证。
2. 完善Coding字段：给coding数组中的元素补充display字段，符合FHIR R4 Coding类型的规范要求，修改后的category部分如下：

   "category": [    
     {      
       "text": "Vital Signs",      
       "coding": [        
         {          
           "system": "http://hl7.org/fhir/observation-category",          
           "code": "vital-signs",
           "display": "Vital Signs"        
         }      
       ]    
     }  
   ]
   

3. 强制数组类型：如果转换工具存在单元素数组自动转对象的逻辑，手动强制保留数组结构（比如在转换代码中明确指定category为数组，即使只有一个元素）。
4. 测试多元素场景：临时在category数组中添加第二个CodeableConcept元素，验证是否还触发相同错误，以此排除单元素数组的识别问题。

内容的提问来源于stack exchange，提问作者Shubham Gupta