clarify some details regarding error objects #1525
Conversation
freddrake
commented
Dec 1, 2020
freddrake
commented
- fixes Question about members of error objects #1496
- in json:api 1.1 error objects:
- require at least one member be set
- clarify that links, if provided, is not required to have BOTH about & type
- strengthen status member with a SHOULD
_format/1.1/index.md
Outdated
| * `id`: a unique identifier for this particular occurrence of the problem. | ||
| * `links`: a [links object][links] containing the following members: | ||
| * `links`: a [links object][links] that **MAY** contain the following members, | ||
| and that **MUST** contain at least one of: |
There was a problem hiding this comment.
I discussed this with @gabesullice and we're both uncomfortable including this MUST requirement here. Throughout the spec, links objects do not have any particular required members. It seems plausible that custom links could be included here without requiring about or type in addition.
There was a problem hiding this comment.
It would be great to make this more explicit. I always felt uncomfortable using custom link names in error objects because it was the only place where a links object had documented members. Maybe we can add something like 'may contain any member with the following members having a specified meaning'?
There was a problem hiding this comment.
Not sure what you mean about this being the only place where a links object has documented members; do self, related, and the pagination links not count?
Regarding "custom" links, maybe that's described somewhere in 1.1, but... I'm hesitant to approach that topic since I'm still trying to bring my implementation up to snuff for 1.0.
There was a problem hiding this comment.
@gabesullice and I were just talking about how custom members in links objects throughout the spec are still underspecified. We'd like to rectify this prior to 1.1 but, since it's a general issue, it doesn't need to hold up this PR.
dgeb
left a comment
dgeb
left a comment
There was a problem hiding this comment.
Looks good to me now, thanks @freddrake!
@gabesullice can you please do a quick review as well?
gabesullice
left a comment
gabesullice
left a comment
There was a problem hiding this comment.
These are great clarifications, thanks for submitting this @freddrake!
|
Consider the following response: {
"errors": [
{
"description": "Some description about the error"
}
]
}This response is perfectly fine with 1.0, but is now invalid in 1.1 because of the new requirement. In my opinion, this is a breaking change that belongs to version 2.0 instead of 1.1. I propose that 1.1 should use |
This reverts commit c28e2a1. See json-api/json-api#1525 (comment)
|
@Art4 Your example document was invalid for v1.0 as well. A |
|
@jelhan Unknown/undefined properties must be ignored, but are not prohibited. This would be against the "never remove, only add" strategy. To quote the spec: https://jsonapi.org/format/1.0/#status
It is possible that a But to stay on topic, one can also imagine the following response: {
"errors": [
{}
]
} |
7 participants
