See https://twitter.com/jsonapi/status/1069593631365959680 — RC1 of version 1.1 of the JSON:API spec was released — see https://jsonapi.org/format/1.1/.

Until it's final, we shouldn't switch over from 1.0 to 1.1, but we should explicitly verify that we are fully compatible with it.

Relevant tweets quoted:

  1. New 1.1 features include "profiles", which provide a means to negotiate additional semantics beyond what's covered in the base spec. Profiles could cover specific means of filtering, paginating, or versioning resources. Create and share profiles here: https://jsonapi.org/extensions/

    We have #2955020: Spec Compliance: JSON API's profile/extention (Fancy Filters, Drupal sorting, Drupal pagination, relationship arity) needs to be explicitly communicated for this.

  2. Also of note is the change in the official recommendation to use camelCase names for resource fields. This reduces the friction of composing + parsing JSON:API with JavaScript and other languages.

    We can't do this without massive disruption.

https://jsonapi.org/#update-history is likely going to be helpful.

Comments

Wim Leers created an issue. See original summary.

e0ipso’s picture

We can't do this without massive disruption.

Nor we should. This falls on the implementor's side, they should use JSON:API Extras for it.

wim leers’s picture

Nor we should. This falls on the implementor's side, they should use JSON:API Extras for it.

Completely agreed — sorry for not making that more clear :) OTOH, good to have an explicit +1 :)

wim leers’s picture

Status: Active » Needs review
StatusFileSize
new5.38 KB

Once we switch to 1.1 support, we'll need to take care of all of the following (in these points below I'm following the structure in https://jsonapi.org/#update-history):

  1. Features
    1. Profiles: https://jsonapi.org/format/1.1/#profiles#2955020: Spec Compliance: JSON API's profile/extention (Fancy Filters, Drupal sorting, Drupal pagination, relationship arity) needs to be explicitly communicated
    2. @-Members: https://jsonapi.org/format/1.1/#document-member-names-at-members — this is pure API addition, no break needed — rough patch attached
    3. error object type links: https://jsonapi.org/format/1.1/#error-objects — again pure API addition, no break — at worst this causes some duplicate links — for example the sole info URL may be repeated as one of the type URLs
  2. Editorial clarifications
    1. for query parameters: https://jsonapi.org/format/1.1/#query-parameters — we were already interpreting it this way
    2. for appropriate status codes: https://github.com/json-api/json-api/pull/1036 (for https://github.com/json-api/json-api/issues/1033) and https://github.com/json-api/json-api/pull/1029 (for https://github.com/json-api/json-api/issues/1023). The latter already works, the former not yet. Added a failing test for the former.
  3. Recommendation changes
    1. now recommending camelCase — we're not adopting that (see #2 + #3), plus it's only a recommendation anyway
wim leers’s picture

