Support for extensions on reference primitive data type

72 views
Skip to first unread message

Maico Bernal

unread,
Jul 23, 2025, 3:54:22 PMJul 23
to GCP Healthcare Discuss
Hello there!

We are implementing template based extraction from Structure Data Capture v4 on GCP on FHIR R4 store. 


In the template-based extraction, you usually create inline contained resources on a Questionnaire, and put an extensión in the reference field (which is a primitive datatype string). This is also a common approach for other primitive datatypes. 

In JSON format, that is written with a under slash as expected by FHIR specification: https://build.fhir.org/json.html#primitive

For example, a derivedFrom field from an Observation template would look like this:

"derivedFrom" : [ { "extension" : [ { "url" : "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-templateExtractContext", "valueString" : "%resource.id" } ], "_reference" : { "extension" : [ { "url" : "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-templateExtractValue", "valueString" : "'QuestionnaireResponse/' + %resource.id" } ] } } ]
You can check the full example here: https://build.fhir.org/ig/HL7/sdc/Questionnaire-extract-complex-template.json.html, but esentially, in this extension located on the _reference field you are instructing with fhirPath the $extract service to create the reference as a concatenation of strings ('QuestionnaireResponse/' + %resource.id)

This examples works and can be ingested on a HAPI FHIR (and I know that also works on other cloud vendors as asked on community), but when ingested on a GCP FHIR store the "_reference" field gets deleted, without a warning. 

We have tested extensions on other primitive datatypes like on 20 differents resources types and this is the only field that gets this behaviour. 

Right now, we make a workaround like this:

"recorder": {
"extension": [
{
"valueString": "%resource.author"
}
]
},

The extension extractValue is the one that indicates to the $extract service that needs to replace the value with the fhirPath expression written on the valueString field. In this case we are replacing the recorder with the author reference of the QuestionnaireResponse (which already has been pre-populated with some basic info like author, authored, id, etc). In this case, it will return an object with a reference field. 

Right now as Questionnaires are only being used on GCP, they will work, but if we receive Questionnaires designed and stored from others non-GPC FHIR store sources, they will probably include the _reference field and wont work, as the instruction for the extraction on that field would be deleted.

Hope this could be taking into consideration for future updates. 

I know SDC could be tricky to understand, I tried to be as didactic as possible. 

Thanks in advance for your time, 
Maico. 

Milena Bukal

unread,
Jul 24, 2025, 11:07:54 AMJul 24
to GCP Healthcare Discuss
Hi Maico,

I'm not familiar with SDC & any context around that, but I'll attempt to help with your question regarding the GCP FHIR store.

First, to clarify re: "but when ingested on a GCP FHIR store the "_reference" field gets deleted, without a warning."

That's not what happens to me when I try to create a Questionnaire with a "_reference" field like your example, I get the error: 
{
  "issue": [
    {
      "code": "structure",
      "details": {
        "text": "unparseable_resource"
      },
      "diagnostics": "unknown field: \"_reference\"",
      "expression": [
        "Questionnaire.derivedFrom[0]"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

You're correct about it being valid FHIR able to replace a "field" with "_field" and an id/extension (for example, a data absent reason).

...But if we look at the R4 definition of Questionnaire: https://hl7.org/fhir/R4/questionnaire.html and click on the type of derivedFrom: https://hl7.org/fhir/R4/datatypes.html#canonical there is no "reference" subfield of a canonical, it's just a json string.

canonical.png

So you can't do "_reference"... because a field named "reference" would also be invalid, according to the spec.

I don't know why other APIs would support this functionality?

Thanks,
Milena

Maico Bernal

unread,
Jul 24, 2025, 1:27:33 PMJul 24
to GCP Healthcare Discuss
Hi Milena, 

Thank you for your time!

Here below I provide you a full example that can reproduce this behaviour.

The resource will be ingested without any error or warning on the GCP FHIR Store R4, but it will automatically remove all the "_reference" fields. 

This is only happening on the "_reference" field, but not in the others primitive ones (I only put status, code, system and display for example purposes but we tested it on plenty of fields). 

I tested this example making a POST on the following public servers, and the _reference field is persisted. 


Here is the example:

{
"resourceType": "Questionnaire",
"id": "Test",
"version": "0.1",
"name": "Test",
"title": "Test",
"status": "active",
"date": "2025-07-24",
"contained": [
{
"resourceType": "Observation",
"id": "ObsTemplate",
"subject": {
"reference": "#PatientTemplate",
"valueString": "%resource.subject.reference"
}
]
}
},
"performer": [
{
"reference": "#PractitionerTemplate",
"valueString": "%resource.author.reference"
}
]
}
}
],
"encounter": {
"reference": "#EncounterTemplate",
"valueString": "dummy-fhir-path-for-example"
}
]
}
},
"hasMember": [
{
"reference": "#ObservationDummy",
"valueString": "dummy-fhir-path-for-example"
}
]
}
}
],
"status": "final",
"_status": {
"valueString": "%resource.status"
}
]
},
"code": {
"coding": [
{
"code": "75500-9",
"_code": {
"valueString": "%resource.code"
}
]
},
"system": "http://loinc.org",
"_system": {
"valueString": "%resource.system"
}
]
},
"display": "Triage Note",
"_display": {
"valueString": "%resource.display"
}
]
}
}
]
},
"effectiveDateTime": "2025-04-28T10:00:00-05:00",
"_effectiveDateTime": {
"valueString": "%resource.authored"
}
]
},
"valueBoolean": true,
"_valueBoolean": {
"valueString": "item.where(linkId = 'disnea').answer.value"
}
]
}
},
{
"resourceType": "Patient",
"id": "PatientTemplate",
"active": true,
"maritalStatus": {
"coding": [
{
"code": "S",
"display": "Never Married",
}
]
}
},
{
"resourceType": "Practitioner",
"id": "PractitionerTemplate",
"active": false
},
{
"resourceType": "Encounter",
"id": "EncounterTemplate",
"status": "planned",
"class": {
"code": "VR",
"display": "Virtual",
}
},
{
"resourceType": "Observation",
"id": "ObservationDummy",
"status": "preliminary",
"code": {
"coding": [
{
"code": "dummy",
"display": "Dummy Code",
}
]
}
}
],
"item": [
{
"extension": [
{
"extension": [
{
"url": "template",
"valueReference": {
"reference": "#ObsTemplate"
}
}
],
}
],
"initial": [
{
"valueBoolean": false
}
],
"type": "boolean",
"linkId": "disnea",
"text": "¿Sintió falta de aire?",
"required": true,
"repeats": false,
"readOnly": false
}
]
}

