Merge branch 'master' into prevent-schema-creation-race

Author: peter-doggart

CHANGELOG.rst

@@ -36,6 +36,8 @@ Bug Fixes
 
    * Add python version requirement on setup.py (#586) [jason-the-j]
    * Add a thread lock to avoid concurrent schema construction. (#545) [peter-doggart]
+   * Fix Nested field schema generation for nullable fields. (#638) [peter-doggart]
+   * Fix reference resolution for definitions in schema. (#553) [peter-doggart]
 
 .. _section-1.3.0:
 1.3.0

flask_restx/api.py

@@ -17,7 +17,7 @@
 
 from flask.signals import got_request_exception
 
-from jsonschema import RefResolver
+from referencing import Registry
 
 from werkzeug.utils import cached_property
 from werkzeug.datastructures import Headers
@@ -134,7 +134,7 @@ def __init__(
         format_checker=None,
         url_scheme=None,
         default_swagger_filename="swagger.json",
-        **kwargs
+        **kwargs,
     ):
         self.version = version
         self.title = title or "API"
@@ -830,7 +830,44 @@ def payload(self):
     @property
     def refresolver(self):
         if not self._refresolver:
-            self._refresolver = RefResolver.from_schema(self.__schema__)
+            # Create a registry that can resolve references within our schema
+            registry = Registry()
+            schema = self.__schema__
+
+            # If schema has definitions, register it
+            if "definitions" in schema:
+                schema_id = schema.get("$id", "http://localhost/schema.json")
+                registry = registry.with_resource(schema_id, schema)
+            else:
+                # If no definitions in schema, register all models individually
+                for name, model in self.models.items():
+                    model_schema = model.__schema__
+                    # Add $id to the model schema so it can be referenced
+                    if "$id" not in model_schema:
+                        model_schema = model_schema.copy()
+                        model_schema["$id"] = (
+                            f"http://localhost/schema.json#/definitions/{name}"
+                        )
+                    registry = registry.with_resource(
+                        f"http://localhost/schema.json#/definitions/{name}",
+                        model_schema,
+                    )
+
+                # Also register the root schema with definitions
+                if self.models:
+                    definitions = {}
+                    for name, model in self.models.items():
+                        definitions[name] = model.__schema__
+
+                    schema_with_definitions = {
+                        "$id": "http://localhost/schema.json",
+                        "definitions": definitions,
+                    }
+                    registry = registry.with_resource(
+                        "http://localhost/schema.json", schema_with_definitions
+                    )
+
+            self._refresolver = registry
         return self._refresolver
 
     @staticmethod
@@ -866,7 +903,7 @@ def _blueprint_setup_add_url_rule_patch(
             "%s.%s" % (blueprint_setup.blueprint.name, endpoint),
             view_func,
             defaults=defaults,
-            **options
+            **options,
         )
 
     def _deferred_blueprint_init(self, setup_state):

flask_restx/fields.py

@@ -134,6 +134,9 @@ class Raw(object):
     :param bool readonly: Is the field read only ? (for documentation purpose)
     :param example: An optional data example (for documentation purpose)
     :param callable mask: An optional mask function to be applied to output
+    :param bool nullable: Whether the field accepts null values in input
+        validation. When True, the generated JSON Schema will allow null
+        values for this field during request payload validation.
     """
 
     #: The JSON/Swagger schema type
@@ -153,6 +156,7 @@ def __init__(
         readonly=None,
         example=None,
         mask=None,
+        nullable=None,
         **kwargs
     ):
         self.attribute = attribute
@@ -163,6 +167,7 @@ def __init__(
         self.readonly = readonly
         self.example = example if example is not None else self.__schema_example__
         self.mask = mask
+        self.nullable = nullable
 
     def format(self, value):
         """
@@ -284,6 +289,19 @@ def schema(self):
             schema["allOf"] = allOf
         else:
             schema["$ref"] = ref
+
+        # If nullable is True, wrap using anyOf to permit nulls for input validation
+        if self.nullable:
+            # Remove structural keys that conflict with anyOf composition
+            for key in ("$ref", "allOf", "type", "items"):
+                schema.pop(key, None)
+            # Create anyOf with the original schema and null type
+            anyOf = [{"$ref": ref}]
+            if self.as_list:
+                anyOf = [{"type": "array", "items": {"$ref": ref}}]
+            anyOf.append({"type": "null"})
+            schema["anyOf"] = anyOf
+
         return schema
 
     def clone(self, mask=None):

flask_restx/model.py

@@ -11,6 +11,7 @@
 from .errors import abort
 
 from jsonschema import Draft4Validator
+from jsonschema.validators import validator_for
 from jsonschema.exceptions import ValidationError
 
 from .utils import not_none
@@ -89,9 +90,48 @@ def inherit(cls, name, *parents):
         return model
 
     def validate(self, data, resolver=None, format_checker=None):
-        validator = Draft4Validator(
-            self.__schema__, resolver=resolver, format_checker=format_checker
-        )
+        # For backward compatibility, resolver can be either a RefResolver or a Registry
+        if resolver is not None and hasattr(resolver, "resolve"):
+            # Old RefResolver - convert to registry
+            registry = None
+            validator = Draft4Validator(
+                self.__schema__, resolver=resolver, format_checker=format_checker
+            )
+        else:
+            # New Registry or None
+            # If we have a registry, we need to create a schema that includes definitions
+            schema_to_validate = self.__schema__
+            if resolver is not None:
+                # Check if the schema has $ref that need to be resolved
+                import json
+
+                schema_str = json.dumps(self.__schema__)
+                if '"$ref"' in schema_str:
+                    # Create a schema with inline definitions from the registry
+                    definitions = {}
+                    for uri in resolver:
+                        resource = resolver[uri]
+                        if isinstance(resource, dict) and "definitions" in resource:
+                            definitions.update(resource["definitions"])
+
+                    if definitions:
+                        # Create a new schema that includes the definitions
+                        schema_to_validate = {
+                            "$id": "http://localhost/schema.json",
+                            "definitions": definitions,
+                            **self.__schema__,
+                        }
+
+            ValidatorClass = validator_for(schema_to_validate)
+            if resolver is not None:
+                validator = ValidatorClass(
+                    schema_to_validate, registry=resolver, format_checker=format_checker
+                )
+            else:
+                validator = ValidatorClass(
+                    schema_to_validate, format_checker=format_checker
+                )
+
         try:
             validator.validate(data)
         except ValidationError:

requirements/install.pip

@@ -1,5 +1,6 @@
 aniso8601>=0.82
 jsonschema
+referencing
 Flask>=0.8, !=2.0.0
 werkzeug!=2.0.0
 importlib_resources

tests/test_fields.py

@@ -881,6 +881,17 @@ def test_with_allow_null(self, api):
         assert field.allow_null
         assert field.__schema__ == {"$ref": "#/definitions/NestedModel"}
 
+    def test_with_nullable_schema(self, api):
+        nested_fields = api.model("NestedModel", {"name": fields.String})
+        field = fields.Nested(nested_fields, nullable=True)
+        # Should allow null in schema via anyOf
+        assert field.__schema__ == {
+            "anyOf": [
+                {"$ref": "#/definitions/NestedModel"},
+                {"type": "null"},
+            ]
+        }
+
     def test_with_skip_none(self, api):
         nested_fields = api.model("NestedModel", {"name": fields.String})
         field = fields.Nested(nested_fields, skip_none=True)