I did some more type wrangling to finally get the Id type to specialize on Entity rather than EntityDescription. The compiler gets into trouble depending on which of a few semantically identical routes are taken, but I finally stumbled upon the correct combination of protocols and extensions to get the job done. this was always the ideal outcome, but I was not sure the Swift compiler would allow it.

Author: mattpolzin

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

@@ -40,10 +40,13 @@ let peopleFromData = peopleResponse.body.primaryData?.values
 let dogsFromData = peopleResponse.body.includes?[Dog.self]
 let housesFromData = peopleResponse.body.includes?[House.self]
 
+print("-----")
+print(peopleResponse)
+print("-----")
+
 // MARK: - Pass successfully parsed body to other parts of the code
 
 if case let .data(bodyData) = peopleResponse.body {
-	print(bodyData)
 	print("first person's name: \(bodyData.primary.values[0][\.fullName])")
 } else {
 	print("no body data")

JSONAPI.playground/Sources/Entities.swift

@@ -24,7 +24,7 @@ extension String: CreatableRawIdType {
 }
 
 // MARK: - Entity typealias for convenience
-public typealias ExampleEntity<Description: EntityDescription> = Entity<Description, Id<String, Description>>
+public typealias ExampleEntity<Description: EntityDescription> = Entity<Description, String>
 
 // MARK: - A few resource objects (entities)
 public enum PersonDescription: EntityDescription {
@@ -60,9 +60,9 @@ public enum PersonDescription: EntityDescription {
 
 public typealias Person = ExampleEntity<PersonDescription>
 
-public extension Entity where Description == PersonDescription, Identifier == Id<String, PersonDescription> {
-	public init(id: Person.Identifier? = nil,name: [String], favoriteColor: String, friends: [Person], dogs: [Dog], home: House) throws {
-		self = try Person(id: id ?? Person.Identifier(), attributes: .init(name: .init(rawValue: name), favoriteColor: .init(rawValue: favoriteColor)), relationships: .init(friends: .init(entities: friends), dogs: .init(entities: dogs), home: .init(entity: home)))
+public extension Entity where Description == PersonDescription, EntityRawIdType == String {
+	public init(id: Person.Id? = nil,name: [String], favoriteColor: String, friends: [Person], dogs: [Dog], home: House) throws {
+		self = try Person(id: id ?? Person.Id(), attributes: .init(name: .init(rawValue: name), favoriteColor: .init(rawValue: favoriteColor)), relationships: .init(friends: .init(entities: friends), dogs: .init(entities: dogs), home: .init(entity: home)))
 	}
 }
 
@@ -89,12 +89,12 @@ public enum DogDescription: EntityDescription {
 
 public typealias Dog = ExampleEntity<DogDescription>
 
-public extension Entity where Description == DogDescription, Identifier == Id<String, DogDescription> {
+public extension Entity where Description == DogDescription, EntityRawIdType == String {
 	public init(name: String, owner: Person?) throws {
 		self = try Dog(attributes: .init(name: .init(rawValue: name)), relationships: DogDescription.Relationships(owner: .init(entity: owner)))
 	}
 
-	public init(name: String, owner: Person.Identifier) throws {
+	public init(name: String, owner: Person.Id) throws {
 		self = try Dog(attributes: .init(name: .init(rawValue: name)), relationships: .init(owner: .init(id: owner)))
 	}
 }

README.md

@@ -170,13 +170,13 @@ An `Entity` needs to be specialized on two generic types. The first is the `Enti
 
 #### `IdType`
 
-An `IdType` packages up two pieces of information: A unique identifier of a given `RawIdType` and the `EntityDescription` of the type of entity the Id identifies. Having the `EntityDescription` type associated with the Id makes it easy to store all of your entities in a local hash broken out by `EntityDescription`; You can pass Ids around and always know where to look for the `Entity` to which the Id refers. `RawIdType`s are documented below.
+An `IdType` packages up two pieces of information: A unique identifier of a given `RawIdType` and the `Entity` type that the Id identifies. Having the `Entity` type associated with the Id makes it easy to store all of your entities in a local hash broken out by `Entity` type; You can pass Ids around and always know where to look for the `Entity` to which the Id refers. `RawIdType`s are documented below.
 
 #### Convenient `typealiases`
 
 Often you can use one `RawIdType` for many if not all of your `Entities`. That means you can save yourself some boilerplate by using `typealias`es like the following:
 ```
-public typealias Entity<Description: JSONAPI.EntityDescription> = JSONAPI.Entity<Description, Id<String, Description>>
+public typealias Entity<Description: JSONAPI.EntityDescription> = JSONAPI.Entity<Description, String>
 
 public typealias NewEntity<Description: JSONAPI.EntityDescription> = JSONAPI.Entity<Description, Unidentified>
 ```

Sources/JSONAPI/Document/Document.swift

@@ -243,6 +243,23 @@ extension Document {
 
 extension Document: CustomStringConvertible {
 	public var description: String {
-		return "Document(body: \(String(describing: body))"
+		return "Document(\(String(describing: body)))"
+	}
+}
+
+extension Document.Body: CustomStringConvertible {
+	public var description: String {
+		switch self {
+		case .errors(let errors, meta: let meta, links: let links):
+			return "errors: \(String(describing: errors)), meta: \(String(describing: meta)), links: \(String(describing: links))"
+		case .data(let data):
+			return String(describing: data)
+		}
+	}
+}
+
+extension Document.Body.Data: CustomStringConvertible {
+	public var description: String {
+		return "primary: \(String(describing: primary)), includes: \(String(describing: includes)), meta: \(String(describing: meta)), links: \(String(describing: links))"
 	}
 }

Sources/JSONAPI/Meta/Links.swift

@@ -9,9 +9,11 @@
 public protocol Links: Codable, Equatable {}
 
 /// Use NoLinks where no links should belong to a JSON API component
-public struct NoLinks: Links {
+public struct NoLinks: Links, CustomStringConvertible {
 	public static var none: NoLinks { return NoLinks() }
 	public init() {}
+
+	public var description: String { return "No Links" }
 }
 
 public protocol JSONAPIURL: Codable, Equatable {}

Sources/JSONAPI/Meta/Meta.swift

@@ -19,8 +19,10 @@ public protocol Meta: Codable, Equatable {
 // nullable.
 extension Optional: Meta where Wrapped: Meta {}
 
-public struct NoMetadata: Meta {
+public struct NoMetadata: Meta, CustomStringConvertible {
 	public static var none: NoMetadata { return NoMetadata() }
 
 	public init() { }
+
+	public var description: String { return "No Metadata" }
 }

Sources/JSONAPI/Resource/Entity.swift

@@ -39,7 +39,9 @@ public protocol EntityDescription {
 /// specialization.
 public protocol EntityType: PrimaryResource {
 	associatedtype Description: EntityDescription
-	associatedtype Identifier: Equatable & Codable
+	associatedtype EntityRawIdType: JSONAPI.MaybeRawId
+
+	typealias Id = JSONAPI.Id<EntityRawIdType, Self>
 
 	typealias Attributes = Description.Attributes
 	typealias Relationships = Description.Relationships
@@ -48,7 +50,7 @@ public protocol EntityType: PrimaryResource {
 	/// the entity is being created clientside and the
 	/// server is being asked to create a unique Id. Otherwise,
 	/// this should be of a type conforming to `IdType`.
-	var id: Identifier { get }
+	var id: Id { get }
 
 	/// The JSON API compliant attributes of this `Entity`.
 	var attributes: Attributes { get }
@@ -57,11 +59,13 @@ public protocol EntityType: PrimaryResource {
 	var relationships: Relationships { get }
 }
 
+public protocol IdentifiableEntityType: EntityType, Relatable where EntityRawIdType: JSONAPI.RawIdType {}
+
 /// An `Entity` is a single model type that can be
 /// encoded to or decoded from a JSON API
 /// "Resource Object."
 /// See https://jsonapi.org/format/#document-resource-objects
-public struct Entity<Description: JSONAPI.EntityDescription, Identifier: JSONAPI.Identifier>: EntityType {
+public struct Entity<Description: JSONAPI.EntityDescription, EntityRawIdType: JSONAPI.MaybeRawId>: EntityType {
 
 	/// The JSON API compliant "type" of this `Entity`.
 	public static var type: String { return Description.type }
@@ -70,74 +74,79 @@ public struct Entity<Description: JSONAPI.EntityDescription, Identifier: JSONAPI
 	/// the entity is being created clientside and the
 	/// server is being asked to create a unique Id. Otherwise,
 	/// this should be of a type conforming to `IdType`.
-	public let id: Identifier
+	public let id: Entity.Id
 
 	/// The JSON API compliant attributes of this `Entity`.
 	public let attributes: Description.Attributes
 
 	/// The JSON API compliant relationships of this `Entity`.
 	public let relationships: Description.Relationships
 
-	public init(id: Identifier, attributes: Description.Attributes, relationships: Description.Relationships) {
+	public init(id: Entity.Id, attributes: Description.Attributes, relationships: Description.Relationships) {
 		self.id = id
 		self.attributes = attributes
 		self.relationships = relationships
 	}
 }
 
+extension Entity: IdentifiableEntityType, Relatable, WrappedRelatable where EntityRawIdType: JSONAPI.RawIdType {
+	public typealias Identifier = Entity.Id
+	public typealias WrappedIdentifier = Identifier
+}
+
 extension Entity: CustomStringConvertible {
 	public var description: String {
 		return "Entity<\(Entity.type)>(id: \(String(describing: id)), attributes: \(String(describing: attributes)), relationships: \(String(describing: relationships)))"
 	}
 }
 
 // MARK: Convenience initializers
-extension Entity where Identifier: CreatableIdType {
+extension Entity where EntityRawIdType: CreatableRawIdType {
 	public init(attributes: Description.Attributes, relationships: Description.Relationships) {
-		self.id = Identifier()
+		self.id = Entity.Id()
 		self.attributes = attributes
 		self.relationships = relationships
 	}
 }
 
 extension Entity where Description.Attributes == NoAttributes {
-	public init(id: Identifier, relationships: Description.Relationships) {
+	public init(id: Entity.Id, relationships: Description.Relationships) {
 		self.init(id: id, attributes: NoAttributes(), relationships: relationships)
 	}
 }
 
-extension Entity where Description.Attributes == NoAttributes, Identifier: CreatableIdType {
+extension Entity where Description.Attributes == NoAttributes, EntityRawIdType: CreatableRawIdType {
 	public init(relationships: Description.Relationships) {
 		self.init(attributes: NoAttributes(), relationships: relationships)
 	}
 }
 
 extension Entity where Description.Relationships == NoRelationships {
-	public init(id: Identifier, attributes: Description.Attributes) {
+	public init(id: Entity.Id, attributes: Description.Attributes) {
 		self.init(id: id, attributes: attributes, relationships: NoRelationships())
 	}
 }
 
-extension Entity where Description.Relationships == NoRelationships, Identifier: CreatableIdType {
+extension Entity where Description.Relationships == NoRelationships, EntityRawIdType: CreatableRawIdType {
 	public init(attributes: Description.Attributes) {
 		self.init(attributes: attributes, relationships: NoRelationships())
 	}
 }
 
 extension Entity where Description.Attributes == NoAttributes, Description.Relationships == NoRelationships {
-	public init(id: Identifier) {
+	public init(id: Entity.Id) {
 		self.init(id: id, attributes: NoAttributes(), relationships: NoRelationships())
 	}
 }
 
-extension Entity where Description.Attributes == NoAttributes, Description.Relationships == NoRelationships, Identifier: CreatableIdType {
+extension Entity where Description.Attributes == NoAttributes, Description.Relationships == NoRelationships, EntityRawIdType: CreatableRawIdType {
 	public init() {
 		self.init(attributes: NoAttributes(), relationships: NoRelationships())
 	}
 }
 
 // MARK: Pointer for Relationships use.
-public extension Entity where Identifier: IdType {
+public extension Entity where EntityRawIdType: JSONAPI.RawIdType {
 	/// Get a pointer to this entity that can be used as a
 	/// relationship to another entity.
 	public var pointer: ToOneRelationship<Entity> {
@@ -202,7 +211,7 @@ public extension Entity {
 
 		try container.encode(Entity.type, forKey: .type)
 
-		if Identifier.self != Unidentified<Description>.self {
+		if EntityRawIdType.self != Unidentified.self {
 			try container.encode(id, forKey: .id)
 		}
 
@@ -224,8 +233,9 @@ public extension Entity {
 		guard Entity.type == type else {
 			throw JSONAPIEncodingError.typeMismatch(expected: Description.type, found: type)
 		}
-		
-		id = try (Unidentified<Description>() as? Identifier) ?? container.decode(Identifier.self, forKey: .id)
+
+		let maybeUnidentified = Unidentified() as? EntityRawIdType
+		id = try maybeUnidentified.map { Entity.Id(rawValue: $0) } ?? container.decode(Entity.Id.self, forKey: .id)
 
 		attributes = try (NoAttributes() as? Description.Attributes) ?? container.decode(Description.Attributes.self, forKey: .attributes)
 

Sources/JSONAPI/Resource/Id.swift

@@ -5,10 +5,16 @@
 //  Created by Mathew Polzin on 7/24/18.
 //
 
+/// All types that are RawIdType and additionally
+/// Unidentified conform to this protocol. You
+/// should not add conformance to this protocol
+/// directly.
+public protocol MaybeRawId: Codable, Equatable {}
+
 /// Any type that you would like to be encoded to and
 /// decoded from JSON API ids should conform to this
 /// protocol. Conformance for `String` is given.
-public protocol RawIdType: Codable, Hashable {}
+public protocol RawIdType: MaybeRawId, Hashable {}
 
 /// If you would like to be able to create new
 /// Entities with Ids backed by a RawIdType then
@@ -22,19 +28,18 @@ public protocol CreatableRawIdType: RawIdType {
 
 extension String: RawIdType {}
 
-public protocol Identifier: Codable, Equatable {
-	associatedtype EntityDescription: JSONAPI.EntityDescription
-}
-
-public struct Unidentified<EntityDescription: JSONAPI.EntityDescription>: Identifier, CustomStringConvertible {
+public struct Unidentified: MaybeRawId, CustomStringConvertible {
 	public init() {}
 
-	public var description: String { return "Id(Unidentified)" }
+	public var description: String { return "Unidentified" }
 }
 
-public protocol IdType: Identifier, Hashable, CustomStringConvertible {
-	associatedtype RawType: RawIdType
-	
+public protocol MaybeId: Codable {
+	associatedtype EntityType: JSONAPI.EntityType
+	associatedtype RawType: MaybeRawId
+}
+
+public protocol IdType: MaybeId, CustomStringConvertible, Hashable where RawType: RawIdType {
 	var rawValue: RawType { get }
 }
 
@@ -48,27 +53,33 @@ public protocol CreatableIdType: IdType {
 
 /// An Entity ID. These IDs can be encoded to or decoded from
 /// JSON API IDs.
-public struct Id<RawType: RawIdType, EntityDescription: JSONAPI.EntityDescription>: IdType {
+public struct Id<RawType: MaybeRawId, EntityType: JSONAPI.EntityType>: Codable, Equatable, MaybeId {
 
 	public let rawValue: RawType
 
 	public init(rawValue: RawType) {
 		self.rawValue = rawValue
 	}
-	
+
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.singleValueContainer()
 		rawValue = try container.decode(RawType.self)
 	}
-	
+
 	public func encode(to encoder: Encoder) throws {
 		var container = encoder.singleValueContainer()
 		try container.encode(rawValue)
 	}
 }
 
+extension Id: Hashable, CustomStringConvertible, IdType where RawType: RawIdType {}
+
 extension Id: CreatableIdType where RawType: CreatableRawIdType {
 	public init() {
 		rawValue = .unique()
 	}
 }
+
+extension Id where RawType == Unidentified {
+	public static var unidentified: Id { return .init(rawValue: Unidentified()) }
+}