From 0dc7f54aba348f75eb3f77741658630b296413f0 Mon Sep 17 00:00:00 2001 From: Petros Moisiadis Date: Thu, 30 Jul 2026 17:07:32 +0300 Subject: [PATCH] Update fields.md explaining how the `source` argument affects structure of `.validated_data` One may think that, after successful validation, a key in the `.validated_data` attribute of a serializer always equals the corresponding field name in the serializer. However, that may not be the case if the field has been defined in the serializer with a dotted path value in its `source` argument. In that case, what is actually included in `.validated_data` is a nested dictionary that is derived by expanding the dotted path of the `source` argument. This addition in the documentation clarifies the situation and explains why DRF follows that behavior. --- docs/api-guide/fields.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 8f13d90ece..e0e4cd0732 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -84,6 +84,22 @@ When serializing fields with dotted notation, it may be necessary to provide a ` This case would require user object to be fetched from database when it is not prefetched. If that is not wanted, be sure to be using `prefetch_related` and `select_related` methods appropriately. For more information about the methods refer to [django documentation][django-docs-select-related]. +Also note that, when the dotted notation is used, after validation of the serializer occurs, the dictionary value of the `.validated_data` attribute will _not_ include a flat `"": ` item. Instead, it will include a nested dictionary derived by expanding the dotted path value of the `source` argument. So, for the previous serializer example, `.validated_data` would be: +``` +{ + "user": { + "email": ... + } +} +``` +instead of: +``` +{ + "email": ... +} +``` +This works this way because, in DRF's philosophy, the `.data` attribute represents the external API representation (where key names equal field names), while the `.validated_data` attribute represents the internal object structure (where key names equal source paths). + The value `source='*'` has a special meaning, and is used to indicate that the entire object should be passed through to the field. This can be useful for creating nested representations, or for fields which require access to the complete object in order to determine the output representation. Defaults to the name of the field.