---
title: Serialize / deserialize an object
summary: Round-trip an object graph to/from JSON or XML, files or strings.
status: draft
owner: saif-docgen
last_reviewed: 2026-09-15
library: SAIF.Framework.Common
reference_type: package
operation_id: OP-026
trigger: Caller persists or rehydrates an object graph
---

# Serialize / deserialize an object

Round-trip an object graph to/from JSON or XML, files or strings, triggered when caller persists or rehydrates an object graph.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-026 |
| **Trigger** | Caller persists or rehydrates an object graph |
| **Inputs** | A file path, a serialized string, or the instance to serialize |
| **Outputs** | `T`, `string`, or a written file |
| **Primary components** | ``SAIF.Common.Serializer` — `LoadFromJson<T>`, `SerializeToJson<T>`, `DeserializeFromJson<T>`, `LoadFromXml<T>`, `SaveToJson<T>`, `SaveToXml<T>`; plus `GenericExtensions.ToJsonString<T>` / `ToXmlString<T>` and `DotNet40Extensions.LoadFromJson<T>` / `DeserializeFromJson<T>`` |
| **Entry point** | `Common/SAIF.Common/Classes/Serializer.cs` |

## Steps

1. JSON paths construct a `System.Web.Script.Serialization.JavaScriptSerializer`; XML paths construct a `System.Xml.Serialization.XmlSerializer(typeof(T))`. ([BR-058](<../business-rules.md#br-058-json-serialization-uses-javascriptserializer-(system.web.extensions)-and-xml-serialization-uses-xmlserializer%3B-serializable-targets-must-be-reference-types-(where-t-%3A-class)-except-for-savetojson%3Ct%3E%2C-which-is-unconstrained>))
2. `LoadFromJson<T>(fileName)` opens a `StreamReader` in a `using`, reads the whole file, and deserializes to `T`. `LoadFromXml<T>(fileName)` opens a `StreamReader` and deserializes with `as T`, returning `null` on a type mismatch rather than throwing. ([BR-059](../business-rules.md#br-059-xml-deserialization-that-produces-an-incompatible-type-yields-null-rather-than-throwing%2C-because-the-result-is-cast-with-as-t))
3. `SaveToJson<T>` / `SaveToXml<T>` open a `StreamWriter` in a `using`, write the serialized form, and call `Flush()` explicitly. ([BR-060](../business-rules.md#br-060-serialized-output-written-to-a-file-is-explicitly-flushed-before-the-writer-is-disposed))
4. `SerializeToJson<T>` / `DeserializeFromJson<T>` operate on strings with no file I/O; `GenericExtensions.ToXmlString<T>` serializes through an in-memory `StringWriter`.
5. The generic constraint `where T : class` applies to every method except `SaveToJson<T>`, which is unconstrained. ([BR-058](<../business-rules.md#br-058-json-serialization-uses-javascriptserializer-(system.web.extensions)-and-xml-serialization-uses-xmlserializer%3B-serializable-targets-must-be-reference-types-(where-t-%3A-class)-except-for-savetojson%3Ct%3E%2C-which-is-unconstrained>))

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start(["Caller persists or rehydrates<br>an object graph"]) --> Format{"JSON or XML path?"}
	Format -->|JSON| JsonSer["Construct<br>JavaScriptSerializer"]
	Format -->|XML| XmlSer["Construct<br>XmlSerializer(typeof(T))"]
	JsonSer --> Load
	XmlSer --> Load["LoadFromJson/LoadFromXml:<br>read file, deserialize to T"]
	Load --> LoadCheck{"XML result type<br>mismatch (as T)?"}
	LoadCheck -->|Yes| NullReturn(["Return null"])
	LoadCheck -->|No| Save
	NullReturn --> Save["SaveToJson/SaveToXml: write<br>serialized form, Flush explicitly"]
	Save --> StringOps["SerializeToJson/DeserializeFromJson:<br>operate on strings, no file I/O"]
	StringOps --> Constraint["Generic constraint T : class<br>applies except SaveToJson<T>"]
	Constraint --> End(["Object graph, string,<br>or written file returned"])
```

## Failure and edge-case behavior

- No method catches exceptions. Missing files raise `FileNotFoundException`; malformed payloads raise serializer exceptions; both propagate to the caller.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `Common/SAIF.Common/Classes/Serializer.cs`
- `Common/SAIF.Common/Extensions/GenericExtensions.cs`
- `Common/SAIF.Common/Extensions/DotNet40Extensions.cs`