Json-api: Feedback requested re: v1.1

[dgeb]

On behalf of the spec editors, I'd like to solicit general feedback on the v1.1 release candidate to understand how things are going in the community.

We are currently in an awkward state, unable to finalize v1.1 due to the caveat described in the status section:

This version is expected to be finalized and released on January 31, 2019 (provided there are two compliant implementations by that date; if not the release will wait until such implementations exist to prove its viability).

It's inarguably a bad sign that we're now more than five months past this date without yet being aware of multiple compliant server and client implementations of the v1.1 RC. Now it's possible that we're simply out of the loop, and v1.1 has been fully implemented by several libraries that we (the editors) don't happen to be using. However, it's also possible that the new-to-1.1 profiles feature has proven too onerous, impractical, or undesirable to be implemented widely (and this is of course the precise reason that we added that caveat in the first place).

With that in mind, we're reaching out with a few questions to JSON:API implementors:

• Have you attempted to implement any part of v1.1? If so, what part?
• Which parts of v1.1 do you find useful?
• Which parts of v1.1 do you not find useful?
• Have any parts of v1.1 proven to be too onerous or impractical to implement?

For reference, the major deltas introduced in 1.1 are listed in the update history section of the home page and copied below:

• New features include: profiles, "@-Members", and error object type links.
• There are editorial clarifications around: query parameters (their parsing/serialization, and reserved parameter names), the appropriate status code for specific responses, and the presence of the included key even when its value is an empty array.
• JSON:API switched to recommending camelCased names.

Please feel free to speak openly in comments below. We are trying to revitalize the spec and push forward on some much needed initiatives. However, we're also willing to re-examine and change some aspects of v1.1 first, because it has definitely become a blocker.

Thanks for any feedback you can provide.

[lode]

Thanks for the call!

Have you attempted to implement any part of v1.1? If so, what part?

I've added full v1.1 support in https://github.com/lode/jsonapi (see https://github.com/json-api/json-api/pull/1377), which is a server implementation. Next to allowing any custom profile, I've also added an implementation of the Cursor Pagination profile.

Good to know, my library doesn't _yet_ offer any parsing or assistance for handling the request. It is up to the user (of the library) to handle the request and direct the library. So any tricky things in handling query parameters or profile media type isn't something I bumped into. The library currently only handles the output, so for example profile links and content-types are handled.

Which parts of v1.1 do you find useful?

The type links are good to have. And I like the possibilities of profiles, although I think it would be good if there's a way for profiles to allow things that the spec doesn't. As the profiles anyway have to be announced & negociated, it allows for more experimentation.

Also, although minor maybe, I like the camelCase recommendation.

Which parts of v1.1 do you not find useful?

The @-members. For me it feels like a weird addition to the spec.

Have any parts of v1.1 proven to be too onerous or impractical to implement?

Again the @-members. See also the discussion https://github.com/json-api/json-api/issues/1367. Without them the spec is very clear in what is allowed where. There is a certain structure and semantics to it. The @-members skip all of that and being allowed everywhere is actually more hard to implement than being allowed in specific places.

I have implemented them, but as I don't use it, and the spec is very broad, I'm unsure if they work as expected or are useful.

Hope this helps.

[remmeier]

from the www.crnk.io perspective we already follow the parameterization and camcelCase recommendations. The profile implementation we can take on our roadmap for version 3.1. So it should manifest in the coming 4-6 weeks. It has not yet been an overly interesting target as of yet. Nothing wrong with the specification, but I think the real value will only manifest when there are also concrete profile specifications in the various areas. I could imagine meta modelling, filtering, nested filtering, full-text search, facetted search, bulk operations/sideloading, maybe an optional slightly simplified response structure (directly inlined inclusions, no "attributes" and "relationship" wrappers to make it a bit more approachable/look-alike to regular APIs). In various areas we already have stuff not backed by any specification and would love to not having to do that anymore.

given that GraphQL gets plenty of love currently, some alignment with that might also be worthwhile.

[jugaadi]

The profiles feature was first proposed on April 15, 2018 before being finalized on September 18, 2018. We have waited six months(or ten months post finalization) for implementation feedback. This reflects a lot on the focus given to our community. However, I would humbly request the authors to go ahead with the v1.1 release(including the profiles feature) without further delay.

The entire community is excited for v1.2 and have been waiting for the LocalID, Operations, Sideposting, etc features for more than a year. Any further delays in enhancing JSON:API spec would push people to alternatives thereby, further shrinking the community.

[lindyhopchris]

I just want to add to what @jugaadi said above... I run a Laravel JSON API package.

