> For the complete documentation index, see [llms.txt](https://php-fhir-tools.ardenexal.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://php-fhir-tools.ardenexal.net/serialization/overview.md).

# Overview

Convert FHIR model objects to and from JSON and XML.

The Serialization component converts FHIR model objects to and from JSON and XML. It works standalone (no framework) or wired through the [Symfony Bundle](/symfony-bundle/configuration.md). It is built on top of the Symfony Serializer component, with FHIR-aware normalizers handling resources, complex types, backbone elements, and primitives.

The public surface is small and stable:

* `FHIRSerializationService` — the high-level entry point (`serializeToJson`, `serializeToXml`, `deserializeFromJson`, `deserializeFromXml`, `deserialize`).
* `FHIRSerializationContext` — an immutable value object describing options. See [Context & Options](/serialization/context.md).
* `Validator\FHIRValidator` — business-rule validation. See [Validation](/validation/overview.md).

Everything else (the per-format normalizers, the type resolver, the metadata extractor) is an internal detail that the service or the Symfony container wires for you. You normally never instantiate those directly.

## Installation

{% tabs %}
{% tab title="Standalone" %}

```bash
composer require ardenexal/fhir-serialization ardenexal/fhir-models
```

`ardenexal/fhir-models` provides the generated R4/R4B/R5 model classes the serializer reads and writes. Without it there is nothing to serialize.
{% endtab %}

{% tab title="With FHIRBundle" %}
The Serialization component is pulled in automatically with the bundle:

```bash
composer require ardenexal/fhir-bundle
```

{% endtab %}
{% endtabs %}

## Creating the service

{% tabs %}
{% tab title="Standalone" %}
Outside a Symfony container, build a fully-wired service with the static factory. It defaults to FHIR R4; pass a different `FhirVersion` for R4B or R5.

```php
<?php

use Ardenexal\FHIRTools\Component\Serialization\FHIRSerializationService;
use Ardenexal\FHIRTools\Component\Serialization\FhirVersion;

$serializer = FHIRSerializationService::createDefault();                 // R4
// $serializer = FHIRSerializationService::createDefault(FhirVersion::R5);
```

{% hint style="warning" %}
**Do not** call `new FHIRSerializationService()` directly — the constructor requires a fully assembled `Serializer`, context factory, and debug-info collector. `createDefault()` (and `createWithIG()`, see [IG-Aware](/serialization/ig-aware.md)) perform that wiring for you.
{% endhint %}
{% endtab %}

{% tab title="Symfony DI" %}
When the FHIRBundle is installed, inject the service by type — the `fhir.serialization_service` alias points at it:

```php
<?php

namespace App\Service;

use Ardenexal\FHIRTools\Component\Serialization\FHIRSerializationService;
use Ardenexal\FHIRTools\Component\Models\R4B\Resource\PatientResource;

final class PatientService
{
    public function __construct(
        private readonly FHIRSerializationService $serializer,
    ) {}

    public function toJson(PatientResource $patient): string
    {
        return $this->serializer->serializeToJson($patient);
    }
}
```

{% endtab %}
{% endtabs %}

## Next

* [JSON Serialization](/serialization/json.md)
* [XML Serialization](/serialization/xml.md)
* [Context & Options](/serialization/context.md)
* [IG-Aware Serialization](/serialization/ig-aware.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://php-fhir-tools.ardenexal.net/serialization/overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.