Skip to content

Commit e1c6f23

Browse files
SarthakB11Siyet
andauthored
place null last in anyOf for optional unions in JSON schema (#1028)
Fixes #1027. For `T | None`, `_json_schema.py` was emitting `{"type": "null"}` before the struct/`$ref` entry in `anyOf`. Tools that pick the first `anyOf` element for example generation (Swagger UI in the issue) ended up showing `null`. Pydantic puts `null` last for the same reason. Move `NoneType` out of the union iteration into a `has_none` flag and append `{"type": "null"}` last in all three union branches (no-struct, single-struct, tagged-struct). The tagged-struct branch's `if options:` guard becomes `if options or has_none:` so `Tagged | None` keeps `null` in its `anyOf` instead of dropping it. Observable changes: - `Struct | None`: was `[null, $ref]`, now `[$ref, null]`. - `Union[X, None, Y]`: `null` moves from the middle to the end. - `str | None`: already `[string, null]` on CPython, unchanged. Tests added in `tests/unit/test_schema.py` for `Optional[Struct]`, `Union[int, None, str]`, and `Union[Tagged, None]` (covers the third branch that previously dropped `null` entirely). --------- Signed-off-by: SarthakB11 <[email protected]> Co-authored-by: Siyet <[email protected]>
1 parent ecf2282 commit e1c6f23

2 files changed

Lines changed: 93 additions & 0 deletions

File tree

‎src/msgspec/_json_schema.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -330,6 +330,8 @@ def to_schema(self, t: mi.Type, check_ref: bool = True) -> dict[str, Any]:
330330
elif isinstance(t, mi.UnionType):
331331
structs = {}
332332
other = []
333+
has_none = False
334+
none_member = None
333335
tag_field = None
334336
for subtype in t.types:
335337
real_type = subtype
@@ -338,6 +340,9 @@ def to_schema(self, t: mi.Type, check_ref: bool = True) -> dict[str, Any]:
338340
if isinstance(real_type, mi.StructType) and not real_type.array_like:
339341
tag_field = real_type.tag_field
340342
structs[real_type.tag] = real_type
343+
elif isinstance(real_type, mi.NoneType):
344+
has_none = True
345+
none_member = subtype
341346
else:
342347
other.append(subtype)
343348

@@ -354,14 +359,22 @@ def to_schema(self, t: mi.Type, check_ref: bool = True) -> dict[str, Any]:
354359
}
355360
if options:
356361
options.append(struct_schema)
362+
if has_none:
363+
options.append(self.to_schema(none_member))
357364
schema["anyOf"] = options
365+
elif has_none:
366+
schema["anyOf"] = [struct_schema, self.to_schema(none_member)]
358367
else:
359368
schema.update(struct_schema)
360369
elif len(structs) == 1:
361370
_, subtype = structs.popitem()
362371
options.append(self.to_schema(subtype))
372+
if has_none:
373+
options.append(self.to_schema(none_member))
363374
schema["anyOf"] = options
364375
else:
376+
if has_none:
377+
options.append(self.to_schema(none_member))
365378
schema["anyOf"] = options
366379
elif isinstance(t, mi.LiteralType):
367380
# `t.values` may mix types (e.g. `Literal[1, None]`), which a plain

‎tests/unit/test_schema.py‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
Literal,
1818
NamedTuple,
1919
NewType,
20+
Optional,
2021
Set,
2122
Tuple,
2223
TypedDict,
@@ -828,6 +829,29 @@ class Ex(Generic[T]):
828829
}
829830

830831

832+
def test_optional_struct_null_last():
833+
class Example(msgspec.Struct):
834+
x: int
835+
836+
assert msgspec.json.schema(Optional[Example]) == {
837+
"anyOf": [{"$ref": "#/$defs/Example"}, {"type": "null"}],
838+
"$defs": {
839+
"Example": {
840+
"title": "Example",
841+
"type": "object",
842+
"properties": {"x": {"type": "integer"}},
843+
"required": ["x"],
844+
}
845+
},
846+
}
847+
848+
849+
def test_optional_union_null_last():
850+
assert msgspec.json.schema(Union[int, None, str]) == {
851+
"anyOf": [{"type": "integer"}, {"type": "string"}, {"type": "null"}],
852+
}
853+
854+
831855
@pytest.mark.parametrize("use_union_operator", [False, True])
832856
def test_union(use_union_operator):
833857
class Example(msgspec.Struct):
@@ -899,6 +923,28 @@ class Point3D(Point):
899923
)
900924

901925

926+
def test_struct_tagged_union_with_none():
927+
class Point(msgspec.Struct, tag=True):
928+
x: int
929+
y: int
930+
931+
class Point3D(Point):
932+
z: int
933+
934+
schema = msgspec.json.schema(Union[Point, Point3D, None])
935+
assert schema["anyOf"] == [
936+
{
937+
"anyOf": [{"$ref": "#/$defs/Point"}, {"$ref": "#/$defs/Point3D"}],
938+
"discriminator": {
939+
"mapping": {"Point": "#/$defs/Point", "Point3D": "#/$defs/Point3D"},
940+
"propertyName": "type",
941+
},
942+
},
943+
{"type": "null"},
944+
]
945+
assert "discriminator" not in schema
946+
947+
902948
def test_struct_tagged_union_mixed_types():
903949
class Point(msgspec.Struct, tag=True):
904950
x: int
@@ -945,6 +991,40 @@ class Point3D(Point):
945991
}
946992

947993

994+
def test_struct_tagged_union_with_none_and_other():
995+
class Point(msgspec.Struct, tag=True):
996+
x: int
997+
y: int
998+
999+
class Point3D(Point):
1000+
z: int
1001+
1002+
schema = msgspec.json.schema(Union[Point, Point3D, int, None])
1003+
assert schema["anyOf"] == [
1004+
{"type": "integer"},
1005+
{
1006+
"anyOf": [{"$ref": "#/$defs/Point"}, {"$ref": "#/$defs/Point3D"}],
1007+
"discriminator": {
1008+
"mapping": {"Point": "#/$defs/Point", "Point3D": "#/$defs/Point3D"},
1009+
"propertyName": "type",
1010+
},
1011+
},
1012+
{"type": "null"},
1013+
]
1014+
assert "discriminator" not in schema
1015+
1016+
1017+
def test_optional_union_null_member_metadata_preserved():
1018+
NullWithMeta = Annotated[None, msgspec.Meta(description="explicitly unset")]
1019+
1020+
assert msgspec.json.schema(Union[int, NullWithMeta]) == {
1021+
"anyOf": [
1022+
{"type": "integer"},
1023+
{"type": "null", "description": "explicitly unset"},
1024+
],
1025+
}
1026+
1027+
9481028
def test_struct_array_union():
9491029
class Point(msgspec.Struct, array_like=True, tag=True):
9501030
x: int

0 commit comments

Comments
 (0)