Deprecated usage of type field name (#993)

This support was added in #376 but only for non polymorphic fields.

However as per specification [0] `type` must not be a field name and
therefore must be forbidden in DJA as well.

Some dependents might depend on being allowed to have a field
name `type` so deprecating it now and remove it in next major version.

[0] https://jsonapi.org/format/#document-resource-object-fields

Author: sliverc

CHANGELOG.md

@@ -24,6 +24,7 @@ any parts of the framework not mentioned in the documentation should generally b
 ### Deprecated
 
 * Deprecated `get_included_serializers(serializer)` function under `rest_framework_json_api.utils`. Use `serializer.included_serializers` instead.
+* Deprecated support for field name `type` as it may not be used according to the [JSON:API spec](https://jsonapi.org/format/#document-resource-object-fields).
 
 ## [4.2.1] - 2021-07-06
 

example/tests/test_model_viewsets.py

@@ -223,17 +223,21 @@ def test_patch_allow_field_type(author, author_type_factory, client):
     """
     Verify that type field may be updated.
     """
-    author_type = author_type_factory()
-    url = reverse("author-detail", args=[author.id])
-
-    data = {
-        "data": {
-            "id": author.id,
-            "type": "authors",
-            "relationships": {"data": {"id": author_type.id, "type": "author-type"}},
+    # TODO remove in next major version 5.0.0 see serializers.ReservedFieldNamesMixin
+    with pytest.deprecated_call():
+        author_type = author_type_factory()
+        url = reverse("author-detail", args=[author.id])
+
+        data = {
+            "data": {
+                "id": author.id,
+                "type": "authors",
+                "relationships": {
+                    "data": {"id": author_type.id, "type": "author-type"}
+                },
+            }
         }
-    }
 
-    response = client.patch(url, data=data)
+        response = client.patch(url, data=data)
 
-    assert response.status_code == 200
+        assert response.status_code == 200

rest_framework_json_api/parsers.py

@@ -162,7 +162,7 @@ def parse(self, stream, media_type=None, parser_context=None):
         # Construct the return data
         serializer_class = getattr(view, "serializer_class", None)
         parsed_data = {"id": data.get("id")} if "id" in data else {}
-        # `type` field needs to be allowed in none polymorphic serializers
+        # TODO remove in next major version 5.0.0 see serializers.ReservedFieldNamesMixin
         if serializer_class is not None:
             if issubclass(serializer_class, serializers.PolymorphicModelSerializer):
                 parsed_data["type"] = data.get("type")

rest_framework_json_api/serializers.py

@@ -1,3 +1,4 @@
+import warnings
 from collections import OrderedDict
 from collections.abc import Mapping
 
@@ -171,6 +172,18 @@ def get_fields(self):
                 f"{', '.join(sorted(found_reserved_field_names))}"
             )
 
+        if "type" in fields:
+            # see https://jsonapi.org/format/#document-resource-object-fields
+            warnings.warn(
+                DeprecationWarning(
+                    f"Field name 'type'  found in serializer class "
+                    f"{self.__class__.__module__}.{self.__class__.__qualname__} "
+                    f"which is not allowed according to the JSON:API spec and "
+                    f"won't be supported anymore in the next major DJA release. "
+                    f"Rename 'type' field to something else. "
+                )
+            )
+
         return fields
 
 

setup.cfg

@@ -60,6 +60,10 @@ filterwarnings =
     error::PendingDeprecationWarning
     # Django Debug Toolbar currently (2021-04-07) specifies default_app_config which is deprecated in Django 3.2:
     ignore:'debug_toolbar' defines default_app_config = 'debug_toolbar.apps.DebugToolbarConfig'. Django now detects this configuration automatically. You can remove default_app_config.:PendingDeprecationWarning
+    # TODO remove in next major version of DJA 5.0.0
+    # this deprecation warning filter needs to be added as AuthorSerializer is used in
+    # too many tests which introduced the type field name in tests
+    ignore:Field name 'type'
 testpaths =
     example
     tests

tests/test_serializers.py

@@ -50,3 +50,12 @@ class ReservedFieldNamesSerializer(serializers.Serializer):
         "ReservedFieldNamesSerializer uses following reserved field name(s) which is "
         "not allowed: meta, results"
     )
+
+
+def test_serializer_fields_deprecated_field_name_type():
+    with pytest.deprecated_call():
+
+        class TypeFieldNameSerializer(serializers.Serializer):
+            type = serializers.CharField()
+
+        TypeFieldNameSerializer().fields