Skip to content

5.0 - The More Meta The Merrier
Compare
Choose a tag to compare
@mattpolzin mattpolzin released this 26 Sep 20:21
5.0.0
c645c73
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

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>
Assets 2
Loading