Merge pull request #90 from Ardenexal/feat/roundtrip-doc-fix

docs: remove fixed single-element XML round-trip limitation; add regression guard

Author: Ardenexal

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- [Docs] Removed the stale "single-element repeating fields" XML limitation note from the serialization guide; single-value repeating fields (e.g. a `HumanName` with one `given`) already round-trip correctly through XML, and a regression test now guards this
+
 ## [0.4.0] - 2026-06-12
 
 ### Added

docs/serialization/xml.md

@@ -35,13 +35,6 @@ definitions are never processed. Attribute values are also preserved as strings
 their precision on round-trip rather than being cast to float/int.
 {% endhint %}
 
-{% hint style="info" %}
-**Known limitation (XML, single-element repeating fields):** a repeating element that contains
-exactly one value (for example a `HumanName` whose `given` is `['John']`) currently fails to
-deserialize back from XML, because XML collapses the lone element to a scalar. Two-or-more values
-(`given: ['John', 'James']`) round-trip correctly, as does omitting the field. JSON is unaffected.
-{% endhint %}
-
 ## Error handling
 
 Like JSON, all failures are wrapped in `FHIRSerializationException`:

src/Component/Serialization/tests/Integration/ArrayOfComplexRoundTripTest.php

@@ -56,4 +56,42 @@ public function testArrayOfComplexXmlRoundTripPreservesAllItems(): void
         self::assertIsArray($names);
         self::assertCount(2, $names, 'both HumanName entries must survive a JSON→object→XML→object trip');
     }
+
+    /**
+     * Regression guard: a repeating field with exactly ONE value must survive an XML round-trip.
+     * XmlEncoder collapses a lone element to a scalar/assoc array rather than a list, so single-element
+     * arrays must be re-wrapped on deserialization. Covers both a repeating primitive (`given`) and a
+     * repeating complex type (`identifier`). The 2+-element case is covered above; this guards the tail.
+     */
+    public function testSingleElementRepeatingFieldsXmlRoundTrip(): void
+    {
+        $service = FHIRSerializationService::createDefault();
+
+        $json = <<<'JSON'
+{
+  "resourceType": "Patient",
+  "id": "single",
+  "identifier": [ { "system": "urn:x", "value": "123" } ],
+  "name": [ { "family": "Smith", "given": ["John"] } ]
+}
+JSON;
+
+        $patient = $service->deserialize($json);
+        $xml     = $service->serializeToXml($patient);
+        $back    = $service->deserialize($xml);
+
+        $refl = new \ReflectionClass($back);
+
+        $names = $refl->getProperty('name')->getValue($back);
+        self::assertIsArray($names);
+        self::assertCount(1, $names, 'single HumanName must survive an XML round-trip');
+
+        $given = (new \ReflectionClass($names[0]))->getProperty('given')->getValue($names[0]);
+        self::assertIsArray($given, 'single-element repeating primitive `given` must stay an array');
+        self::assertCount(1, $given, 'lone `given` value must not be lost when XML collapses it');
+
+        $identifiers = $refl->getProperty('identifier')->getValue($back);
+        self::assertIsArray($identifiers);
+        self::assertCount(1, $identifiers, 'single complex `identifier` must survive an XML round-trip');
+    }
 }