Change Summary

Requirespydantic/pydantic-core#1711.

Example:

frompydanticimportBaseModelfrompydantic_coreimportUNSETclassA(BaseModel):a:int|UNSET=UNSETa1=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'}classB(BaseModel):a:UNSET=UNSETB.model_json_schema()#> {'properties': {}, 'title': 'B', 'type': 'object'}

Things to consider:

• Sentinel name:UNSET seems to be the best fit (andmatchesmsgspec), 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 specifyingexclude_unset=True during serialization. If users explicitly setexclude_unset=False but theUNSET sentinel is still excluded, this will be confusing. One alternative could beMISSING: it also makes it a little bit clearer that the expected behavior is to have fields set toMISSING excluded from the output.
• Sentinel location: currently defined inpydantic-core, but we need to expose it from theexperimental module as we rely on the draftPEP 661.
• Should we create a new core schema for theUNSET 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).