Root Errors and "__obj__" vs "__root__"

[samuelcolvin]

Currently here (for invalid data to parse_obj) and here (in parse_raw) we use '__obj__' as the location for errors to indicate an error which is general to the model, not specific to a field.

We should change this in v1 to __root__ to better match other nomenclature, eg. custom root types, where we use __root__.

We should also implement at some point entire model validation, as discussed at #691 (comment). I guess to match the above naming, we should do this using a special value to a validator @validator('__root__'). If this raised an error it would end up in ValidationError details with 'location': '__root__', (Unless it's a "@validator('__root__')" validator for a submodel, when obviously it should have the location of that model.

Perhaps it would would be nice to have a special decorator @root_validator which is an alias of @validator('__root__'), we should support multiple root validators either as a result of inheritance or on a single class.

I guess the __obj__ > __root__ change must happen with v1 and the new root validator could go in a later release, but we should be sure we won't need other backwards incompatible changes to implement the root validator.

Thoughts?

[koxudaxi]

It seems so good to me.

We should change this in v1 to __root__ to better match other nomenclature, eg. custom root types, where we use __root__.

I know about custom root type. But, someone might not understand the __root__ clearly.

[samuelcolvin]

agreed, documentation will need improving, but better to use one term everywhere.

I'm not wedded to the term "root" other offers considered...

[koxudaxi]

I agree.

My answer is __root__ for the title of the issue.

[dmontagu]

We should also implement at some point entire model validation

For the sake of discussion, here's a somewhat radical proposal:

1. If the list of fields passed to the validator is empty, it becomes a __root__/entire-model validator (depending on whether the model has a non-default __root__). (I see no reason to drop support for @validator('__root__'), but wouldn't be opposed to it for simplicity's sake.)
2. The loc field of ErrorWrapper is changed from typically containing {field.name} to typically containing{Model.Config.title or Model.__name__}.{field.name}.
   • I recognize that right now, validation happens inside the Field, which is not aware of the containing model. I think this could be addressed by the existence of a function/method that returns a modified ErrorWrapper where loc includes the name of the model.
3. For __root__ or entire-model validation, drop the .{field.name} from loc.

Technical implementation challenges aside, I think this might be a good way to achieve a unified interface for specifying whole-model and __root__ validators, and for achieving consistent error labeling.

I'll open a separate issue to discuss the implications of adding the model name to ErrorWrapper, but, any thoughts on this in the context of handling root errors?

[samuelcolvin]

So you're basically suggesting prefixing loc with the model name?

The problem is that very often (in few types of case, but the large majority of cases) we're simply doing something like:

class LoginModel:
    email: EmailStr
    password: constr(max_length=100)

def login_view(request):
  m = LoginModel(**request.json())
  ...

The user (or frontend developer) has never heard of LoginModel, so an error at loc: ['LoginModel', 'email'] is a lot more confusing than at loc: ['email'].

We could just use the model name instead of __root__ for those errors?

[samuelcolvin]

I know that in theory loc is designed to be processed by the middleware of using package and used to generate the final error format, but I for one quite often end up using it directly.

[dmontagu]

@samuelcolvin I was coming from the context of FastAPI, and was imagining that the model name is externally available through the OpenAPI spec. But maybe that is a big assumption (especially if you want validation errors but don't want a public OpenAPI spec). I guess it would be nice if there were a config setting for include_model_name_in_error_loc (or something less verbose 😅). That would make it possible to optionally incorporate the change without many changes to code, and without needing to worry about causing conflicts with frameworks using pydantic (like FastAPI).

Either way, I think __root__ would be similarly confusing externally. But it would have the advantage of leaking less implementation information if you wanted to avoid that.

[samuelcolvin]

I agree __root__ isn't much better. But at least it won't get added to the majority of errors which have a field.

What do others think?

Also what do other libraries do? Django (and presumably therefore DRF) uses __all__ which is no clearer than __root__.

[dmontagu]

I've thought this through some more, and given ValidationError tracebacks now include the model name, I think it makes sense to just use __root__ everywhere (and prefer this to __all__). For the sake of debugging, I think it's fine to require access to the tracebacks to determine the model name. I'll take a shot at implementing.

[dmontagu]

@samuelcolvin I tried taking a shot at this, but I think I got in over my head. Validation currently always happens in a field, and I couldn't find a way to add "root" validation for non-custom-root models without substantial and/or very-likely-controversial changes. Given the amount of changes that it seemed like I'd have to make, (not to mention the effort required to get it to actually work even if I was willing to make large changes), I'm going to leave this to you for now.

(If you have an approach in mind that you think should work, I would also be happy to put in some renewed effort given more guidance.)