The markdown parsing is broken/disabled for release notes. Sorry about that, I'm chasing the source of a crash that's been bringing this website down for the last couple of days.
Include15 support
16 hours ago
Add support for including 15 different types of resources on one document.
Include14 support
20 hours ago
Support for 14 includes on one document.
New Include12 and Include13 types
1 year ago
Adds the ability to work with 12 or 13 include types on a single document.
Loosen Poly requirement in Podspec
2 years ago
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)
3 years ago
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
3 years ago
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](https://github.com/mattpolzin/JSONAPI/releases/tag/5.0.0-rc.1) or the [JSON:API specification](https://jsonapi.org/format/#document-resource-object-relationships) for more information on the distinction.
You can see more on using this new metadata location in this library's [relationship metadata documentation](https://github.com/mattpolzin/JSONAPI/blob/5.0.0-rc.1/documentation/usage.md#relationship-metadata).
### β οΈ 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.
```swift
// 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:
```swift
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
3 years ago
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:
```json
{
"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):
```json
{
"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.
```swift
// 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:
```swift
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](https://github.com/mattpolzin/JSONAPI/blob/release/v5/documentation/usage.md#relationship-metadata) for information on getting at that metadata!
Version 4.0.0 Stable Release
3 years ago
### 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.
3 years ago
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.
Bugfix for ResourceObjectProxy
3 years ago
Attempt to fix a bug that only shows up in edge cases where `ResourceObjectProxy.ID` is used directly and must be equal to `ResourceObject.ID`.