Update example indentation

Beta/3x

JSONAPI.playground/Pages/Full Client & Server Example.xcplaygroundpage/Contents.swift

@@ -37,7 +37,7 @@ typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Ent
 // JSON:API Documents for this particular API to have Metadata, Links,
 // useful Errors, or an APIDescription (The *SPEC* calls this
 // "API Description" the "JSON:API Object").
-typealias Document<PrimaryResourceBody: JSONAPI.ResourceBody, IncludeType: JSONAPI.Include> = JSONAPI.Document<PrimaryResourceBody, NoMetadata, NoLinks, IncludeType, NoAPIDescription, BasicJSONAPIError<String>>
+typealias Document<PrimaryResourceBody: JSONAPI.CodableResourceBody, IncludeType: JSONAPI.Include> = JSONAPI.Document<PrimaryResourceBody, NoMetadata, NoLinks, IncludeType, NoAPIDescription, BasicJSONAPIError<String>>
 
 // MARK: Entity Definitions
 

JSONAPI.playground/Pages/PATCHing.xcplaygroundpage/Contents.swift

@@ -0,0 +1,124 @@
+//: [Previous](@previous)
+
+import Foundation
+import JSONAPI
+
+/*******
+
+ Please enjoy these examples, but allow me the forced casting and the lack of error checking for the sake of brevity.
+
+ This playground focuses on receiving a resource, making some changes, and then creating a request body for a PATCH request.
+ As with all examples in these playround pages, no actual networking code will be provided.
+
+ ********/
+
+// Mock up a server response
+let mockDogData = """
+{
+    "data": {
+        "id": "1234",
+        "type": "dogs",
+        "attributes": {
+            "name": "Sparky"
+        },
+        "relationships": {
+            "owner": {
+                "data": null
+            }
+        }
+    }
+}
+""".data(using: .utf8)!
+
+//
+// MARK: - EXAMPLE 1 (Mutable Attributes)
+//
+
+// pretend to have requested a Dog and received the mock data
+// now parse it.
+let parsedResponse = try! JSONDecoder().decode(MutableDogDocument.self, from: mockDogData)
+
+// extract our Dog (skipping over any robustness to handle errors)
+var dog = parsedResponse.body.primaryResource!.value
+print("Received dog named: \(dog.name)")
+
+// change the dog's name
+let changedDog = dog.tappingAttributes { $0.name = .init(value: "Julia") }
+
+// create a document to be used as a request body for a PATCH request
+let patchRequest = MutableDogDocument(apiDescription: .none,
+                                      body: .init(resourceObject: changedDog),
+                                      includes: .none,
+                                      meta: .none,
+                                      links: .none)
+
+// encode and send off to server
+let encodedPatchRequest = try! JSONEncoder().encode(patchRequest)
+print("----")
+print(String(data: encodedPatchRequest, encoding:.utf8)!)
+
+
+//
+// MARK: - EXAMPLE 2 (Immutable Attributes)
+//
+print()
+print("####")
+print()
+
+// pretend to have requested a Dog and received the mock data
+// now parse it.
+let parsedResponse2 = try! JSONDecoder().decode(SingleDogDocument.self, from: mockDogData)
+
+// extract our Dog (skipping over any robustness to handle errors)
+var dog2 = parsedResponse2.body.primaryResource!.value
+print("Received dog named: \(dog2.name)")
+
+// change the dog's name
+let changedDog2 = dog2.replacingAttributes { _ in
+    return .init(name: .init(value: "Nigel"))
+}
+
+// create a document to be used as a request body for a PATCH request
+let patchRequest2 = SingleDogDocument(apiDescription: .none,
+                                      body: .init(resourceObject: changedDog2),
+                                      includes: .none,
+                                      meta: .none,
+                                      links: .none)
+
+// encode and send off to server
+let encodedPatchRequest2 = try! JSONEncoder().encode(patchRequest2)
+print("----")
+print(String(data: encodedPatchRequest2, encoding:.utf8)!)
+
+
+//
+// MARK: - EXAMPLE 3 (Change relationship)
+//
+print()
+print("####")
+print()
+
+// pretend to have requested a Dog and received the mock data
+// now parse it.
+let parsedResponse3 = try! JSONDecoder().decode(SingleDogDocument.self, from: mockDogData)
+
+// extract our Dog (skipping over any robustness to handle errors)
+var dog3 = parsedResponse2.body.primaryResource!.value
+print("Received dog with owner: \(dog3 ~> \.owner)")
+
+// give the dog an owner
+let changedDog3 = dog3.replacingRelationships { _ in
+    return .init(owner: .init(id: Id(rawValue: "1")))
+}
+
+// create a document to be used as a request body for a PATCH request
+let patchRequest3 = SingleDogDocument(apiDescription: .none,
+                                      body: .init(resourceObject: changedDog3),
+                                      includes: .none,
+                                      meta: .none,
+                                      links: .none)
+
+// encode and send off to server
+let encodedPatchRequest3 = try! JSONEncoder().encode(patchRequest3)
+print("----")
+print(String(data: encodedPatchRequest3, encoding:.utf8)!)

JSONAPI.playground/Pages/Usage.xcplaygroundpage/Contents.swift

