-
Notifications
You must be signed in to change notification settings - Fork 889
only top-level member may be defined by extension #1642
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
only top-level member may be defined by extension #1642
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for addressing this, @jelhan. I agree with this approach and the clear wording you've used. I think it just needs a link back to the extensions section.
Co-authored-by: Dan Gebhardt <dan@cerebris.com>
@jelhan I'm sorry for not following this topic earlier, but allowing extensions to define the only member in top-level document is a breaking change.
This is really the case here: A
POST /operations HTTP/1.1
Host: example.org
Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
Accept: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
{
"atomic:operations": [{
"op": "add",
"href": "/blogPosts",
"data": {
"type": "articles",
"attributes": {
"title": "JSON API paints my bikeshed!"
}
}
- }]
+ }],
+ "meta": {}
} Sure, this workaround is a bit annoying, but would keep BC with The changes in this PR should be part of |
@Art4 Content negotiation between client and server prevents that issue. A client requests that a server applies an extension via |
@jelhan Good point, thank you very much. Sadly this way version 1.0 is not forward compatible with 1.1, but at least 1.1 is backward compatible to 1.0. My mistake was that after reading e.g. this comment I assumed that JSON:API would be forward compatible. I will adjust my parser with this in mind. Thank you for your patient. |
It's forward compatible. A server implementing v1.0 handles every request to apply an extension as not supporting that specific extension. But I see that it gets problematic if a library only implements parts of the processing rules. In your case the library seems to be limited to parsing a JSON:API document. But not implementing the content negotiation. I would recommend to document in that case that it only supports JSON:API documents without any extension applied. As extensions can define additional processing rules, a JSON:API document cannot be parsed ignoring applied extensions. |
An extension may introduce it's own top-level member. E.g. the atomic operations extension defines the additional top-level members
atomic:operations
andatomic:results
.So far the specification enforced that a JSON:API document has either
data
,errors
ormeta
top-level member. Even if there is another top-level member introduced by an applied extension.This is not desirable. And it was not intended. It is likely that some implementations would ignore that requirement. Even the examples given in official atomic operations extension are ignoring it:
A
meta
top-level member with an empty object could be added to fulfill that requirement. The example payload from atomic operations extensions would be changed like the following:But there doesn't seem to be any value in doing so. Instead we should relax the constraint of the base spec to better support this use case of extensions.
I see two potential options to address the issue:
A document **MUST** contain at least one of the following top-level members: * `data`: the document's "primary data". * `errors`: an array of [error objects](#errors). * `meta`: a [meta object][meta] that contains non-standard meta-information. + * a member defined by an applied extension.
I tend toward the second approach:
data
,errors
ormeta
top-level member even if no extension is applied, could be considered a breaking change.