That's so (not) meta

What's Changed

• Allow optional metadata to be omitted as well as nulled out (#116)

Full Changelog: 5.3.0...5.3.1

Include15 support

Add support for including 15 different types of resources on one document.

Include14 support

Support for 14 includes on one document.

New Include12 and Include13 types

Adds the ability to work with 12 or 13 include types on a single document.

Loosen Poly requirement in Podspec

The Cocoapods spec file was unnecessarily restricting the Poly dependency to patch version bumps instead of minor version bumps. This release simply loosens that requirement.

Fix compilation under Swift 5.4 pre-release (Xcode 12.5 betas)

This minor change with no source compatibility ramifications fixes compilation under the newest version of Swift's compiler.

5.0 - The More Meta The Merrier

See the release candidate notes for more information on the following: https://github.com/mattpolzin/JSONAPI/releases/tag/5.0.0-rc.1

Features & Improvements

Better error reporting

When there is a failure to decode includes in a JSON:API document, version 5 will give you a much more concise error message. Where before it would always tell you all the possible ways the include might have failed to decode, it will now attempt to determine which failure is relevant using a couple of simple heuristics about very common cases.

If an include does not have a JSON:API type matching any of the types allowed to be included, the error will just tell you what type it found and what types it was looking for.

If an include that failed to decode matches one of the expected JSON:API types, the error will report specifically the reason why that type of resource could not be decoded.

Resource Identifier Object metadata

Previously, you could decode metadata that was found in the Relationship Object but not metadata that was found in the Resource Identifier Object nested within a Relationship Object. This gap in what the JSONAPI library can express has been fixed. See the release candidate notes or the JSON:API specification for more information on the distinction.

You can see more on using this new metadata location in this library's relationship metadata documentation.

⚠️ 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<T: JSONAPIIdentifiable> = JSONAPI.ToOneRelationship<T, NoIdMetadata, NoMetadata, NoLinks>
typealias ToMany<T: JSONAPI.Relatable> = JSONAPI.ToManyRelationship<T,NoIdMetadata, NoMetadata, NoLinks>

Version 5.0.0 Release Candidate 1

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!

Version 4.0.0 Stable Release

Additions & Fixes

Release 4.0.0 has changed in the following ways since version 3.x. The following list includes changes for all 4.0.0 alpha and release candidates. There are no functional changes between the latest release candidate and this stable release.

➕ ResourceObject is now Hashable when it is not Unidentified.
➕ ResourceObject now conforms to Swift.Identifiable when it is not Unidentified.
➕ CompoundResource and new Document initializers make document creation more ergonomic.
➕ Modify Document.SuccessDocument to guarantee non-optional properties where appropriate.
➕ SucceedableJSONAPIDocument and FailableJSONAPIDocument improve generic abstraction story.
➕ MetaRelationship added for relationships with only links and metadata.
🐞 Fix/Improve errors during decoding caused by malformed ResourceObject relationships.

Breaking Changes

⚠️ Bump minimum Swift version to 5.2
📛 Renames Identifiable to JSONAPIIdentifiable to avoid confusion and conflict with Swift.Identifiable.
📛 Renames JSONAPIIdentifiable's Identifier associated type to ID to match that of the Swift Identifiable type.
🗑 Remove deprecated subscript access to ResourceObject attributes.

Suggested approach to migrating code:

• Find JSONAPI.Identifiable or Identifiable (careful not to pick up any uses of Swift Identifiable in your codebase) and replace with JSONAPIIdentifiable.
• Anywhere you are using Identifier() in the context of a ResourceObject to construct its ID, replace with ID().
• Anywhere you are using subscript access on ResourceObject to access an attribute, switch to using dynamic member access (i.e. widget[\.cog] changes to widget.cog`).

Bugfix for typealias/associatedtype conflict.

One protocol's typealias will collide with another protocol's associatedtype in very ugly ways. This is why for now we will have ResourceObject.ID and ResourceObject.Id (both equally valid ways of referring to a ResourceObject's Identifying type.