feat(marshmallow): support Tuple field in OpenAPI 3.1+ (closes #399)

Author: ansh-rohilla

src/apispec/core.py

@@ -350,9 +350,18 @@ def _resolve_refs_in_schema(self, schema: dict) -> None:
                     "schema", schema["properties"][key]
                 )
                 self._resolve_refs_in_schema(schema["properties"][key])
-        if "items" in schema:
+        if "items" in schema and isinstance(schema["items"], (dict, str)):
             schema["items"] = self.get_ref("schema", schema["items"])
-            self._resolve_refs_in_schema(schema["items"])
+            if isinstance(schema["items"], dict):
+                self._resolve_refs_in_schema(schema["items"])
+        if "prefixItems" in schema:
+            schema["prefixItems"] = [
+                self.get_ref("schema", s) if isinstance(s, (dict, str)) else s
+                for s in schema["prefixItems"]
+            ]
+            for sch in schema["prefixItems"]:
+                if isinstance(sch, dict):
+                    self._resolve_refs_in_schema(sch)
         for key in ("allOf", "oneOf", "anyOf"):
             if key in schema:
                 schema[key] = [self.get_ref("schema", s) for s in schema[key]]

src/apispec/ext/marshmallow/field_converter.py

@@ -19,6 +19,8 @@
 from marshmallow.orderedset import OrderedSet
 from packaging.version import Version
 
+from apispec.exceptions import APISpecError
+
 # marshmallow field => (JSON Schema type, format)
 DEFAULT_FIELD_MAPPING: dict[type, tuple[str | None, str | None]] = {
     marshmallow.fields.Integer: ("integer", None),
@@ -38,6 +40,7 @@
     marshmallow.fields.Field: (None, None),
     marshmallow.fields.Raw: (None, None),
     marshmallow.fields.List: ("array", None),
+    marshmallow.fields.Tuple: ("array", None),
     marshmallow.fields.IP: ("string", "ip"),
     marshmallow.fields.IPv4: ("string", "ipv4"),
     marshmallow.fields.IPv6: ("string", "ipv6"),
@@ -69,6 +72,7 @@
     "enum",
     "type",
     "items",
+    "prefixItems",
     "allOf",
     "oneOf",
     "anyOf",
@@ -112,6 +116,7 @@ def init_attribute_functions(self):
             self.nested2properties,
             self.pluck2properties,
             self.list2properties,
+            self.tuple2properties,
             self.dict2properties,
             self.timedelta2properties,
             self.datetime2properties,
@@ -365,7 +370,12 @@ def field2length(
         ]
 
         is_array = isinstance(
-            field, (marshmallow.fields.Nested, marshmallow.fields.List)
+            field,
+            (
+                marshmallow.fields.Nested,
+                marshmallow.fields.List,
+                marshmallow.fields.Tuple,
+            ),
         )
         min_attr = "minItems" if is_array else "minLength"
         max_attr = "maxItems" if is_array else "maxLength"
@@ -503,6 +513,27 @@ def list2properties(self, field, **kwargs: typing.Any) -> dict:
             ret["items"] = self.field2property(field.inner)
         return ret
 
+    def tuple2properties(
+        self, field: marshmallow.fields.Field, **kwargs: typing.Any
+    ) -> dict:
+        """Return a dictionary of properties from :class:`Tuple <marshmallow.fields.Tuple>` fields.
+
+        Will provide `prefixItems` and `items: False` properties based on the field's `tuple_fields` attribute.
+
+        :param Field field: A marshmallow field.
+        :rtype: dict
+        """
+        ret: dict[str, typing.Any] = {}
+        if isinstance(field, marshmallow.fields.Tuple):
+            if (self.openapi_version.major, self.openapi_version.minor) < (3, 1):
+                raise APISpecError(
+                    f"Tuple field is only supported in OpenAPI 3.1.0 and above. "
+                    f"Current OpenAPI version is {self.openapi_version}."
+                )
+            ret["prefixItems"] = [self.field2property(f) for f in field.tuple_fields]
+            ret["items"] = False
+        return ret
+
     def dict2properties(self, field, **kwargs: typing.Any) -> dict:
         """Return a dictionary of properties from :class:`Dict <marshmallow.fields.Dict>` fields.
 

src/apispec/ext/marshmallow/schema_resolver.py

@@ -282,8 +282,17 @@ def resolve_schema_dict(self, schema):
         :param string|Schema|dict schema: the schema to resolve.
         """
         if isinstance(schema, dict):
-            if schema.get("type") == "array" and "items" in schema:
+            if (
+                schema.get("type") == "array"
+                and "items" in schema
+                and not isinstance(schema["items"], bool)
+            ):
                 schema["items"] = self.resolve_schema_dict(schema["items"])
+            if "prefixItems" in schema:
+                schema["prefixItems"] = [
+                    self.resolve_schema_dict(s) if not isinstance(s, bool) else s
+                    for s in schema["prefixItems"]
+                ]
             if schema.get("type") == "object" and "properties" in schema:
                 schema["properties"] = {
                     k: self.resolve_schema_dict(v)

tests/test_core.py

@@ -404,6 +404,23 @@ def test_components_resolve_refs_in_schema(self, spec):
         spec.components.schema("refs_schema", copy.deepcopy(self.REFS_SCHEMA))
         self.assert_schema_refs(spec, get_schemas(spec)["refs_schema"])
 
+    @pytest.mark.parametrize("spec", ("3.1.0",), indirect=True)
+    def test_components_resolve_refs_in_schema_openapi_3_1_tuple(self, spec):
+        spec.components.schema(
+            "tuple_schema",
+            {
+                "type": "array",
+                "prefixItems": ["NestedSchema", {"type": "string"}],
+                "items": False,
+            },
+        )
+        schema = get_schemas(spec)["tuple_schema"]
+        assert schema["items"] is False
+        assert schema["prefixItems"] == [
+            build_ref(spec, "schema", "NestedSchema"),
+            {"type": "string"},
+        ]
+
     def test_components_resolve_response_schema(self, spec):
         schema = {"schema": "PetSchema"}
         if spec.openapi_version.major >= 3:

tests/test_ext_marshmallow.py

@@ -7,11 +7,13 @@
     DateTime,
     Dict,
     Field,
+    Float,
     Int,
     List,
     Nested,
     String,
     TimeDelta,
+    Tuple,
 )
 from packaging.version import Version
 
@@ -36,6 +38,7 @@
     get_paths,
     get_responses,
     get_schemas,
+    validate_spec,
 )
 
 MA_VERSION = Version(importlib.metadata.version("marshmallow"))
