Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Achieve compatability with JSON:API 1.1 #90

Open
Art4 opened this issue Nov 28, 2023 · 1 comment · May be fixed by #96
Open

Achieve compatability with JSON:API 1.1 #90

Art4 opened this issue Nov 28, 2023 · 1 comment · May be fixed by #96
Labels
enhancement help wanted JSON:API spec
Milestone
1.4.0

Comments

@Art4
Copy link
Owner

Art4 commented Nov 28, 2023

See #83 and #89
@Art4 Art4 added this to the 1.3.0 milestone Nov 28, 2023
@Art4 Art4 linked a pull request Jul 19, 2024 that will close this issue
Draft
11 tasks
@Art4 Art4 linked a pull request Jul 19, 2024 that will close this issue
Achieve compatability with JSON:API 1.1 #96
Draft
11 tasks
@Art4
Copy link
Owner Author

Art4 commented Jul 22, 2024

Backward incompatibilities between 1.0 and 1.1

BC for JSON-API is defined in section 1 of the spec:

1.) Status

This page presents an archived copy of JSON:API version 1.0. None of the normative text on this page will change. While 1.0 is no longer the latest version of JSON:API, new versions will remain compatible with this one, as JSON:API uses a never remove, only add strategy.

Even if these two sentences seem to be mutually exclusive see this comment:

In the schema world, those two statements are mutually exclusive.

I get that, so I understand why they seem odd. But, in the protocol design world, this apparent "contradiction" is actually a logical prerequisite for extensibility. Please take a look at this great article if you have a second. Basically, it proves that you need to make the set of legally-producable messages smaller than the set of legally consumable messages (which is what additionalProperties: true does) if you want protocol extensibility. So this decision isn't some arbitrary quirk of the spec text or esoteric schema point: it's a critical part of the design!

There seems to be some BC breaks between 1.0 and 1.1. I will document them here so we can report them back and eventually find a way to handle them.

Allow extension member to be the only member in top-level document

PRs: json-api/json-api#1642

Changes between 1.0 and 1.1 (simplified)

  ### <a href="#document-top-level" id="document-top-level" class="headerlink"></a> Top Level

  A JSON object **MUST** be at the root of every JSON:API request and response
  document containing data. This object defines a document's "top level".

  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](#extensions).

Problem

The following content is valid 1.1, but is backward incompatible with 1.0 because data, errors and meta are missing:

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!"
      }
    }
  }]
}

Allow extension member to be the only member in relationship object

PRs: json-api/json-api#1644

Changes between 1.0 and 1.1 (simplified)

  ##### <a href="#document-resource-object-relationships" id="document-resource-object-relationships" class="headerlink"></a> Relationships

  The value of the `relationships` key **MUST** be an object (a "relationships
  object"). Each member of a relationships object ("relationships") represents
  a "relationship" from the [resource object][resource objects]
  in which it has been defined to other resource objects.

  Relationships may be to-one or to-many.

  A relationship's name is given by its key. The value at that key **MUST** be an
  object ("relationship object").

  <a id="document-resource-object-relationships-relationship-object"></a>
  A "relationship object" **MUST** contain at least one of the following:

  * `links`: a [links object][links] containing at least one of the following:
    * `self`: a link for the relationship itself (a "relationship link"). This
      link allows the client to directly manipulate the relationship. For example,
      removing an `author` through an `article`'s relationship URL would disconnect
      the person from the `article` without deleting the `people` resource itself.
      When fetched successfully, this link returns the [linkage][resource linkage]
      for the related resources as its primary data.
      (See [Fetching Relationships](#fetching-relationships).)
    * `related`: a [related resource link]
    * a member defined by an applied [extension](#extensions).
  * `data`: [resource linkage]
  * `meta`: a [meta object][meta] that contains non-standard meta-information about the
    relationship.
+ * a member defined by an applied [extension](#extensions).

Problem

The following content is valid 1.1, but is backward incompatible with 1.0 because links, data and meta are missing:

POST /articles HTTP/1.1
Host: example.org
Content-Type: application/vnd.api+json;ext="https://example.org/ext/example"
Accept: application/vnd.api+json;ext="https://example.org/ext/example"

{
  "data": {
    "type": "articles",
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    },
    "relationships": [
      {
        "example:color": {
          "name": "red",
        }
      }
    ]
  }
}

Allow extension member to be the only member in relationship links object

PRs: json-api/json-api#1644

Changes between 1.0 and 1.1 (simplified)

  ##### <a href="#document-resource-object-relationships" id="document-resource-object-relationships" class="headerlink"></a> Relationships

  The value of the `relationships` key **MUST** be an object (a "relationships
  object"). Each member of a relationships object ("relationships") represents
  a "relationship" from the [resource object][resource objects]
  in which it has been defined to other resource objects.

  Relationships may be to-one or to-many.

  A relationship's name is given by its key. The value at that key **MUST** be an
  object ("relationship object").

  <a id="document-resource-object-relationships-relationship-object"></a>
  A "relationship object" **MUST** contain at least one of the following:

  * `links`: a [links object][links] containing at least one of the following:
    * `self`: a link for the relationship itself (a "relationship link"). This
      link allows the client to directly manipulate the relationship. For example,
      removing an `author` through an `article`'s relationship URL would disconnect
      the person from the `article` without deleting the `people` resource itself.
      When fetched successfully, this link returns the [linkage][resource linkage]
      for the related resources as its primary data.
      (See [Fetching Relationships](#fetching-relationships).)
    * `related`: a [related resource link]
+    * a member defined by an applied [extension](#extensions).
  * `data`: [resource linkage]
  * `meta`: a [meta object][meta] that contains non-standard meta-information about the
    relationship.
  * a member defined by an applied [extension](#extensions).

Problem

The following content is valid 1.1, but is backward incompatible with 1.0 because self and related are missing:

POST /articles HTTP/1.1
Host: example.org
Content-Type: application/vnd.api+json;ext="https://example.org/ext/example"
Accept: application/vnd.api+json;ext="https://example.org/ext/example"

{
  "data": {
    "type": "articles",
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    },
    "relationships": [
      {
        "links": [
          "example:link": {
            "href": "https://example.org",
          }
        ]
      }
    ]
  }
}

@Art4 Art4 modified the milestones: 1.3.0, 1.4.0 Oct 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement help wanted JSON:API spec
Projects
None yet
Milestone
1.4.0
Development

Successfully merging a pull request may close this issue.

Achieve compatability with JSON:API 1.1 Art4/json-api-client
1 participant
@Art4