OpenAPI schema omits int64 format for negative values outside int32 range

[zainnadeem786]

Summary

OpenAPI schema generation appears to omit format: int64 for IntegerField values below the signed int32 minimum.

Positive integer values above the signed int32 maximum are handled correctly, but negative values below -2147483648 do not appear to trigger format: int64.

Reproduction

from rest_framework import serializers
from rest_framework.schemas.openapi import AutoSchema

schema = AutoSchema()

print(schema.map_field(serializers.IntegerField(min_value=-2147483649)))
print(schema.map_field(serializers.IntegerField(min_value=-2147483648)))
print(schema.map_field(serializers.IntegerField(max_value=2147483648)))
print(schema.map_field(serializers.IntegerField(max_value=2147483647)))

Actual behavior

{'type': 'integer', 'minimum': -2147483649}

{'type': 'integer', 'minimum': -2147483648}

{'type': 'integer', 'maximum': 2147483648, 'format': 'int64'}

{'type': 'integer', 'maximum': 2147483647}

Expected behavior

min_value=-2147483649 should include format: int64 because the value is outside the signed int32 range:

{'type': 'integer', 'minimum': -2147483649, 'format': 'int64'}

The boundary values should remain unchanged:

{'type': 'integer', 'minimum': -2147483648}
{'type': 'integer', 'maximum': 2147483647}

Investigation

The current int64 detection appears to compare both bounds only against the signed int32 upper limit:

if int(content.get('maximum', 0)) > 2147483647 or int(content.get('minimum', 0)) > 2147483647:
    content['format'] = 'int64'

A negative minimum value can never satisfy minimum > 2147483647, so values below the signed int32 lower bound are not detected.

Impact

Generated OpenAPI schemas may under-specify integer size requirements for APIs that allow values below the signed int32 range.

This affects schema accuracy only. Runtime validation behavior is unchanged.

Suggested fix

Add the missing lower-bound comparison:

if (
    int(content.get('maximum', 0)) > 2147483647 or
    int(content.get('minimum', 0)) < -2147483648
):
    content['format'] = 'int64'

Suggested tests

Add OpenAPI field mapping cases for:

• IntegerField(min_value=-2147483649) emits format: int64
• IntegerField(min_value=-2147483648) does not emit format: int64
• IntegerField(max_value=2147483648) continues to emit format: int64
• IntegerField(max_value=2147483647) does not emit format: int64

I would be happy to prepare a small PR with regression tests if this behavior is considered a bug.

[browniebroke]

Interesting... We also have a BigIntegerField now:

django-rest-framework/rest_framework/fields.py

Lines 925 to 944 in cf582fb

	class BigIntegerField(IntegerField):
	default_error_messages = {
	'invalid': _('A valid biginteger is required.'),
	'max_value': _('Ensure this value is less than or equal to {max_value}.'),
	'min_value': _('Ensure this value is greater than or equal to {min_value}.'),
	'max_string_length': _('String value too large.')
	}
	def __init__(self, coerce_to_string=None, **kwargs):
	super().__init__(**kwargs)
	if coerce_to_string is not None:
	self.coerce_to_string = coerce_to_string
	def to_representation(self, value):
	if getattr(self, 'coerce_to_string', api_settings.COERCE_BIGINT_TO_STRING):
	return '' if value is None else str(value)
	return super().to_representation(value)

One of the reason was that some languages don't handle int64 well

The suggested fix will break if minimum > 2147483647 (positive)

[zainnadeem786]

Good point, thanks for catching that. @browniebroke

You're right that the suggested fix should preserve the existing positive minimum > 2147483647 behavior as well. A safer condition would be to check both signed int32 boundaries while keeping the current positive minimum case:

minimum = content.get('minimum')
maximum = content.get('maximum')

if (
    (maximum is not None and maximum > 2147483647) or
    (minimum is not None and (minimum > 2147483647 or minimum < -2147483648))
):
    content['format'] = 'int64'

That would preserve the existing behavior for large positive minimum values and also cover negative values below the signed int32 lower bound.

For BigIntegerField, I can also check the current OpenAPI mapping behavior separately before preparing a PR, so the fix does not conflict with the newer bigint handling or COERCE_BIGINT_TO_STRING behavior.

[zainnadeem786]

@browniebroke I checked the current BigIntegerField mapping separately.

BigIntegerField currently does not have dedicated OpenAPI handling. Since it subclasses IntegerField, it goes through the existing integer mapping branch.

Current behavior:

serializers.BigIntegerField()
# {'type': 'integer'}

serializers.BigIntegerField(min_value=-2147483649)
# {'type': 'integer', 'minimum': -2147483649}

serializers.BigIntegerField(max_value=2147483648)
# {'type': 'integer', 'maximum': 2147483648, 'format': 'int64'}

coerce_to_string=True and the global COERCE_BIGINT_TO_STRING=True setting also currently do not change the OpenAPI schema output.

Given that, I agree it would be better not to change BigIntegerField behavior broadly in this discussion/PR.

The narrow scope I would propose is only to fix the signed int32 boundary detection in the existing integer mapping logic, while preserving the existing positive minimum > 2147483647 behavior:

minimum = content.get('minimum')
maximum = content.get('maximum')

if (
    (maximum is not None and maximum > 2147483647) or
    (minimum is not None and (minimum > 2147483647 or minimum < -2147483648))
):
    content['format'] = 'int64'

That would fix the negative lower-bound case without changing unconditional BigIntegerField schema behavior or coerce_to_string handling.