XML Marshaling

The gofhir/models library serializes FHIR XML through dedicated helper functions defined in xml_helpers.go. Every resource struct implements MarshalXML and UnmarshalXML from Go’s encoding/xml package, and top-level functions handle the XML declaration, FHIR namespace, and self-closing element conventions.

XML Helper Functions

The library exposes three primary functions for XML serialization:

MarshalResourceXML

Serializes a FHIR resource to XML bytes with the standard XML declaration header and the FHIR namespace.

package main

import (
    "fmt"
    "log"

    "github.com/gofhir/models/r4/v2"
)

func ptrTo[T any](v T) *T {
    return &v
}

func main() {
    patient := &r4.Patient{
        Id:           ptrTo("xml-example"),
        Active:       ptrTo(true),
        Gender:       ptrTo(r4.AdministrativeGenderMale),
        BirthDate:    ptrTo("1990-06-15"),
    }

    data, err := r4.MarshalResourceXML(patient)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(data))
}

MarshalResourceXML writes the declaration, then the whole resource on one line:

<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir"><id value="xml-example"/><active value="true"/><gender value="male"/><birthDate value="1990-06-15"/></Patient>

For the indented form, use MarshalResourceXMLIndent — see the next section.

MarshalResourceXMLIndent

Produces the same output as MarshalResourceXML but with custom indentation for human-readable output:

data, err := r4.MarshalResourceXMLIndent(patient, "", "  ")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(data))

The prefix and indent parameters work the same way as in xml.Encoder.Indent().

UnmarshalResourceXML

Deserializes FHIR XML bytes to the correct resource type. It reads the root element name to determine the resource type, creates the appropriate struct via the resource registry, and calls UnmarshalXML:

xmlData := []byte(`<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
  <id value="from-xml"/>
  <active value="true"/>
  <name>
    <use value="official"/>
    <family value="Smith"/>
    <given value="John"/>
  </name>
  <gender value="male"/>
</Patient>`)

resource, err := r4.UnmarshalResourceXML(xmlData)
if err != nil {
    log.Fatal(err)
}

patient := resource.(*r4.Patient)
fmt.Println(*patient.Id)             // "from-xml"
fmt.Println(*patient.Active)         // true
fmt.Println(*patient.Name[0].Given[0]) // "John"

FHIR Namespace Handling

The FHIR specification requires that XML representations use the namespace http://hl7.org/fhir. The MarshalResourceXML and MarshalResourceXMLIndent functions automatically add this namespace to the root element:

<Patient xmlns="http://hl7.org/fhir">

During deserialization, UnmarshalResourceXML determines the resource type from the local name of the root element, regardless of namespace prefix.

Primitive Element Encoding

FHIR XML encodes primitive values (strings, booleans, integers, decimals, dates) as XML attributes rather than as element content. The value is placed in a value attribute on the element:

<!-- String primitive -->
<id value="example-123"/>

<!-- Boolean primitive -->
<active value="true"/>

<!-- Code primitive -->
<gender value="male"/>

<!-- Date primitive -->
<birthDate value="1990-06-15"/>

<!-- Decimal primitive -->
<value value="72.5"/>

This differs from typical XML where values are element text content. The library handles this automatically through internal helper functions like xmlEncodePrimitiveString, xmlEncodePrimitiveBool, xmlEncodePrimitiveInt, xmlEncodePrimitiveDecimal, and xmlEncodePrimitiveCode.

Self-Closing Elements

The FHIR specification uses self-closing elements for primitives without children: <id value="123"/> rather than <id value="123"></id>. The library post-processes the XML output to collapse empty elements into self-closing form using the collapseEmptyElements function.

Complex Type Encoding

Complex types (such as HumanName, CodeableConcept, Reference) are encoded as nested XML elements with their child elements:

<Patient xmlns="http://hl7.org/fhir">
  <id value="complex-example"/>
  <name>
    <use value="official"/>
    <family value="Johnson"/>
    <given value="Alice"/>
    <given value="Marie"/>
  </name>
  <telecom>
    <system value="phone"/>
    <value value="+1-555-0100"/>
    <use value="home"/>
  </telecom>
</Patient>

Note that repeating elements (like multiple given names) each appear as separate XML elements with the same tag name, following the FHIR XML convention.

Contained Resources in XML

Contained resources are wrapped in a <contained> element, with the resource type as a nested element:

<Patient xmlns="http://hl7.org/fhir">
  <id value="with-contained"/>
  <contained>
    <Organization>
      <id value="org-1"/>
      <name value="Example Hospital"/>
    </Organization>
  </contained>
  <managingOrganization>
    <reference value="#org-1"/>
  </managingOrganization>
</Patient>

The library handles this through the xmlEncodeContainedResource and xmlDecodeContainedResource helper functions.

XHTML Narrative in XML

The Narrative.Div field contains XHTML that the specification requires to be preserved verbatim. It is written as a real <div>, with its inner markup carried through unchanged:

<text>
  <status value="generated"/>
  <div xmlns="http://www.w3.org/1999/xhtml"><p>John Smith</p></div>
</text>

The XHTML namespace is supplied if your markup omits it, since a div without it is not conformant. Everything inside the div is passed through byte for byte — including empty elements such as <a href="q"></a>, which the self-closing rewrite applied to the rest of the document deliberately leaves alone.

patient.Text = &r4.Narrative{Div: r4.Ptr(`<div><p>unclosed</div>`)}
_, err := r4.MarshalResourceXML(patient)
// err: div is not well-formed XML: XML syntax error on line 1: element <p> closed by </div>

patient := &r4.Patient{
    Id:           ptrTo("with-narrative"),
    Text: &r4.Narrative{
        Status: ptrTo(r4.NarrativeStatusGenerated),
        Div:    ptrTo(`<div xmlns="http://www.w3.org/1999/xhtml"><p>John Smith</p></div>`),
    },
}

data, _ := r4.MarshalResourceXMLIndent(patient, "", "  ")
fmt.Println(string(data))

Round-Trip XML Fidelity

Measured over the published example corpora:

The conformance suite in conformance/ tracks this file by file, so these numbers are measured rather than estimated.

A resource carrying a narrative round-trips with its data intact, narrative included.

The decoded struct is equal to the original: resourceType is a zero-size marker carried by the Go type rather than a string the decoder has to fill in, so there is no field left inconsistent. Read it with GetResourceType():

plain := &r4.Patient{
    Id:           ptrTo("round-trip"),
    Active:       ptrTo(true),
    Gender:       ptrTo(r4.AdministrativeGenderMale),
}

xmlBytes, err := r4.MarshalResourceXML(plain)
if err != nil {
    log.Fatal(err)
}

resource, err := r4.UnmarshalResourceXML(xmlBytes)
if err != nil {
    log.Fatal(err)
}

decoded := resource.(*r4.Patient)
fmt.Println(*decoded.Id)     // "round-trip"
fmt.Println(*decoded.Active) // true