@@ -1369,3 +1372,94 @@ class SchemaWithTimeDelta(Schema):
             get_schemas(spec)["SchemaWithTimeDelta"]["properties"]["day"]["x-unit"]
             == "days"
         )
+
+
+class TestTuple:
+    @pytest.mark.parametrize("openapi_version", ("2.0", "3.0.0"))
+    def test_tuple_unsupported_openapi_versions(self, openapi_version):
+        class SchemaWithTuple(Schema):
+            point = Tuple([Float(), Float()])
+
+        spec = APISpec(
+            title="Tuple Test",
+            version="0.1",
+            openapi_version=openapi_version,
+            plugins=(MarshmallowPlugin(),),
+        )
+        with pytest.raises(
+            APISpecError,
+            match="Tuple field is only supported in OpenAPI 3.1.0 and above.",
+        ):
+            spec.components.schema("SchemaWithTuple", schema=SchemaWithTuple)
+
+    def test_tuple_in_schema_openapi_3_1(self):
+        class SchemaWithTuple(Schema):
+            point = Tuple([Float(), Float()])
+
+        spec = APISpec(
+            title="Tuple Test",
+            version="0.1",
+            openapi_version="3.1.0",
+            plugins=(MarshmallowPlugin(),),
+        )
+        spec.components.schema("SchemaWithTuple", schema=SchemaWithTuple)
+
+        result = get_schemas(spec)["SchemaWithTuple"]["properties"]["point"]
+        assert result == {
+            "type": "array",
+            "prefixItems": [{"type": "number"}, {"type": "number"}],
+            "items": False,
+        }
+        assert validate_spec(spec)
+
+    def test_tuple_with_nested_schema_openapi_3_1(self):
+        class SchemaWithNestedTuple(Schema):
+            pair = Tuple([Nested(PetSchema), String()])
+
+        spec = APISpec(
+            title="Nested Tuple Test",
+            version="0.1",
+            openapi_version="3.1.0",
+            plugins=(MarshmallowPlugin(),),
+        )
+        spec.components.schema("SchemaWithNestedTuple", schema=SchemaWithNestedTuple)
+
+        assert len(get_schemas(spec)) == 2
+        result = get_schemas(spec)["SchemaWithNestedTuple"]["properties"]["pair"]
+        assert result == {
+            "type": "array",
+            "prefixItems": [build_ref(spec, "schema", "Pet"), {"type": "string"}],
+            "items": False,
+        }
+        assert validate_spec(spec)
+
+    def test_tuple_in_operation_openapi_3_1(self):
+        class CoordSchema(Schema):
+            coords = Tuple([Int(), String()])
+
+        spec = APISpec(
+            title="Operation Tuple Test",
+            version="0.1",
+            openapi_version="3.1.0",
+            plugins=(MarshmallowPlugin(),),
+        )
+        spec.path(
+            "/coords",
+            operations={
+                "get": {
+                    "responses": {
+                        "200": {
+                            "description": "Coordinates response",
+                            "content": {"application/json": {"schema": CoordSchema}},
+                        }
+                    }
+                }
+            },
+        )
+        schema = get_schemas(spec)["Coord"]
+        assert schema["properties"]["coords"] == {
+            "type": "array",
+            "prefixItems": [{"type": "integer"}, {"type": "string"}],
+            "items": False,
+        }
+        assert validate_spec(spec)