I love JSON API but have been worried about the stagnation. Profiles etc look great, but they don't really help me with any of the issues that get raised in my package. Features or issues that will be solved by operations are constantly requested. So really, I'm waiting for 1.2, not 1.1.

The community focused approach is really commendable, but I strongly feel it's time we move on to 1.2!

[dgeb]

Thanks to everyone who replied with feedback. Kudos to @lode for implementing the cursor pagination profile in https://github.com/lode/jsonapi as well as some other aspects of 1.1. And thanks to @remmeier for moving crnk.io to the new recommendations as well as committing to some future support for profiles. Last but not least, thanks to @jugaadi and @lindyhopchris for encouraging us to move the spec forward as quickly as possible. I agree that the current pace is unacceptable.

Based on the relatively low amount of feedback here, and the anecdotal evidence I've heard firsthand, it's become clear that many implementors consider that profiles, as currently spec'd, are either too onerous to support fully and/or not worth the effort to support. Some aspects, such as member aliasing, don't appear to have any implementations yet, and so we're planning to remove them from the spec. @gabesullice has begun some simplification work in #1410.

Another thing that has become obvious from discussions about profiles, and even concrete proposals for profiles, is that we've done a poor job communicating the intended limitations of profiles. Profiles are introduced in this way:

JSON:API supports the use of “profiles” as a way to indicate additional semantics that apply to a JSON:API request/document, without altering the basic semantics described in this specification.

The second part of that phrase ("without altering the basic semantics described in this specification") is often missed. Perhaps a clearer way of saying this is that profiles must describe behavior that is completely _conformant_ to the base spec. Profiles are intended to describe _how_ the spec is used, but not extend the allowed usages. If profiles were allowed to introduce a top-level member in the document, say operations for instance, then the spec itself could never introduce that same member. Forward progress on the spec would effectively stop if profiles had this kind of unlimited power.

With that said, there is incredible pressure built up over years to allow for new capabilities to be added to the spec. I feel this strongly myself, having authored both the proposals for local identifiers and operations. Both of these proposals have been queued up for over a year as we have waited for profiles and v1.1 to be completed and proven with implementations.

In hindsight, I can now say that it was probably a mistake to introduce profiles in their current form in the order they have been introduced. We need to unlock forward progress without compromising the spec long term.

I've been meeting weekly with @gabesullice now to regain momentum. Our plans include:

A) Remove the release candidate status from v1.1.
B) Simplify the spec's requirements around profiles.
C) Consider extending the scope of v1.1 to include support for schemas and extensions such as bulk, identifiers, and operations.

Obviously point C sounds extensive and will need to be spelled out in more detail as we arrive at a proposal. However, we are considering including new capabilities in v1.1 because it seems that, otherwise, profiles will continue to be misunderstood and play a much larger role than originally intended. Furthermore, since we're going to require a new release candidate for v1.1, we have the opportunity to reconsider what's included.

Thanks for everyone's continued support. We'll try to move forward as quickly, and as publicly, as possible. Please stay tuned ...

[gabrielgrant]

Very much appreciate you diving back into moving this forward ~@gdeb~ @dgeb and @gabesullice

Might it make sense to update the homepage and status page to reflect the update you posted above? (including, perhaps, linking to your update comment. Or, at the very least, removing the "expected to be finalized and released on January 31, 2019")

[dgeb]

@gabrielgrant yes, I will update that right away. Thanks for the reminder.

[gdeb]

hi @dgeb, I am @gdeb, and it took me a while to understand why I was pinged...

[jugaadi]

The update history and upcoming version spec too needs to be updated.

[tobyzerner]

@dgeb Thanks for the update! Would it be possible to get minutes from these weekly meetings (even very brief) posted in https://discuss.jsonapi.org/c/meeting-minutes, or something similar? I am excited to see progress – please let me know if there's anything I can do to help.

[jugaadi]

Any updates?

[dgeb]

Any updates?

@jugaadi et al - I've just posted a proposal for a change in direction for v1.1 in #1435

[dgeb]

I am excited to see progress – please let me know if there's anything I can do to help.

@tobyzerner thank you for your offer, and apologies for taking so long to reply. I will discuss your offer with the other editors (@gabesullice + @wycats) and see what they think. I definitely want to be more open about decision-making and get as much community buy-in and feedback as possible as we move towards finalizing v1.1.

[jugaadi]

Any updates?

[UkonnRa]

Hi, so any updates? Can JSON:API official conclude the diff between v1.1 and v1 when finialize the v1.1 spec?

[dgeb]

Closing now that v1.1 RC3 has been released with all the planned updates discussed here. At this point we're just making fine tweaks and waiting for a couple initial implementations to be finished.