Milena Bukal

unread,
Jul 24, 2025, 2:44:22 PMJul 24
to Maico Bernal, GCP Healthcare Discuss
Hi Maico,

Thank you for providing a full sample resource, I was able to reproduce your issue. I also tried taking the observation out and POSTing it alone, and it also dropped the "_reference" field. You also can't create a resource with a "_reference" field only.

A strange workaround: if you use a fully qualified url ("projects/p/locations/l/datasets/d/fhirStores/f/fhir/Patient/id"), the "_reference" field is not dropped and correctly populated. A contained ("#Patient1") or local reference ("Patient/1") triggers the bug.

Surprisingly, this has never been reported before. It's a problem with how we parse/store references internally, so it only happens to the reference field. I wouldn't expect to see this with any other field.

I'll file a bug for this, not sure how quick it will be. If it counts as a breaking change, it would require more care.

Thanks,
Milena





--
You received this message because you are subscribed to a topic in the Google Groups "GCP Healthcare Discuss" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/gcp-healthcare-discuss/eodXN1TNlMY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to gcp-healthcare-di...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/gcp-healthcare-discuss/42dd4012-507f-4b86-be2d-ccf73f509babn%40googlegroups.com.

Maico Bernal

unread,
Jul 24, 2025, 3:34:15 PMJul 24
to GCP Healthcare Discuss

Glad to help! I’ll stay subscribed to this post in case there is any news.

Milena Bukal

unread,
Aug 18, 2025, 2:29:22 PMAug 18
to Maico Bernal, GCP Healthcare Discuss
Hi Maico,

This fix should be rolled out in all regions now.

Thanks,
Milena

To view this discussion visit https://groups.google.com/d/msgid/gcp-healthcare-discuss/20f94b39-41d0-4c16-a753-661ce75ae5dcn%40googlegroups.com.

Maico Bernal

unread,
Sep 17, 2025, 10:13:09 AMSep 17
to GCP Healthcare Discuss

Hi Milena,

Sorry for the delayed reply.

I retested the same example in us-central1 and us-east1, against both FHIR R4 and R5 stores, and the _reference field still disappears. It only persists when using a fully qualified URL.

In this Structure Data Capture use case, _reference would typically be populated with a contained reference.

I hope this helps toward a fix. Thanks in advance!

Best,
Maico

Truc Le

unread,
Sep 24, 2025, 4:51:12 PMSep 24
to GCP Healthcare Discuss
Hi Maico,

Thank you for the follow-up. Our investigation confirmed that the previous fix only addressed the parser and missed the rendering path. We apologize for this oversight.

We have now performed thorough end-to-end testing and verified the fix is working correctly. We anticipate this updated fix will be deployed to production within the next 2-3 weeks.

Thanks,
Truc
Reply all
Reply to author
Forward
0 new messages