From 7a2b4d9ddf8086ab80fa015940213485c67b9e57 Mon Sep 17 00:00:00 2001
From: Sebastian Husch Lee <sjrl423@gmail.com>
Date: Tue, 7 Jul 2026 10:03:22 +0200
Subject: [PATCH] Add upgrade notice and migration entry

---
 MIGRATION.md                                  | 20 +++++++++++++++++++
 ...-dataclasses-deseria-0bb839b5edd3fca6.yaml | 12 ++++++-----
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/MIGRATION.md b/MIGRATION.md
index bd052deb14..15d136faae 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -73,6 +73,26 @@ from haystack.dataclasses import Document
 doc = Document(content="col\n1\n2\n3")
 ```
 
+### `GeneratedAnswer` and `ExtractedAnswer` serialization format
+
+**What changed:** `GeneratedAnswer.to_dict()` and `ExtractedAnswer.to_dict()` now return a flat dictionary of the object's fields instead of wrapping them in a `{"type": ..., "init_parameters": {...}}` envelope. `from_dict()` still accepts the old wrapped format, so existing serialized artifacts keep loading.
+
+**Why:** Aligns these dataclasses with how every other Haystack dataclass (`Document`, `ChatMessage`, etc.) serializes, and removes redundant type metadata from pipeline snapshots and `State` objects.
+
+**How to migrate:** Update any code that reads the serialized output to access fields at the top level instead of under `init_parameters`. See [#11805](https://github.com/deepset-ai/haystack/pull/11805).
+
+Before (v2.x):
+```python
+serialized = generated_answer.to_dict()
+data = serialized["init_parameters"]["data"]
+```
+
+After (v3.0):
+```python
+serialized = generated_answer.to_dict()
+data = serialized["data"]
+```
+
 ### Components Moved to External Packages
 
 **What changed:** Some components have been moved out of Haystack into dedicated integration packages,
diff --git a/releasenotes/notes/fix-dataclasses-deseria-0bb839b5edd3fca6.yaml b/releasenotes/notes/fix-dataclasses-deseria-0bb839b5edd3fca6.yaml
index c13d586fa5..567cca034d 100644
--- a/releasenotes/notes/fix-dataclasses-deseria-0bb839b5edd3fca6.yaml
+++ b/releasenotes/notes/fix-dataclasses-deseria-0bb839b5edd3fca6.yaml
@@ -1,8 +1,10 @@
 ---
-fixes:
+upgrade:
   - |
     ``GeneratedAnswer`` and ``ExtractedAnswer`` now serialize to the same flat format as
-    all other Haystack dataclasses (``Document``, ``ChatMessage``, etc.), removing an
-    inconsistency that caused redundant type metadata to be embedded in pipeline
-    snapshots and ``State`` objects. Deserialization is backward compatible: ``from_dict()``
-    still accepts the old ``{"type": "...", "init_parameters": {...}}`` format.
+    all other Haystack dataclasses (``Document``, ``ChatMessage``, etc.). This is a breaking
+    change: ``to_dict()`` no longer wraps the fields in the ``{"type": "...", "init_parameters":
+    {...}}`` envelope and instead returns the fields at the top level. Any code or stored
+    artifact that reads the serialized output and expects the ``type``/``init_parameters``
+    keys must be updated to read the fields directly. ``from_dict()`` remains backward
+    compatible and still accepts the old wrapped format.