better wording & description

Author: vdusek

docs/04_upgrading/upgrading_to_v4.md

@@ -218,7 +218,7 @@ Pickle could store arbitrary Python objects. JSON cannot, so the values in a req
 
 - A `tuple` comes back as a `list`.
 - Non-string `dict` keys come back as strings, so `{1: 'a'}` becomes `{'1': 'a'}`.
-- A value JSON cannot represent (`datetime`, `set`, `Decimal`, a custom object) is no longer stored silently. The request is skipped and the failure is logged. Pydantic models are still supported and are dumped with `model_dump(mode='json')`, so model fields JSON cannot natively represent (such as `datetime`) are stored in their JSON form.
+- Non-JSON-serializable values, such as `datetime`, `set`, `Decimal`, or custom objects, are skipped and logged. Pydantic models are supported via `model_dump(mode='json')`, which converts non-JSON-native fields into JSON-compatible values, such as ISO-8601 strings for `datetime` fields.
 
 Convert such values to a JSON-friendly form before yielding the request:
 
@@ -230,4 +230,4 @@ yield scrapy.Request(url, meta={'since': datetime(2024, 1, 1)})
 
 # After (v4): store a JSON-serializable value.
 yield scrapy.Request(url, meta={'since': datetime(2024, 1, 1).isoformat()})
-```
+```Pickle

src/apify/scrapy/_serialization.py

@@ -1,21 +1,23 @@
 """JSON serialization of Scrapy requests and cached responses for storage on the Apify platform.
 
-Scrapy requests and cached responses are stored in the Apify request queue and key-value store which hold JSON,
-so they are serialized as JSON here rather than pickled.
-
-Only `body` (`bytes`) and `headers` (`{bytes: [bytes]}`) are not natively JSON-serializable; both sit at fixed keys
-and are base64-encoded in place. A `str` `body` is encoded as its UTF-8 bytes and comes back as `bytes`, matching
-Scrapy, which always stores `body` as `bytes`. Pydantic models such as Crawlee's `UserData` are dumped via
-`model_dump(mode='json')`, so model fields JSON cannot natively represent (e.g. `datetime`) are stored in their
-JSON form. Everything else, notably `meta` and `cb_kwargs`, must already be JSON-serializable, otherwise
-serialization fails with a clear error naming the offending value. No in-band sentinel is used, so no user value
-can collide with the encoding.
-
-Known limitations of the pickle -> JSON switch (a documented breaking change): JSON has fewer types than pickle,
-so values in `meta`/`cb_kwargs` are subject to JSON's coercions. A `tuple` round-trips as a `list` and non-string
-`dict` keys round-trip as strings (e.g. `{1: 'a'}` becomes `{'1': 'a'}`). Values JSON cannot represent at all
-(`datetime`, `set`, `Decimal`, arbitrary objects, ...) are not coerced silently: serialization raises and the request
-is skipped loudly rather than stored in a corrupted form.
+Scrapy requests and cached responses are stored in the Apify request queue and key-value store, which hold JSON.
+They are therefore serialized as JSON here.
+
+Only `body` (`bytes`) and `headers` (`{bytes: [bytes]}`) are not natively JSON-serializable. Both live at fixed keys
+and are base64-encoded in place. A `str` `body` is encoded as UTF-8 bytes and deserialized as `bytes`, matching
+Scrapy, which always stores `body` as `bytes`.
+
+Pydantic models, such as Crawlee's `UserData`, are dumped with `model_dump(mode='json')`, which converts
+non-JSON-native fields into JSON-compatible values. For example, `datetime` fields are stored as ISO-8601 strings.
+
+All other values, notably `meta` and `cb_kwargs`, must already be JSON-serializable. Non-JSON-serializable values,
+such as `datetime`, `set`, `Decimal`, or arbitrary objects, fail serialization with a clear error naming the
+offending value. The request is skipped rather than stored in a corrupted form.
+
+No in-band sentinel is used, so user values cannot collide with the encoding.
+
+Known JSON limitations: values in `meta` and `cb_kwargs` are subject to JSON coercions. A `tuple` round-trips as
+a `list`, and non-string `dict` keys round-trip as strings; for example, `{1: 'a'}` becomes `{'1': 'a'}`.
 """
 
 from __future__ import annotations