Allow JSON LD to be used with JSON API #995
Conversation
|
👍 |
|
|
||
| When a JSON API document is [served as JSON-LD](http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld), | ||
| the document **MAY** include member names that begin with an at sign | ||
| (U+0040 COMMERCIAL AT, "@") to convey JSON-LD information. JSON API processers |
There was a problem hiding this comment.
JSON API processers that don't understand JSON-LD MUST ignore these members.
This seems redundant?
There was a problem hiding this comment.
By that I mean to say yes, this allows JSON-LD to be used, but we don't need to be prescriptive if people want to use it for something else.
There was a problem hiding this comment.
Re the new MUST, yes, it is redundant, in the sense that it's the logical consequence of the existing requirement that "Client and server implementations MUST ignore members not recognized by this specification.")
Re not being prescriptive, I'm not sure I follow... are you saying people should be able to use @-prefixed members for non-JSON LD data?
There was a problem hiding this comment.
+1 to what @tkellen said. What are the downsides of simply adding "@" to the set of allowed characters?
There was a problem hiding this comment.
So, allowing "@" as a first character everywhere is "neater", in that it doesn't create a special case just for JSON LD. My thinking for writing it this way, though, was:
- It preserves the ability for us to use "@" in, e.g., a future query parameter's syntax.
- Using an "@"-prefixed key for non-JSON LD data is a bad idea, because it means that if JSON LD adds a key of the same name in the future, your use may cause problems. This narrower allowance takes away that footgun.
- It prevents "@" signs from creeping in to attribute, relationship, and other names, which we may not want for aesthetic reasons (seeing how much we've done to keep prefixes out), and which could be confusing to readers trying to distinguish JSON API data from JSON LD data.
|
Thanks for writing this up, @ethanresnick. Explicitly calling out JSON-LD has a couple effects: We should ensure that both A + B are desirable. And we should decide if we want B to be made more explicit, since it's a pretty big exception we'd be carving out for JSON-LD. |
|
@dgeb See my other note about part A. I could be probably persuaded either way on that. Re part B... I don't think JSON LD integration will be workable if we restrict where in the document the JSON LD data can occur. JSON LD's syntax just isn't expressive enough to effectively annotate a JSON API document unless its able to put those annotations pretty close to the data its referring to. See here to get a sense of what I'm talking about. |
|
I am also very hesitant to add JSON-LD specific features into the spec, but a generic thing that allowed it to work better with JSON-LD is okay. |
|
I'm a bit nervous about the implications of allowing All things considered, I think that I favor a more general exception. |
|
@steveklabnik @dgeb Can you talk more about your hesitancy to make a JSON-LD specific exception? Is it that it seems too ugly? Or that it'll be confusing? To me, a narrow exceptions seems like the more cautious approach, in that we can always loosen the restrictions later to allow |
|
I do not want the spec to look like it's recommending JSON-LD, because I don't think that JSON-LD is a good way to build APIs. This is entirely a personal opinion, and I don't want to block people who do enjoy it to use it. But I am afraid that a "And do this to work with JSON-LD" in the spec is an endorsement that may lead people astray. |
Is there a way to both 1) have narrow-tailoring of the exception and 2) make it clear that we're not making an endorsement? Maybe by changing how we word the rule or the text around it? |
|
Here's another possibility for the wording. It aims to narrowly-tailor the exception without mentioning JSON-LD specifically in the normative text:
Thoughts? |
|
@steveklabnik @tkellen @dgeb Have you had a chance to look at my revised proposal for the wording above? I think it'd be awesome if we could discuss that today and tomorrow and have this issue settled before Wednesday's meeting, so we can move on to other things. @bintoro Feel free to chime in to if you have any ideas. |
|
I think it's better, for sure. |
|
@steveklabnik Anything you'd change? |
|
@ethanresnick I think your revision above strikes a better balance by mentioning JSON-LD non-normatively. My main concern is that the "member names" section describes members that are in user-space, like fields. And this is
How about:
|
|
@ethanresnick not at the moment, but I'm just trying to be cautious with my wording because I am extremely jetlagged. It reads just fine to me now, but what about once my brain is out of this fog? |
|
@dgeb When you say:
are you imagining that this exception would allow users to define @ members only in the spaces where they can't define members otherwise? Or were you imagining that @ members could go both in that space and in the space that users can already add (non @)-members to? I think I was imagining the latter, for the reason I alluded to earlier, namely: that JSON LD integration may not be possible if users are limited in where they can put their @ members. I see problems (contradictions and potential ambiguities) with my proposed wording either way, but before resolving those I want to make sure we're on the same page conceptually about the exception's scope. @steveklabnik Fair enough! |
|
I'm strongly in favor of allowing |
|
Ok, I can accept allowing |
👍
Agreed! I'm going to take a stab at rewriting it this weekend. |
6594b05 to
d7e0d32
Compare
|
@tkellen @dgeb @steveklabnik Can ya'll take a look at this before our meeting so we can try to get this merged today? |
| treat them as JSON API data). | ||
|
|
||
| Moreover, the existence of @-Members **MUST** be ignored when interpreting all | ||
| JSON:API definitions and processing instructions given outside of this |
There was a problem hiding this comment.
"JSON:API" => "JSON API" (until we perform a global swap of the terms).
|
👍 LGTM except that minor nit. Thanks for your patience here @ethanresnick |
|
👍 |
This is primarily intended to allow JSON API to be used in conjunction with JSON-LD.
d7e0d32 to
7578c01
Compare
|
Awesome! Updated with that change, and to add the new content to the normative statements file. |
|
Great! Thanks for seeing this through @ethanresnick |
This change was originally part of the profile extensions PR, because I've long seen allowing JSON LD data as a key requirement for the extension system's design. However, I'm breaking this change out into a separate PR, per @dgeb's suggestion, to make it more visible and invite any discussion on it particularly.