Rename Schema to Field?

[samuelcolvin]

Currently we have the class Schema for when you need to define more stuff on a field than just the type and default.

But this is a confusing name since not all it's arguments refer to the schema. It'll get more confusing if we want to add more arguments to Schema/Field, eg. a more complex alias system #477.

Therefore we should rename it to Field.

This would require:

• renaming the current Field class, perhaps renaming the entire fields.py module.
• Schema needs to carry on working for a while but with a deprecation warning

What does everyone thing?

@tiangolo Schema was your work originally, are you ok with this?

[tiangolo]

Thanks for tagging me. Yep. I think it makes sense.

If we can keep supporting it for a while with a deprecation warning, we should be fine.

And thinking about it, it actually makes more sense for it to be Field.

---

Slightly related, currently Schema (soon to be Field) is a class. When declaring a Pydantic field with:

a: int = Schema(...)

mypy complains that a should be of type int but is being of type Schema.

One way I'm "hacking" it in FastAPI (for stuff that inherits from Schema) is to create a function with a return type annotation of Any (while it is returning a Schema instance).

Then because the return of the function is annotated as Any, mypy accepts it.

I think this is something that could be interesting to have here too, maybe worth considering during this change.

[jasonkuhrt]

In favour of this change too.

This seems to align better with dataclass terminology too, https://docs.python.org/3/library/dataclasses.html#dataclasses.field.

For consideration: is there a possibility that the similarity would be a bad thing, rather than good?

[tiangolo]

I agree with @jasonkuhrt that using a field function would be nice. Being a function that actually returns a class would fix mypy errors when using Schema (or the next, Field), as a function can be typed to return Any. In fact, I'm doing something like that in FastAPI.

Also, by implementing a field function right away we could update the docs and show the new interface to new users, even while Schema is not yet renamed to Field (and the current Field to something else).

I wanna take a shot at this.

I have some naming questions:

• Is it OK a field function exposed as the main interface instead of the corresponding class?
  • Would you prefer another function name? Or a capitalized version (a function Field) that simulates the class name, even while it's a function?
• What would be an acceptable name for the current Field class?

---

On the other side, having just a function field that returns a Schema class would solve the visible naming issue for users, that could be enough, without needing to rename the underlying classes. The drawback is that the internal names would be more difficult for newcomer contributors to the internal code.

[samuelcolvin]

I think the function should be called Field, it should have an alias called Schema that also returns a Field but also raises a warning.

The only question is what do we call the class? It would be confusing to also call it Field, how about FieldInfo?

Please take a shot. I want to work on v1 features once v0.32 is released.