Address the parameter validation use-case
Closed this issue · 14 comments
When I went looking for proposed JSON error response standards I was hoping to find one that addressed the parameter validation use-case. I've still not found one, which surprises me as it seems like a common use-case:
The server gets a request with various parameters in the url and/or the body (eg as form fields), validates them, finds problems, returns an error to the client.
What I'm looking for is a well defined way for the client to be able to tell which parameters have validation errors and what that those errors are.
A typical use-case would be a web form, submitted via javascript, where you'd want the individual fields that have errors to be highlighted and annotated with the corresponding error message describing the problem with the submitted value in that field.
This sounds like a collection of errors. Now that the error spec is compatible with HAL (and we can do a collection of errors as embedded resources in an error collection object). This would look something like:
{
"_embedded": {
"errors": [
{
"message": "\"username\" field validation failed",
"logref": 50,
"_links": {
"self": {
"href": ""
},
"help": {
"href": "http://.../"
},
"describes": {
"href": "http://.../"
}
}
},
{
"message": "\"postcode\" field validation failed",
"logref": 55,
"_links": {
"self": {
"href": ""
},
"help": {
"href": "http://.../"
},
"describes": {
"href": "http://.../"
}
}
}
]
}
}
This example does not bind back to the field name though. How does the client highlight in red or mark the fields that failed validation so the user can fix them?
This also means the client must expect a single error or a collection of errors everytime it sends a POST request with json to the server.
I agree with the concerns raised here. I think there should be something to refer to a certain parameter so errors can be interpreted by the client so something like error highlighting is possible.
What do you think, @blongden?
One inspiration for that could be the way it is handled by JSON+API: It has a path attribute which is "the relative path to the relevant attribute within the associated resource(s)".
I'm not sure I understand quite what is means by the relative path to the relevant attribute within the associated resource. Would that be JSONPath to point to an attribute in a related resource? It could be...
We also don't have a way of representing a link to the resource that generated the error which you would need for the JSONPath to be relevant.
I do agree that this would be useful...
Oh - of course... this would be JSONPath for json and XPath for xml... which is a little tricky.
So as an example...
{
"logref": 42,
"message": "Validation failed",
"path": "$.username",
"_links": {
"affects": {
"href": "http://path.to/user/resource/1",
"title": "Resource affected"
}
}
}Rather than a new 'affects' link relation - IANA has one defined - 'about' which may fit the bill
@blongden Thanks for addressing this 👍
Proposal:
This sounds very reasonable to me! JSON API chose to go with a simpler notation than JSONPath:
Each key is a dot-separated path that points at a repeated relationship. Paths start with a particular resource type and can traverse related resources. For example "posts.comments" points at the "comments" relationship in each resource of type "posts".
But I also like your JSONPath idea, because it has more flexibility.
Relation:
I think the about relation is a good fit for this!
Additional remark:
I think that the returned document should be an array of objects of the form described by you. Imagine that you would have multiple validation errors: In this case the server would need to select one of them and then present the next one. Or am I missing something?
I need to be more verbose about the possibility of expressing multiple errors as a Hal collection. It keeps coming up.
Related to this specific issue though - JSON Pointer appears to have an actual RFC (http://tools.ietf.org/html/rfc6901) and a very similar syntax to XPath. I'll stipulate the use of JSON Pointer for now and we can debate the merits of one vs another at a later date :)
HAL Collection:
Could you ellaborate on that? Could not find anything about collections in HAL neither in the IETF draft nor in the Spec.md. If this is possible, that's great (for both vnd.error and HAL 😉)! 👍
JSON Pointer:
That looks really good!
Yes indeed. I guess the difference is if the resource is a collection vs if it is a error in its own right. Collection - multiple errors are being returns. Error? nested errors are being returned. Nice and flexible.