Change Summary

Requires pydantic/pydantic-core#1711.

Fixes #5326.
Fixes #6928.
Fixes #7712.
Fixes #8394.
Fixes #9057.
Fixes #11705.
Fixes #11843.

Example:

from pydantic import BaseModel
from pydantic.experimental.missing_sentinel import MISSING


class A(BaseModel):
    a: int | MISSING = MISSING

a1 = A()
a1.model_dump()
#> {}

a2 = A(a=1)
a2.model_dump()
#> {'a': 1}

A.model_json_schema()
#> {'properties': {'a': {'title': 'A', 'type': 'integer'}}, 'title': 'A', 'type': 'object'}

class B(BaseModel):
    a: MISSING = MISSING


B.model_json_schema()
#> {'properties': {}, 'title': 'B', 'type': 'object'}

Things to consider:

• Sentinel name: UNSET seems to be the best fit (and matches msgspec), but will be confusing as we already have a concept of unset fields (tracked in __pydantic_fields_set__). These unset fields can already be excluded by specifying exclude_unset=True during serialization. If users explicitly set exclude_unset=False but the UNSET sentinel is still excluded, this will be confusing. One alternative could be MISSING: it also makes it a little bit clearer that the expected behavior is to have fields set to MISSING excluded from the output. Went with MISSING.
• Sentinel location: currently defined in pydantic-core, but we need to expose it from the experimental module as we rely on the draft PEP 661.
• Should we create a new core schema for the UNSET sentinel? I'm currently using a 'literal' schema, but not ideal for a couple reasons:
  • The core validator uses equality to validate literal values, but sentinels should be compared using identity.
  • If we happen to implement an optimization where we merge 'literal' schemas together (e.g. Literal[1] | UNSET -> Literal[1, UNSET]), we would need to account for this in the JSON Schema generation logic). Went with a new core schema type.