@@ -64,11 +64,11 @@ if case let .data(bodyData) = peopleResponse.body {
 
 // MARK: - Work in the abstract
 print("-----")
-func process<T: JSONAPIDocument>(document: T) {
+func process<T: CodableJSONAPIDocument>(document: T) {
-	guard case let .data(body) = document.body else {
+    guard let body = document.body.data else {
 		return
 	}
-	let x: T.Body.Data = body
+	let x: T.BodyData = body
 }
 process(document: peopleResponse)
 

JSONAPI.playground/Sources/Entities.swift

@@ -119,6 +119,29 @@ public enum AlternativeDogDescription: ResourceObjectDescription {
 
 public typealias AlternativeDog = ExampleEntity<AlternativeDogDescription>
 
+public enum MutableDogDescription: ResourceObjectDescription {
+
+    public static var jsonType: String { return "dogs" }
+
+    public struct Attributes: JSONAPI.Attributes {
+        public var name: Attribute<String>
+
+        public init(name: Attribute<String>) {
+            self.name = name
+        }
+    }
+
+    public struct Relationships: JSONAPI.Relationships {
+        public var owner: ToOne<Person?>
+
+        public init(owner: ToOne<Person?>) {
+            self.owner = owner
+        }
+    }
+}
+
+public typealias MutableDog = ExampleEntity<MutableDogDescription>
+
 public extension ResourceObject where Description == DogDescription, MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == String {
 	init(name: String, owner: Person?) throws {
 		self = Dog(attributes: .init(name: .init(value: name)), relationships: DogDescription.Relationships(owner: .init(resourceObject: owner)), meta: .none, links: .none)
@@ -141,4 +164,6 @@ public typealias House = ExampleEntity<HouseDescription>
 
 public typealias SingleDogDocument = JSONAPI.Document<SingleResourceBody<Dog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, BasicJSONAPIError<String>>
 
+public typealias MutableDogDocument = JSONAPI.Document<SingleResourceBody<MutableDog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, BasicJSONAPIError<String>>
+
 public typealias BatchPeopleDocument = JSONAPI.Document<ManyResourceBody<Person>, NoMetadata, NoLinks, Include2<Dog, House>, NoAPIDescription, BasicJSONAPIError<String>>

JSONAPI.playground/contents.xcplayground

@@ -6,5 +6,6 @@
         <page name='Full Client &amp; Server Example'/>
         <page name='Full Document Verbose Generation'/>
         <page name='Sparse Fieldsets Example'/>
+        <page name='PATCHing'/>
     </pages>
 </playground>

JSONAPI.podspec

@@ -16,7 +16,7 @@ Pod::Spec.new do |spec|
   #
 
   spec.name         = "MP-JSONAPI"
-  spec.version      = "2.2.0"
+  spec.version      = "3.0.0"
   spec.summary      = "Swift Codable JSON API framework."
 
   # This description is used to generate tags and improve search results.
@@ -136,6 +136,6 @@ See the JSON API Spec here: https://jsonapi.org/format/
   # spec.requires_arc = true
 
   # spec.xcconfig = { "HEADER_SEARCH_PATHS" => "$(SDKROOT)/usr/include/libxml2" }
-  spec.dependency "Poly", "~> 2.1"
+  spec.dependency "Poly", "~> 2.3.1"
 
 end

Package.resolved

@@ -6,8 +6,8 @@
         "repositoryURL": "https://github.com/mattpolzin/Poly.git",
         "state": {
           "branch": null,
-          "revision": "4a08517b24f8e9f6dd8c02ec7da316aac5c00e2e",
+          "revision": "0c9c08204142babc480938d704a23513d11420e5",
-          "version": "2.1.0"
+          "version": "2.3.1"
         }
       }
     ]

Package.swift

@@ -18,7 +18,7 @@ let package = Package(
             targets: ["JSONAPITesting"])
     ],
     dependencies: [
-        .package(url: "https://github.com/mattpolzin/Poly.git", .upToNextMajor(from: "2.1.0")),
+        .package(url: "https://github.com/mattpolzin/Poly.git", .upToNextMajor(from: "2.3.1")),
     ],
     targets: [
         .target(

Sources/JSONAPI/Document/APIDescription.swift

@@ -7,58 +7,58 @@
 
 /// This is what the JSON API Spec calls the "JSON:API Object"
 public protocol APIDescriptionType: Codable, Equatable {
-	associatedtype Meta
+    associatedtype Meta
 }
 
 /// This is what the JSON API Spec calls the "JSON:API Object"
 public struct APIDescription<Meta: JSONAPI.Meta>: APIDescriptionType {
-	public let version: String
+    public let version: String
-	public let meta: Meta
+    public let meta: Meta
 
-	public init(version: String, meta: Meta) {
+    public init(version: String, meta: Meta) {
-		self.version = version
+        self.version = version
-		self.meta = meta
+        self.meta = meta
-	}
+    }
 }
 
 /// Can be used as `APIDescriptionType` for Documents that do not
 /// have any API Description (a.k.a. "JSON:API Object").
 public struct NoAPIDescription: APIDescriptionType, CustomStringConvertible {
-	public typealias Meta = NoMetadata
+    public typealias Meta = NoMetadata
 
-	public init() {}
+    public init() {}
 
-	public static var none: NoAPIDescription { return .init() }
+    public static var none: NoAPIDescription { return .init() }
 
-	public var description: String { return "No JSON:API Object" }
+    public var description: String { return "No JSON:API Object" }
 }
 
 extension APIDescription {
-	private enum CodingKeys: String, CodingKey {
+    private enum CodingKeys: String, CodingKey {
-		case version
+        case version
-		case meta
+        case meta
-	}
+    }
 
-	public init(from decoder: Decoder) throws {
+    public init(from decoder: Decoder) throws {
-		let container = try decoder.container(keyedBy: CodingKeys.self)
+        let container = try decoder.container(keyedBy: CodingKeys.self)
 
-		// The spec says that if a version is not specified, it should be assumed to be at least 1.0
+        // The spec says that if a version is not specified, it should be assumed to be at least 1.0
-		version = (try? container.decode(String.self, forKey: .version)) ?? "1.0"
+        version = (try? container.decode(String.self, forKey: .version)) ?? "1.0"
 
-		if let metaVal = NoMetadata() as? Meta {
+        if let metaVal = NoMetadata() as? Meta {
-			meta = metaVal
+            meta = metaVal
-		} else {
+        } else {
-			meta = try container.decode(Meta.self, forKey: .meta)
+            meta = try container.decode(Meta.self, forKey: .meta)
-		}
+        }
-	}
+    }
 
-	public func encode(to encoder: Encoder) throws {
+    public func encode(to encoder: Encoder) throws {
-		var container = encoder.container(keyedBy: CodingKeys.self)
+        var container = encoder.container(keyedBy: CodingKeys.self)
 
-		try container.encode(version, forKey: .version)
+        try container.encode(version, forKey: .version)
 
-		if Meta.self != NoMetadata.self {
+        if Meta.self != NoMetadata.self {
-			try container.encode(meta, forKey: .meta)
+            try container.encode(meta, forKey: .meta)
-		}
+        }
-	}
+    }
 }

Sources/JSONAPI/Document/DocumentDecodingError.swift

@@ -0,0 +1,73 @@
+//
+//  DocumentDecodingError.swift
+//  
+//
+//  Created by Mathew Polzin on 10/20/19.
+//
+
+public enum DocumentDecodingError: Swift.Error, Equatable {
+    case primaryResource(error: ResourceObjectDecodingError, idx: Int?)
+    case primaryResourceMissing
+    case primaryResourcesMissing
+
+    case includes(error: IncludesDecodingError)
+
+    case foundErrorDocumentWhenExpectingSuccess
+    case foundSuccessDocumentWhenExpectingError
+
+    init(_ decodingError: ResourceObjectDecodingError) {
+        self = .primaryResource(error: decodingError, idx: nil)
+    }
+
+    init(_ decodingError: ManyResourceBodyDecodingError) {
+        self = .primaryResource(error: decodingError.error, idx: decodingError.idx)
+    }
+
+    init(_ decodingError: IncludesDecodingError) {
+        self = .includes(error: decodingError)
+    }
+
+    init?(_ decodingError: DecodingError) {
+        switch decodingError {
+        case .valueNotFound(let type, let context) where Location(context) == .data && type is AbstractResourceObject.Type:
+            self = .primaryResourceMissing
+        case .valueNotFound(let type, let context) where Location(context) == .data && type == UnkeyedDecodingContainer.self:
+            self = .primaryResourcesMissing
+        default:
+            return nil
+        }
+    }
+
+    private enum Location: Equatable {
+        case data
+
+        init?(_ context: DecodingError.Context) {
+            guard context.codingPath.contains(where: { $0.stringValue == "data" }) else {
+                return nil
+            }
+            self = .data
+        }
+    }
+}
+
+extension DocumentDecodingError: CustomStringConvertible {
+    public var description: String {
+        switch self {
+        case .primaryResource(error: let error, idx: let idx):
+            let idxString = idx.map { " \($0 + 1)" } ?? ""
+            return "Primary Resource\(idxString) failed to parse because \(error)"
+        case .primaryResourceMissing:
+            return "Primary Resource missing."
+        case .primaryResourcesMissing:
+            return "Primary Resources array missing."
+
+        case .includes(error: let error):
+            return "\(error)"
+
+        case .foundErrorDocumentWhenExpectingSuccess:
+            return "Expected a success document with a 'data' property but found an error document."
+        case .foundSuccessDocumentWhenExpectingError:
+            return "Expected an error document but found a success document with a 'data' property."
+        }
+    }
+}

Sources/JSONAPI/Document/Includes.swift

@@ -14,35 +14,35 @@ public typealias Include = EncodableJSONPoly
 ///
 /// If you have
 ///
-/// `let includes: Includes<Include2<Thing1, Thing2>> = ...`
+///     let includes: Includes<Include2<Thing1, Thing2>> = ...
 ///
 /// then you can access all `Thing1` included resources with
 ///
-/// `let includedThings = includes[Thing1.self]`
+///     let includedThings = includes[Thing1.self]
 public struct Includes<I: Include>: Encodable, Equatable {
-	public static var none: Includes { return .init(values: []) }
+    public static var none: Includes { return .init(values: []) }
 
-	let values: [I]
+    public let values: [I]
 
-	public init(values: [I]) {
+    public init(values: [I]) {
-		self.values = values
+        self.values = values
-	}
+    }
 
-	public func encode(to encoder: Encoder) throws {
+    public func encode(to encoder: Encoder) throws {
-		var container = encoder.unkeyedContainer()
+        var container = encoder.unkeyedContainer()
 
-		guard I.self != NoIncludes.self else {
+        guard I.self != NoIncludes.self else {
-			throw JSONAPIEncodingError.illegalEncoding("Attempting to encode Include0, which should be represented by the absense of an 'included' entry altogether.")
+            throw JSONAPICodingError.illegalEncoding("Attempting to encode Include0, which should be represented by the absense of an 'included' entry altogether.", path: encoder.codingPath)
-		}
+        }
 
-		for value in values {
+        for value in values {
-			try container.encode(value)
+            try container.encode(value)
-		}
+        }
-	}
+    }
 
-	public var count: Int {
+    public var count: Int {
-		return values.count
+        return values.count
-	}
+    }
 }
 
 extension Includes: Decodable where I: Decodable {
@@ -56,8 +56,35 @@ extension Includes: Decodable where I: Decodable {
         }
 
         var valueAggregator = [I]()
+        var idx = 0
         while !container.isAtEnd {
-            valueAggregator.append(try container.decode(I.self))
+            do {
+                valueAggregator.append(try container.decode(I.self))
+                idx = idx + 1
+            } catch let error as PolyDecodeNoTypesMatchedError {
+                let errors: [ResourceObjectDecodingError] = error
+                    .individualTypeFailures
+                    .compactMap { decodingError in
+                        switch decodingError.error {
+                        case .typeMismatch(_, let context),
+                             .valueNotFound(_, let context),
+                             .keyNotFound(_, let context),
+                             .dataCorrupted(let context):
+                            return context.underlyingError as? ResourceObjectDecodingError
+                        @unknown default:
+                            return nil
+                        }
+                }
+                guard errors.count == error.individualTypeFailures.count else {
+                    throw IncludesDecodingError(error: error, idx: idx)
+                }
+                throw IncludesDecodingError(
+                    error: IncludeDecodingError(failures: errors),
+                    idx: idx
+                )
+            } catch let error {
+                throw IncludesDecodingError(error: error, idx: idx)
+            }
         }
 
         values = valueAggregator
@@ -65,25 +92,25 @@ extension Includes: Decodable where I: Decodable {
 }
 
 extension Includes {
-	public func appending(_ other: Includes<I>) -> Includes {
+    public func appending(_ other: Includes<I>) -> Includes {
-		return Includes(values: values + other.values)
+        return Includes(values: values + other.values)
-	}
+    }
 }
 
 public func +<I: Include>(_ left: Includes<I>, _ right: Includes<I>) -> Includes<I> {
-	return left.appending(right)
+    return left.appending(right)
 }
 
 extension Includes: CustomStringConvertible {
-	public var description: String {
+    public var description: String {
-		return "Includes(\(String(describing: values))"
+        return "Includes(\(String(describing: values))"
-	}
+    }
 }
 
 extension Includes where I == NoIncludes {
-	public init() {
+    public init() {
-		values = []
+        values = []
-	}
+    }
 }
 
 // MARK: - 0 includes
@@ -93,73 +120,73 @@ public typealias NoIncludes = Include0
 // MARK: - 1 include
 public typealias Include1 = Poly1
 extension Includes where I: _Poly1 {
-	public subscript(_ lookup: I.A.Type) -> [I.A] {
+    public subscript(_ lookup: I.A.Type) -> [I.A] {
-		return values.compactMap { $0.a }
+        return values.compactMap { $0.a }
-	}
+    }
 }
 
 // MARK: - 2 includes
 public typealias Include2 = Poly2
 extension Includes where I: _Poly2 {
-	public subscript(_ lookup: I.B.Type) -> [I.B] {
+    public subscript(_ lookup: I.B.Type) -> [I.B] {
-		return values.compactMap { $0.b }
+        return values.compactMap { $0.b }
-	}
+    }
 }
 
 // MARK: - 3 includes
 public typealias Include3 = Poly3
 extension Includes where I: _Poly3 {
-	public subscript(_ lookup: I.C.Type) -> [I.C] {
+    public subscript(_ lookup: I.C.Type) -> [I.C] {
-		return values.compactMap { $0.c }
+        return values.compactMap { $0.c }
-	}
+    }
 }
 
 // MARK: - 4 includes
 public typealias Include4 = Poly4
 extension Includes where I: _Poly4 {
-	public subscript(_ lookup: I.D.Type) -> [I.D] {
+    public subscript(_ lookup: I.D.Type) -> [I.D] {
-		return values.compactMap { $0.d }
+        return values.compactMap { $0.d }
-	}
+    }
 }
 
 // MARK: - 5 includes
 public typealias Include5 = Poly5
 extension Includes where I: _Poly5 {
-	public subscript(_ lookup: I.E.Type) -> [I.E] {
+    public subscript(_ lookup: I.E.Type) -> [I.E] {
-		return values.compactMap { $0.e }
+        return values.compactMap { $0.e }
-	}
+    }
 }
 
 // MARK: - 6 includes
 public typealias Include6 = Poly6
 extension Includes where I: _Poly6 {
-	public subscript(_ lookup: I.F.Type) -> [I.F] {
+    public subscript(_ lookup: I.F.Type) -> [I.F] {
-		return values.compactMap { $0.f }
+        return values.compactMap { $0.f }
-	}
+    }
 }
 
 // MARK: - 7 includes
 public typealias Include7 = Poly7
 extension Includes where I: _Poly7 {
-	public subscript(_ lookup: I.G.Type) -> [I.G] {
+    public subscript(_ lookup: I.G.Type) -> [I.G] {
-		return values.compactMap { $0.g }
+        return values.compactMap { $0.g }
-	}
+    }
 }
 
 // MARK: - 8 includes
 public typealias Include8 = Poly8
 extension Includes where I: _Poly8 {
-	public subscript(_ lookup: I.H.Type) -> [I.H] {
+    public subscript(_ lookup: I.H.Type) -> [I.H] {
-		return values.compactMap { $0.h }
+        return values.compactMap { $0.h }
-	}
+    }
 }
 
 // MARK: - 9 includes
 public typealias Include9 = Poly9
 extension Includes where I: _Poly9 {
-	public subscript(_ lookup: I.I.Type) -> [I.I] {
+    public subscript(_ lookup: I.I.Type) -> [I.I] {
-		return values.compactMap { $0.i }
+        return values.compactMap { $0.i }
-	}
+    }
 }
 
 // MARK: - 10 includes
@@ -169,3 +196,40 @@ extension Includes where I: _Poly10 {
         return values.compactMap { $0.j }
     }
 }
+
+// MARK: - 11 includes
+public typealias Include11 = Poly11
+extension Includes where I: _Poly11 {
+    public subscript(_ lookup: I.K.Type) -> [I.K] {
+        return values.compactMap { $0.k }
+    }
+}
+
+// MARK: - DecodingError
+public struct IncludesDecodingError: Swift.Error, Equatable {
+    public let error: Swift.Error
+    public let idx: Int
+
+    public static func ==(lhs: Self, rhs: Self) -> Bool {
+        return lhs.idx == rhs.idx
+            && String(describing: lhs) == String(describing: rhs)
+    }
+}
+
+extension IncludesDecodingError: CustomStringConvertible {
+    public var description: String {
+        return "Include \(idx + 1) failed to parse: \(error)"
+    }
+}
+
+public struct IncludeDecodingError: Swift.Error, Equatable, CustomStringConvertible {
+    public let failures: [ResourceObjectDecodingError]
+
+    public var description: String {
+        return failures
+            .enumerated()
+            .map {
+                "\nCould not have been Include Type \($0.offset + 1) because:\n\($0.element)"
+        }.joined(separator: "\n")
+    }
+}

Sources/JSONAPI/Document/ResourceBody.swift

@@ -10,121 +10,132 @@
 /// array should be used for no results).
 public protocol OptionalEncodablePrimaryResource: Equatable, Encodable {}
 
-/// An `EncodablePrimaryResource` is a `PrimaryResource` that only supports encoding.
+/// An `EncodablePrimaryResource` is a `CodablePrimaryResource` that only supports encoding.
-/// This is actually more restrictave than `PrimaryResource`, which supports both encoding and
-/// decoding.
 public protocol EncodablePrimaryResource: OptionalEncodablePrimaryResource {}
 
 /// This protocol allows for `SingleResourceBody` to contain a `null`
 /// data object where `ManyResourceBody` cannot (because an empty
 /// array should be used for no results).
-public protocol OptionalPrimaryResource: OptionalEncodablePrimaryResource, Decodable {}
+public protocol OptionalCodablePrimaryResource: OptionalEncodablePrimaryResource, Decodable {}
 
-/// A `PrimaryResource` is a type that can be used in the body of a JSON API
+/// A `CodablePrimaryResource` is a type that can be used in the body of a JSON API
 /// document as the primary resource.
-public protocol PrimaryResource: EncodablePrimaryResource, OptionalPrimaryResource {}
+public protocol CodablePrimaryResource: EncodablePrimaryResource, OptionalCodablePrimaryResource {}
 
 extension Optional: OptionalEncodablePrimaryResource where Wrapped: EncodablePrimaryResource {}
 
-extension Optional: OptionalPrimaryResource where Wrapped: PrimaryResource {}
+extension Optional: OptionalCodablePrimaryResource where Wrapped: CodablePrimaryResource {}
 
 /// An `EncodableResourceBody` is a `ResourceBody` that only supports being
 /// encoded. It is actually weaker than `ResourceBody`, which supports both encoding
 /// and decoding.
-public protocol EncodableResourceBody: Equatable, Encodable {}
+public protocol EncodableResourceBody: Equatable, Encodable {
+    associatedtype PrimaryResource
+}
 
-/// A ResourceBody is a representation of the body of the JSON API Document.
+/// A `CodableResourceBody` is a representation of the body of the JSON:API Document.
 /// It can either be one resource (which can be specified as optional or not)
 /// or it can contain many resources (and array with zero or more entries).
-public protocol ResourceBody: Decodable, EncodableResourceBody {}
+public protocol CodableResourceBody: Decodable, EncodableResourceBody {}
 
 /// A `ResourceBody` that has the ability to take on more primary
 /// resources by appending another similarly typed `ResourceBody`.
-public protocol Appendable {
+public protocol ResourceBodyAppendable {
-	func appending(_ other: Self) -> Self
+    func appending(_ other: Self) -> Self
 }
 
-public func +<R: Appendable>(_ left: R, right: R) -> R {
+public func +<R: ResourceBodyAppendable>(_ left: R, right: R) -> R {
-	return left.appending(right)
+    return left.appending(right)
 }
 
 /// A type allowing for a document body containing 1 primary resource.
 /// If the `Entity` specialization is an `Optional` type, the body can contain
 /// 0 or 1 primary resources.
-public struct SingleResourceBody<Entity: JSONAPI.OptionalEncodablePrimaryResource>: EncodableResourceBody {
+public struct SingleResourceBody<PrimaryResource: JSONAPI.OptionalEncodablePrimaryResource>: EncodableResourceBody {
-	public let value: Entity
+    public let value: PrimaryResource
 
-	public init(resourceObject: Entity) {
+    public init(resourceObject: PrimaryResource) {
-		self.value = resourceObject
+        self.value = resourceObject
-	}
+    }
 }
 
 /// A type allowing for a document body containing 0 or more primary resources.
-public struct ManyResourceBody<Entity: JSONAPI.EncodablePrimaryResource>: EncodableResourceBody, Appendable {
+public struct ManyResourceBody<PrimaryResource: JSONAPI.EncodablePrimaryResource>: EncodableResourceBody, ResourceBodyAppendable {
-	public let values: [Entity]
+    public let values: [PrimaryResource]
 
-	public init(resourceObjects: [Entity]) {
+    public init(resourceObjects: [PrimaryResource]) {
-		values = resourceObjects
+        values = resourceObjects
-	}
+    }
 
-	public func appending(_ other: ManyResourceBody) -> ManyResourceBody {
+    public func appending(_ other: ManyResourceBody) -> ManyResourceBody {
-		return ManyResourceBody(resourceObjects: values + other.values)
+        return ManyResourceBody(resourceObjects: values + other.values)
-	}
+    }
 }
 
 /// Use NoResourceBody to indicate you expect a JSON API document to not
 /// contain a "data" top-level key.
-public struct NoResourceBody: ResourceBody {
+public struct NoResourceBody: CodableResourceBody {
-	public static var none: NoResourceBody { return NoResourceBody() }
+    public typealias PrimaryResource = Void
+
+    public static var none: NoResourceBody { return NoResourceBody() }
 }
 
 // MARK: Codable
 extension SingleResourceBody {
-	public func encode(to encoder: Encoder) throws {
+    public func encode(to encoder: Encoder) throws {
-		var container = encoder.singleValueContainer()
+        var container = encoder.singleValueContainer()
 
         let anyNil: Any? = nil
-        let nilValue = anyNil as? Entity
+        let nilValue = anyNil as? PrimaryResource
         guard value != nilValue else {
             try container.encodeNil()
             return
         }
 
-		try container.encode(value)
+        try container.encode(value)
-	}
+    }
 }
 
-extension SingleResourceBody: Decodable, ResourceBody where Entity: OptionalPrimaryResource {
+extension SingleResourceBody: Decodable, CodableResourceBody where PrimaryResource: OptionalCodablePrimaryResource {
     public init(from decoder: Decoder) throws {
         let container = try decoder.singleValueContainer()
 
         let anyNil: Any? = nil
         if container.decodeNil(),
-            let val = anyNil as? Entity {
+            let val = anyNil as? PrimaryResource {
             value = val
             return
         }
 
-        value = try container.decode(Entity.self)
+        value = try container.decode(PrimaryResource.self)
     }
 }
 
 extension ManyResourceBody {
-	public func encode(to encoder: Encoder) throws {
+    public func encode(to encoder: Encoder) throws {
-		var container = encoder.unkeyedContainer()
+        var container = encoder.unkeyedContainer()
 
-		for value in values {
+        for value in values {
-			try container.encode(value)
+            try container.encode(value)
-		}
+        }
-	}
+    }
 }
 
-extension ManyResourceBody: Decodable, ResourceBody where Entity: PrimaryResource {
+extension ManyResourceBody: Decodable, CodableResourceBody where PrimaryResource: CodablePrimaryResource {
     public init(from decoder: Decoder) throws {
         var container = try decoder.unkeyedContainer()
-        var valueAggregator = [Entity]()
+        var valueAggregator = [PrimaryResource]()
+        var idx = 0
         while !container.isAtEnd {
-            valueAggregator.append(try container.decode(Entity.self))
+            do {
+                valueAggregator.append(try container.decode(PrimaryResource.self))
+            } catch let error as ResourceObjectDecodingError {
+                throw ManyResourceBodyDecodingError(
+                    error: error,
+                    idx: idx
+                )
+            }
+            idx = idx + 1
         }
         values = valueAggregator
     }
@@ -133,13 +144,19 @@ extension ManyResourceBody: Decodable, ResourceBody where Entity: PrimaryResourc
 // MARK: CustomStringConvertible
 
 extension SingleResourceBody: CustomStringConvertible {
-	public var description: String {
+    public var description: String {
-		return "PrimaryResourceBody(\(String(describing: value)))"
+        return "PrimaryResourceBody(\(String(describing: value)))"
-	}
+    }
 }
 
 extension ManyResourceBody: CustomStringConvertible {
-	public var description: String {
+    public var description: String {
-		return "PrimaryResourceBody(\(String(describing: values)))"
+        return "PrimaryResourceBody(\(String(describing: values)))"
-	}
+    }
+}
+
+// MARK: - DecodingError
+public struct ManyResourceBodyDecodingError: Swift.Error, Equatable {
+    public let error: ResourceObjectDecodingError
+    public let idx: Int
 }

Sources/JSONAPI/EncodingError.swift

@@ -1,14 +0,0 @@
-//
-//  EncodingError.swift
-//  JSONAPI
-//
-//  Created by Mathew Polzin on 12/7/18.
-//
-
-public enum JSONAPIEncodingError: Swift.Error {
-	case typeMismatch(expected: String, found: String)
-	case illegalEncoding(String)
-	case illegalDecoding(String)
-	case missingOrMalformedMetadata
-	case missingOrMalformedLinks
-}

Sources/JSONAPI/Error/BasicJSONAPIError.swift

@@ -1,15 +1,17 @@
 //
-//  BasicError.swift
+//  BasicJSONAPIError.swift
 //  JSONAPI
 //
 //  Created by Mathew Polzin on 9/29/19.
 //
 
 /// Most of the JSON:API Spec defined Error fields.
-public struct BasicJSONAPIErrorPayload<IdType: Codable & Equatable>: Codable, Equatable, ErrorDictType {
+public struct BasicJSONAPIErrorPayload<IdType: Codable & Equatable>: Codable, Equatable, ErrorDictType, CustomStringConvertible {
     /// a unique identifier for this particular occurrence of the problem
     public let id: IdType?
-//    public let links: Links? // we skip this for now to avoid adding complexity to using this basic type.
+
+    //    public let links: Links? // we skip this for now to avoid adding complexity to using this basic type.
+
     /// the HTTP status code applicable to this problem
     public let status: String?
     /// an application-specific error code
@@ -20,7 +22,8 @@ public struct BasicJSONAPIErrorPayload<IdType: Codable & Equatable>: Codable, Eq
     public let detail: String?
     /// an object containing references to the source of the error
     public let source: Source?
-//    public let meta: Meta? // we skip this for now to avoid adding complexity to using this basic type
+
+    //    public let meta: Meta? // we skip this for now to avoid adding complexity to using this basic type
 
     public init(id: IdType? = nil,
                 status: String? = nil,
@@ -61,6 +64,10 @@ public struct BasicJSONAPIErrorPayload<IdType: Codable & Equatable>: Codable, Eq
             ].compactMap { $0 }
         return Dictionary(uniqueKeysWithValues: keysAndValues)
     }
+
+    public var description: String {
+        return definedFields.map { "\($0.key): \($0.value)" }.sorted().joined(separator: ", ")
+    }
 }
 
 /// `BasicJSONAPIError` optionally decodes many possible fields

Sources/JSONAPI/Error/GenericJSONAPIError.swift

@@ -1,5 +1,5 @@
 //
-//  GenericError.swift
+//  GenericJSONAPIError.swift
 //  JSONAPI
 //
 //  Created by Mathew Polzin on 9/29/19.
@@ -8,7 +8,7 @@
 /// `GenericJSONAPIError` can be used to specify whatever error
 /// payload you expect to need to parse in responses and handle any
 /// other payload structure as `.unknownError`.
-public enum GenericJSONAPIError<ErrorPayload: Codable & Equatable>: JSONAPIError {
+public enum GenericJSONAPIError<ErrorPayload: Codable & Equatable>: JSONAPIError, CustomStringConvertible {
     case unknownError
     case error(ErrorPayload)
 
@@ -35,6 +35,15 @@ public enum GenericJSONAPIError<ErrorPayload: Codable & Equatable>: JSONAPIError
     public static var unknown: Self {
         return .unknownError
     }
+
+    public var description: String {
+        switch self {
+        case .unknownError:
+            return "unknown error"
+        case .error(let payload):
+            return String(describing: payload)
+        }
+    }
 }
 
 public extension GenericJSONAPIError {

Sources/JSONAPI/Error/JSONAPIError.swift

@@ -1,12 +1,12 @@
 //
-//  Error.swift
+//  JSONAPIError.swift
 //  JSONAPI
 //
 //  Created by Mathew Polzin on 11/10/18.
 //
 
 public protocol JSONAPIError: Swift.Error, Equatable, Codable {
-	static var unknown: Self { get }
+    static var unknown: Self { get }
 }
 
 /// `UnknownJSONAPIError` can actually be used in any sitaution
@@ -16,18 +16,18 @@ public protocol JSONAPIError: Swift.Error, Equatable, Codable {
 /// information the server might be providing in the error payload,
 /// use `BasicJSONAPIError` instead.
 public enum UnknownJSONAPIError: JSONAPIError {
-	case unknownError
+    case unknownError
 
-	public init(from decoder: Decoder) throws {
+    public init(from decoder: Decoder) throws {
-		self = .unknown
+        self = .unknown
-	}
+    }
 
-	public func encode(to encoder: Encoder) throws {
+    public func encode(to encoder: Encoder) throws {
-		var container = encoder.singleValueContainer()
+        var container = encoder.singleValueContainer()
-		try container.encode("unknown")
+        try container.encode("unknown")
-	}
+    }
 
-	public static var unknown: Self {
+    public static var unknown: Self {
-		return .unknownError
+        return .unknownError
-	}
+    }
 }

Sources/JSONAPI/JSONAPICodingError.swift

@@ -0,0 +1,27 @@
+//
+//  JSONAPICodingError.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 12/7/18.
+//
+
+public enum JSONAPICodingError: Swift.Error {
+    case typeMismatch(expected: String, found: String, path: [CodingKey])
+    case quantityMismatch(expected: Quantity, path: [CodingKey])
+    case illegalEncoding(String, path: [CodingKey])
+    case illegalDecoding(String, path: [CodingKey])
+    case missingOrMalformedMetadata(path: [CodingKey])
+    case missingOrMalformedLinks(path: [CodingKey])
+
+    public enum Quantity: String, Equatable {
+        case one
+        case many
+
+        public var other: Quantity {
+            switch self {
+            case .one: return .many
+            case .many: return .one
+            }
+        }
+    }
+}

Sources/JSONAPI/Meta/Links.swift

@@ -5,63 +5,63 @@
 //  Created by Mathew Polzin on 11/24/18.
 //
 
-/// A Links structure should contain nothing but JSONAPI.Link properties.
+/// A Links structure should contain nothing but `JSONAPI.Link` properties.
 public protocol Links: Codable, Equatable {}
 
 /// Use NoLinks where no links should belong to a JSON API component
 public struct NoLinks: Links, CustomStringConvertible {
-	public static var none: NoLinks { return NoLinks() }
+    public static var none: NoLinks { return NoLinks() }
-	public init() {}
+    public init() {}
     
-	public var description: String { return "No Links" }
+    public var description: String { return "No Links" }
 }
 
 public protocol JSONAPIURL: Codable, Equatable {}
 
 public struct Link<URL: JSONAPI.JSONAPIURL, Meta: JSONAPI.Meta>: Equatable, Codable {
-	public let url: URL
+    public let url: URL
-	public let meta: Meta
+    public let meta: Meta
     
-	public init(url: URL, meta: Meta) {
+    public init(url: URL, meta: Meta) {
-		self.url = url
+        self.url = url
-		self.meta = meta
+        self.meta = meta
-	}
+    }
 }
 
 extension Link where Meta == NoMetadata {
-	public init(url: URL) {
+    public init(url: URL) {
-		self.init(url: url, meta: .none)
+        self.init(url: url, meta: .none)
-	}
+    }
 }
 
 public extension Link {
-	private enum CodingKeys: String, CodingKey {
+    private enum CodingKeys: String, CodingKey {
-		case href
+        case href
-		case meta
+        case meta
-	}
+    }
     
-	init(from decoder: Decoder) throws {
+    init(from decoder: Decoder) throws {
-		guard Meta.self == NoMetadata.self,
+        guard Meta.self == NoMetadata.self,
-			let noMeta = NoMetadata() as? Meta else {
+            let noMeta = NoMetadata() as? Meta else {
-				let container = try decoder.container(keyedBy: CodingKeys.self)
+                let container = try decoder.container(keyedBy: CodingKeys.self)
-				meta = try container.decode(Meta.self, forKey: .meta)
+                meta = try container.decode(Meta.self, forKey: .meta)
-				url = try container.decode(URL.self, forKey: .href)
+                url = try container.decode(URL.self, forKey: .href)
-				return
+                return
-		}
+        }
-		let container = try decoder.singleValueContainer()
+        let container = try decoder.singleValueContainer()
-		url = try container.decode(URL.self)
+        url = try container.decode(URL.self)
-		meta = noMeta
+        meta = noMeta
-	}
+    }
     
-	func encode(to encoder: Encoder) throws {
+    func encode(to encoder: Encoder) throws {
-		guard Meta.self == NoMetadata.self else {
+        guard Meta.self == NoMetadata.self else {
-			var container = encoder.container(keyedBy: CodingKeys.self)
+            var container = encoder.container(keyedBy: CodingKeys.self)
-			try container.encode(url, forKey: .href)
+            try container.encode(url, forKey: .href)
-			try container.encode(meta, forKey: .meta)
+            try container.encode(meta, forKey: .meta)
-			return
+            return
-		}
+        }
-		var container = encoder.singleValueContainer()
+        var container = encoder.singleValueContainer()
         
-		try container.encode(url)
+        try container.encode(url)
-	}
+    }
 }