Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Serialization

Aliases and Naming Conventions

Map JSON keys to Python field names with Pydantic aliases: alias, validation_alias, serialization_alias, populate_by_name, AliasPath and alias generators for camelCase APIs.

Python code uses snake_case; many JSON APIs use camelCase or odd names such as @id or user-name. You do not want your Python to look like the wire format, and you do not want to rename keys by hand. Aliases let a field have one name in Python and another in the data.

alias: one name for input and output

Field(alias="...") sets the key that is expected in the input. When you dump, the Python name is used by default, unless you ask for aliases with by_alias=True.

Python A basic alias

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

By default, once an alias is set, only the alias is accepted as input. Creating User(user_id=7, ...) with keywords would fail. You have two ways to allow both:

Python Accepting the Python name too

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

populate_by_name=True accepts both the alias and the field name when reading. In newer versions you can be more precise with validate_by_name and validate_by_alias in the config, but populate_by_name is the one you will see most.

Separate names for reading and writing

Sometimes the incoming key differs from the outgoing one. Use two arguments instead of alias:

  • validation_alias: the key(s) accepted on input.
  • serialization_alias: the key written on output when you use by_alias=True.
Python validation_alias and serialization_alias

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

AliasChoices and AliasPath

A single field can accept several possible keys, or reach into nested data:

Python Choices and paths

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

AliasChoices tries each key in order; AliasPath digs into nested dictionaries and lists, so you can flatten awkward input without a custom validator.

Alias generators: convert the whole model

Writing alias="..." on every field is tedious. An alias generator is a function that turns every field name into its alias. Pydantic provides ready-made ones in pydantic.alias_generators: to_camel, to_pascal and to_snake.

Python camelCase for the entire model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Put the config in a shared base class (as in Inheritance and Generics) and every model in the project talks camelCase to the outside world while staying snake_case inside.

FastAPI serializes responses with aliases by default, so by_alias=True is not needed when you return a model from an endpoint. For plain model_dump calls you must pass it yourself. If you want it automatic everywhere, set serialize_by_alias=True in the model config (available in recent Pydantic versions).

Aliases and error locations

Errors report locations using the alias (the key as it appeared in the input), because that is what the client sent. This helps API users find their mistake, as the key in the error matches their payload.

Python Errors show the alias

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Reserved names

A field cannot be called model_config, and field names that start with model_ trigger a warning about the protected namespace. If you have a column named model_name, either rename it or give it an alias and a different Python name: ai_model: str = Field(alias="model_name").

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. With user_id: int = Field(alias='userId'), which keyword does User(...) accept by default?

    Only the alias is accepted unless you set populate_by_name=True.
  2. 2. What does by_alias=True change?

    Dumps use Python names by default; by_alias=True writes the alias keys.
  3. 3. Which tool lets one field accept 'email', 'mail' or 'e-mail'?

    AliasChoices lists alternative input keys, tried in order.
  4. 4. How do you make every field of every model use camelCase aliases?

    An alias generator in a shared base class converts all field names automatically.

Summary

  • Field(alias=...) maps an input key to a Python field; dumps use aliases only with by_alias=True.
  • Set populate_by_name=True to accept the Python field name as well.
  • validation_alias and serialization_alias give different names for reading and writing.
  • AliasChoices accepts several keys; AliasPath reads nested values.
  • An alias_generator such as to_camel in a shared base config converts a whole model.

Next: Computed Fields and Custom Serializers