Skip to content

Version 5.0.0 Release Candidate 1

Pre-release
Pre-release
Compare
Choose a tag to compare
@mattpolzin mattpolzin released this 22 Sep 03:52
5.0.0-rc.1
cc57a60

This version has drastically clearer error reporting around failures to decode includes in a JSON:API document (thanks @mlomeli for the help in designing a better experience).

This version also adds support for metadata within Resource Identifier Objects. You were already able to represent metadata in Relationship Objects, but now metadata support for relationships should be complete.

The difference is subtle. Here's metadata in the Relationship Object:

{
  "data": {
    "type": "people",
    "id": "88223",
    "attributes": {
      ...
    },
    "relationships": {
      "pet": {
        "data": {
          "type": "dogs",
          "id": "123"
        },
        "meta": {
          "nickname": "Sparks"
        }
      }
    }
  }
}

Here's metadata in the Resource Identifier Object (look for it one level deeper next to the id/type of the related resource):

{
  "data": {
    "type": "people",
    "id": "88223",
    "attributes": {
      ...
    },
    "relationships": {
      "pet": {
        "data": {
          "type": "dogs",
          "id": "123",
          "meta": {
            "nickname": "Sparks"
          }
        }
      }
    }
  }
}

In order to support this new metadata location, the following breaking change was made.

⚠️ Breaking Changes ⚠️
ToOneRelationship and ToManyRelationship both gained an additional generic type parameter named IdMetaType. This means that any code that uses them directly or typealiases them will need to be updated.

// before
ToOneRelationship<Identifiable: JSONAPI.JSONAPIIdentifiable, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>

// after
ToOneRelationship<Identifiable: JSONAPI.JSONAPIIdentifiable, IdMetaType: JSONAPI.Meta, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>

//before
ToManyRelationship<Relatable: JSONAPI.Relatable, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>

//after
ToManyRelationship<Relatable: JSONAPI.Relatable, IdMetaType: JSONAPI.Meta, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>

if you don't need to take advantage of this new metadata location, you can do away with it just like with any other option your relationship does not need. Here are two examples of typealiases that do away with all of the various auxiliary information:

typealias ToOne<R> = ToOneRelationship<R, NoIdMetadata, NoMetadata, NoLinks>
typealias ToMany<R> = ToManyRelationship<R, NoIdMetadata, NoMetadata, NoLinks>

If you do need to use the new metadata location, it is really just JSONAPI.Meta like any other metadata -- that is, it really just needs to be Codable and Equatable.

if you've got a resource with a relationship containing metadata inside the Resource Identifier Object, see the new documentation for information on getting at that metadata!

Assets 2
Loading