Based on #4, AFAICT JSON:API 1.1 only requires changes for:

  1. point 1.1 (Profiles), and for that we already have #2955020: Spec Compliance: JSON API's profile/extention (Fancy Filters, Drupal sorting, Drupal pagination, relationship arity) needs to be explicitly communicated — ideally we'd have a patch ready for that, proving that it is indeed possible to express our profiles using the spec
  2. point 1.2 (@-Members): to ignore such members in incoming requests — definitely no BC break there
  3. point 1.3 (error object type links): just adding more links — definitely no BC break there
  4. point 2.2.a: status code when creating relationship to non-existing resource: this WILL BE a behavior change, and should therefore in principle happen before JSON:API 2.0
  5. point 2.2.b: status code when deleting non-existing resource — just needs test coverage (#4 includes it already, and it passes)

@e0ipso and @gabesullice: I'd love to hear your thoughts on how this should impact 2.0RC3 and 2.0-stable. IMHO 2.2.a is a hard blocker for 2.0-stable, and 1.1 should be too to be safe.

Status: Needs review » Needs work

The last submitted patch, 4: 3019574-4.patch, failed testing. View results
- codesniffer_fixes.patch Interdiff of automated coding standards fixes only.

gabesullice’s picture

+1 to 1.1 and 2.2a as stable blockers. I'm ambivalent about whether they should blocking RC3 though.

I'm beginning to feel like we're abusing the RC process a bit... if we know there will be changes, can we really tag a release candidate if we know it's not really a true candidate for release? OTOH, tagged releases seem to increase testing and adoption of 2.0 which I like.

wim leers’s picture

I'm beginning to feel like we're abusing the RC process a bit...

I don't think we are. We released RC1 thinking it could be a stable release. Bugs were found. RC2 was released. Bugs were again found, and they're now all fixed. But also during RC2, https://twitter.com/jsonapi/status/1069593631365959680 happened. While that is not a bug, that does pose a risk of BC breaks post-2.0. Better to address that now rather than later.

But yes, I think we're getting distracted in the RC phase; I think several of the lately committed performance issues should not have been committed during RC (2 commits for #3014232, 1 commit for #3017239. They weren't critical. Anything non-critical should wait until after 2.0.

gabesullice’s picture

Status: Needs work » Needs review
StatusFileSize
new580 bytes
new5.04 KB

First, a simple CS fix.

Status: Needs review » Needs work

The last submitted patch, 9: 3019574-9.patch, failed testing. View results

gabesullice’s picture

Status: Needs work » Needs review
StatusFileSize
new2.85 KB
new6.47 KB

This should address 2.2a.

Status: Needs review » Needs work

The last submitted patch, 11: 3019574-11.patch, failed testing. View results

gabesullice’s picture

Status: Needs work » Needs review
StatusFileSize
new869 bytes
new6.37 KB

Essentially:

-            'via' => ['href' => 'http://jsonapi.test/jsonapi/node/camelids'],
+            'via' => ['href' => $url->setAbsolute()->toString()],

Status: Needs review » Needs work

The last submitted patch, 13: 3019574-13.patch, failed testing. View results

wim leers’s picture

Status: Needs work » Needs review
StatusFileSize
new4.61 KB
new10.58 KB

This fixes most failures.

wim leers’s picture

StatusFileSize
new3.06 KB
new7.89 KB
+++ b/src/JsonApiSpec.php
@@ -72,8 +72,8 @@ class JsonApiSpec {
-        // First character must be "globally allowed". Length must be >=1.
-        self::MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS . '{1}' .
+        // First character must be "globally allowed" or @. Length must be >=1.
+        '(' . self::MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS . '|){1}' .

+++ b/src/Normalizer/HttpExceptionNormalizer.php
@@ -94,6 +94,7 @@ class HttpExceptionNormalizer extends NormalizerBase {
+    // @todo add `type` links: https://jsonapi.org/format/1.1/#error-objects

+++ b/src/Normalizer/JsonApiDocumentTopLevelNormalizer.php
@@ -85,6 +86,7 @@ class JsonApiDocumentTopLevelNormalizer extends NormalizerBase implements Denorm
+      // @todo drop @-members

@@ -93,6 +95,7 @@ class JsonApiDocumentTopLevelNormalizer extends NormalizerBase implements Denorm
+      // @todo drop @-members

+++ b/tests/src/Unit/JsonApiSpecTest.php
@@ -42,6 +42,7 @@ class JsonApiSpecTest extends UnitTestCase {
+    $data['@-member'] = ['@kittens', TRUE];

These are for points 1.2 and 1.3 and are definitely safe to add later. Let's remove them here. That will make the patch green.

The last submitted patch, 15: 3019574-15.patch, failed testing. View results

wim leers’s picture

Issue tags: +Needs followup

IMHO #16 should get committed, then RC3 should be tagged. We'll need a Minor taskfollow-up for points 1.2 and 1.3.

+1 from @e0ipso and/or @gabesullice wanted :)

gabesullice’s picture

Title: Verify JSON:API 1.1 RC1 spec compliance » JSON:API 1.1 RC1 Spec Compliance: Creating/updating a relationship to a non-existant resource should 404
Status: Needs review » Reviewed & tested by the community

This LGTM. Committing.

gabesullice’s picture

Status: Reviewed & tested by the community » Fixed
gabesullice’s picture

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.