More consistent and intuitive `alias` behavior for validation and serialization

[sydney-runkle]

Right now, we have some inconsistent behavior in terms of using aliases in validation and serialization.

By default, if an alias or validation_alias is defined on a field, we use the alias for validation. This behavior can be changed by setting populate_by_name to True on the model_config.

Conversely, if an alias or serialization_alias is defined on a field, that alias not used by default for serialization. We must specify by_alias=True in the call to model_dump + other serialization functions.

I propose that in V3:

• We use alias by default for both validation and serialization
• We add a field (or fields, but ideally just one) to ConfigDict to support different behavior than the default

This is a breaking change, hence the V3 label.

Requests to change the inconsistent default behavior have been made for a few years, so I'm going to comb through issues and close those so we can centralize discussion here.

[marcussaad]

Plus one having this behavior match and an option to pass to ConfigDict!

[bluenote10]

It would be great if this could be considered for V2 as well, because it looks more like a bug currently, no? The current behavior is not what the original plan for the alias system #5426 (comment) had specified (every other row in that specification table currently misbehaves). Also, the current behavior means that it is effectively not possible in V2 to decouple the Python field name from its serialized name -- which is kind of the primary feature of the alias system.

[sydney-runkle]

@bluenote10,

Though I agree that the current behavior is not great, changing the API is enough of a breaking change that I don't think it makes sense to do in V2.

Thanks for linking that comment - that's a helpful reference to have in the future on this issue.

Also, the current behavior means that it is effectively not possible in V2 to decouple the Python field name from its serialized name -- which is kind of the primary feature of the alias system.

Could you please say more about this? I don't think I understand the issue you're having.

[bluenote10]

Could you please say more about this? I don't think I understand the issue you're having.

I'm often seeing variations of code that contains funny comments like these:

class SomeModel(BaseModel):
    # Please don't change these field names even though they poorly named!
    # They are determined by external API X / third-party JSON schema Y / ...
    foo: int
    bar: int

or even

class SomeModel(BaseModel):
    # Please don't fix the typo in this field name to avoid breaking backwards compatibility.
    field_wit_typo: int

This raises the question: Can we not simply decouple the field name visible in the code from the representation in the serialized layer? The alias system seems to be the feature that should provide exactly that. Ideally the code should look like:

class SomeModel(BaseModel):
    # We are decoupling the field names from external API X for better readability
    better_named_foo: int = Field(alias="foo")
    better_named_bar: int = Field(alias="bar")

However currently in V2 the alias system is a rather dangerous pitfall: It suggests that it addresses this use case but it doesn't! The above code looks right, and a shallow experiment may even wrongly conclude that it does what one expects. But as demonstrated in #8551, none of the 8 possible combinations of alias, validation_alias, serialization_alias and populate_by_name actually behaves correctly in the sense of fully decoupling the field name (behaving exactly like the un-aliased model)!

Identifying each and every occurrence of model_dump and adding by_alias is not "behaving like the un-aliased model": Forgetting to do so is very easy (especially in generic usages of models), and will be a big bug, because the code will serialize to an invalid payload. This strategy is way too bug prone to be a realistic work-around.

Having to use a custom serializer on top doesn't feel right either. Currently the alias system is non-intuitive, does not cover its primary use case, does not follow the docs and the specs in #5426 (comment), so it looks a bit more like a bug, no?

[justin-snyder-slgg]

This is a pretty major pitfall for my current attempt at upgrading a codebase to 2.x. While V2 aliases seemed promising at first, I am still running into a fair amount of frustration with regards to the by_alias=False default and surprising behavior where sometimes the wrong name is being serialized into the json.

[alexanderankin]

are we just waiting for PR's on this? right? or are we not sold on a particular solution - where are we at with this?

diff --git a/pydantic/config.py b/pydantic/config.py
index 7edf7c60..504d627d 100644
--- a/pydantic/config.py
+++ b/pydantic/config.py
@@ -161,6 +161,11 @@ class ConfigDict(TypedDict, total=False):
     3. The model is populated by the field name `'name'`.
     """
 
+    serialize_by_name: bool
+    """
+    counter part to populate_by_name
+    """
+
     use_enum_values: bool
     """
     Whether to populate models with the `value` property of enums, rather than the raw enum.
diff --git a/pydantic/main.py b/pydantic/main.py
index 525c8f98..fc61d8a7 100644
--- a/pydantic/main.py
+++ b/pydantic/main.py
@@ -363,6 +363,8 @@ class BaseModel(metaclass=_model_construction.ModelMetaclass):
         Returns:
             A JSON string representation of the model.
         """
+        if self.model_config.get("serialize_by_name", False):
+            by_alias = True
         return self.__pydantic_serializer__.to_json(
             self,
             indent=indent,

</details.

[samuelcolvin]

I think we can add an option to config now. We can't change the default behaviour until V3.