tests/test_ext_marshmallow_field.py

@@ -7,6 +7,8 @@
 from marshmallow import Schema, fields, validate
 from packaging.version import Version
 
+from apispec.exceptions import APISpecError
+
 from .schemas import CategorySchema, CustomIntegerField, CustomList, CustomStringField
 from .utils import build_ref, get_schemas
 
@@ -779,3 +781,105 @@ def test_field2property_examples(spec_fixture):
     assert res == {
         "examples": ["foo", "bar"],
     }
+
+
+class TestField2PropertyTuple:
+    @pytest.mark.parametrize("spec_fixture", ("2.0", "3.0.0"), indirect=True)
+    def test_tuple_unsupported_openapi_versions(self, spec_fixture):
+        field = fields.Tuple([fields.Integer(), fields.String()])
+        with pytest.raises(
+            APISpecError,
+            match="Tuple field is only supported in OpenAPI 3.1.0 and above.",
+        ):
+            spec_fixture.openapi.field2property(field)
+
+    @pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
+    def test_tuple_simple(self, spec_fixture):
+        field = fields.Tuple([fields.Integer(), fields.String()])
+        res = spec_fixture.openapi.field2property(field)
+        assert res == {
+            "type": "array",
+            "prefixItems": [{"type": "integer"}, {"type": "string"}],
+            "items": False,
+        }
+
+    @pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
+    def test_tuple_empty(self, spec_fixture):
+        field = fields.Tuple([])
+        res = spec_fixture.openapi.field2property(field)
+        assert res == {
+            "type": "array",
+            "prefixItems": [],
+            "items": False,
+        }
+
+    @pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
+    def test_tuple_nullable(self, spec_fixture):
+        field = fields.Tuple([fields.Integer()], allow_none=True)
+        res = spec_fixture.openapi.field2property(field)
+        assert res == {
+            "type": ["array", "null"],
+            "prefixItems": [{"type": "integer"}],
+            "items": False,
+        }
+
+    @pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
+    def test_tuple_length_validator(self, spec_fixture):
+        field = fields.Tuple(
+            [fields.Integer(), fields.String()],
+            validate=validate.Length(equal=2),
+        )
+        res = spec_fixture.openapi.field2property(field)
+        assert res == {
+            "type": "array",
+            "prefixItems": [{"type": "integer"}, {"type": "string"}],
+            "items": False,
+            "minItems": 2,
+            "maxItems": 2,
+        }
+
+    @pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
+    def test_tuple_dump_only_and_load_only(self, spec_fixture):
+        dump_field = fields.Tuple([fields.Integer()], dump_only=True)
+        assert spec_fixture.openapi.field2property(dump_field) == {
+            "type": "array",
+            "prefixItems": [{"type": "integer"}],
+            "items": False,
+            "readOnly": True,
+        }
+
+        load_field = fields.Tuple([fields.Integer()], load_only=True)
+        assert spec_fixture.openapi.field2property(load_field) == {
+            "type": "array",
+            "prefixItems": [{"type": "integer"}],
+            "items": False,
+            "writeOnly": True,
+        }
+
+    @pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
+    def test_tuple_metadata(self, spec_fixture):
+        field = fields.Tuple(
+            [fields.Integer()],
+            metadata={"description": "Tuple of coordinates"},
+        )
+        assert spec_fixture.openapi.field2property(field) == {
+            "type": "array",
+            "prefixItems": [{"type": "integer"}],
+            "items": False,
+            "description": "Tuple of coordinates",
+        }
+
+    @pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
+    def test_tuple_nested(self, spec_fixture):
+        field = fields.Tuple([fields.Tuple([fields.Integer()])])
+        assert spec_fixture.openapi.field2property(field) == {
+            "type": "array",
+            "prefixItems": [
+                {
+                    "type": "array",
+                    "prefixItems": [{"type": "integer"}],
+                    "items": False,
+                }
+            ],
+            "items": False,
+        }