Validator docs are silent on when validators run and implications to developers [DATAREST-789]

Marc Zampetti opened DATAREST-789 and commented

In the SDR docs, the section on Validators and Events is silent on when the various events/validations fire to an extent. There is docs about the various types of events, but it is not clear specifically when those events are fired in the overall lifecycle.

This can lead to confusion for developers, especially in the case of the BeforeSave() event. For example, when writing a BeforeSave validator that inspects the input Object, in the case of a PATCH request that is given a partial object, the Validator is run against the input object, and NOT the merged object. But the docs don't make that clear, and so its reasonable that a developer might assume the validation is run later. This can lead to problems since the validator might be trying to enforce validation rules that are not valid in the case of a partial object.

The docs should be updated to be more clear about when the event fires, and on what type of object the various events are applied against

Affects: 2.3.2 (Fowler SR2), 2.4.2 (Gosling SR2), 2.4.4 (Gosling SR4), 2.5 RC1 (Hopper)