Add parsing invariant structure even though I do not have a solid enough use-case to implement an invariant fully just yet.

JSONAPI.playground/Pages/Test Library.xcplaygroundpage/Contents.swift

@@ -13,7 +13,7 @@ Please enjoy these examples, but allow me the forced casting and the lack of err
 // MARK: - Literal Expressibility
 // The JSONAPITestLib provides literal expressibility for key types to
 // make creating tests easier
-let dog = Dog(id: "1234", attributes: Dog.Attributes(name: "Buddy"), relationships: Dog.Relationships(owner: nil))
+let dog = Dog(id: "1234", attributes: Dog.Attributes(name: "Buddy"), relationships: Dog.Relationships(owner: nil), meta: .none, links: .none)
 
 // MARK: - JSON API structure checking
 // The JSONAPITestLib provides a `check` function for each Entity type

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

@@ -13,7 +13,7 @@ let dogFromCode = try! Dog(name: "Buddy", owner: nil)
 
 typealias SingleDogDocument = JSONAPI.Document<SingleResourceBody<Dog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, UnknownJSONAPIError>
 
-let singleDogDocument = SingleDogDocument(body: SingleResourceBody(entity: dogFromCode))
+let singleDogDocument = SingleDogDocument(apiDescription: .none, body: .init(entity: dogFromCode), includes: .none, meta: .none, links: .none)
 
 let singleDogData = try! JSONEncoder().encode(singleDogDocument)
 
@@ -24,13 +24,13 @@ let dogFromData = dogResponse.body.primaryData?.value
 // MARK: - Create a request or response with multiple people and dogs and houses included
 let personIds = [Person.Identifier(), Person.Identifier()]
 let dogs = try! [Dog(name: "Buddy", owner: personIds[0]), Dog(name: "Joy", owner: personIds[0]), Dog(name: "Travis", owner: personIds[1])]
-let houses = [House(), House()]
+let houses = [House(attributes: .none, relationships: .none, meta: .none, links: .none), House(attributes: .none, relationships: .none, meta: .none, links: .none)]
 let people = try! [Person(id: personIds[0], name: ["Gary", "Doe"], favoriteColor: "Orange-Red", friends: [], dogs: [dogs[0], dogs[1]], home: houses[0]), Person(id: personIds[1], name: ["Elise", "Joy"], favoriteColor: "Red", friends: [], dogs: [dogs[2]], home: houses[1])]
 
 typealias BatchPeopleDocument = JSONAPI.Document<ManyResourceBody<Person>, NoMetadata, NoLinks, Include2<Dog, House>, NoAPIDescription, UnknownJSONAPIError>
 
 let includes = dogs.map { BatchPeopleDocument.Include($0) } + houses.map { BatchPeopleDocument.Include($0) }
-let batchPeopleDocument = BatchPeopleDocument(body: .init(entities: people), includes: .init(values: includes))
+let batchPeopleDocument = BatchPeopleDocument(apiDescription: .none, body: .init(entities: people), includes: .init(values: includes), meta: .none, links: .none)
 let batchPeopleData = try! JSONEncoder().encode(batchPeopleDocument)
 
 // MARK: - Parse a request or response body with multiple people in it and dogs and houses included

JSONAPI.playground/Sources/Entities.swift

@@ -23,8 +23,10 @@ extension String: CreatableRawIdType {
 	}
 }
 
-// MARK: - Entity typealias for convenience
+// MARK: - typealiases for convenience
 public typealias ExampleEntity<Description: EntityDescription> = Entity<Description, NoMetadata, NoLinks, String>
+public typealias ToOne<E: Identifiable> = ToOneRelationship<E, NoMetadata, NoLinks>
+public typealias ToMany<E: Relatable> = ToManyRelationship<E, NoMetadata, NoLinks>
 
 // MARK: - A few resource objects (entities)
 public enum PersonDescription: EntityDescription {
@@ -46,11 +48,11 @@ public enum PersonDescription: EntityDescription {
 	}
 	
 	public struct Relationships: JSONAPI.Relationships {
-		public let friends: ToManyRelationship<Person>
-		public let dogs: ToManyRelationship<Dog>
-		public let home: ToOneRelationship<House>
+		public let friends: ToMany<Person>
+		public let dogs: ToMany<Dog>
+		public let home: ToOne<House>
 
-		public init(friends: ToManyRelationship<Person>, dogs: ToManyRelationship<Dog>, home: ToOneRelationship<House>) {
+		public init(friends: ToMany<Person>, dogs: ToMany<Dog>, home: ToOne<House>) {
 			self.friends = friends
 			self.dogs = dogs
 			self.home = home
@@ -62,7 +64,7 @@ public typealias Person = ExampleEntity<PersonDescription>
 
 public extension Entity where Description == PersonDescription, MetaType == NoMetadata, LinksType == NoLinks, 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)))
+		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)), meta: .none, links: .none)
 	}
 }
 
@@ -79,9 +81,9 @@ public enum DogDescription: EntityDescription {
 	}
 
 	public struct Relationships: JSONAPI.Relationships {
-		public let owner: ToOneRelationship<Person?>
+		public let owner: ToOne<Person?>
 
-		public init(owner: ToOneRelationship<Person?>) {
+		public init(owner: ToOne<Person?>) {
 			self.owner = owner
 		}
 	}
@@ -91,11 +93,11 @@ public typealias Dog = ExampleEntity<DogDescription>
 
 public extension Entity where Description == DogDescription, MetaType == NoMetadata, LinksType == NoLinks, 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)))
+		self = try Dog(attributes: .init(name: .init(rawValue: name)), relationships: DogDescription.Relationships(owner: .init(entity: owner)), meta: .none, links: .none)
 	}
 
 	public init(name: String, owner: Person.Id) throws {
-		self = try Dog(attributes: .init(name: .init(rawValue: name)), relationships: .init(owner: .init(id: owner)))
+		self = try Dog(attributes: .init(name: .init(rawValue: name)), relationships: .init(owner: .init(id: owner)), meta: .none, links: .none)
 	}
 }
 

Package.resolved

@@ -1,15 +1,7 @@
 {
   "object": {
     "pins": [
-      {
-        "package": "Result",
-        "repositoryURL": "https://github.com/mattpolzin/Result",
-        "state": {
-          "branch": "master",
-          "revision": "b98e238da6ea030fa7862ae6fd6500552370019c",
-          "version": null
-        }
-      }
+
     ]
   },
   "version": 1

Package.swift

@@ -14,13 +14,11 @@ let package = Package(
 			targets: ["JSONAPITestLib"])
     ],
     dependencies: [
-		// antitypical/Result without the Foundation requirement:
-        .package(url: "https://github.com/mattpolzin/Result", .branch("master"))
     ],
     targets: [
         .target(
             name: "JSONAPI",
-            dependencies: ["Result"]),
+            dependencies: []),
 		.target(
 			name: "JSONAPITestLib",
 			dependencies: ["JSONAPI"]),

README.md

@@ -52,8 +52,8 @@ Note that Playground support for importing non-system Frameworks is still a bit
 
 #### Relationship Object
 - [x] `data`
-- [ ] `links`
-- [ ] `meta`
+- [x] `links`
+- [x] `meta`
 
 #### Links Object
 - [x] `href`
@@ -67,7 +67,7 @@ Note that Playground support for importing non-system Frameworks is still a bit
 ### JSONAPITestLib
 #### Entity Validator
 - [x] Disallow optional array in `Attribute` (should be empty array, not `null`).
-- [x] Only allow `TransformedAttribute` and its derivatives within `Attributes` struct.
+- [x] Only allow `TransformedAttribute` and its derivatives as stored properties within `Attributes` struct. Computed properties can still be any type because they do not get encoded or decoded.
 - [x] Only allow `ToManyRelationship` and `ToOneRelationship` within `Relationships` struct.
 
 ### Potential Improvements
@@ -186,9 +186,11 @@ Note that I am assuming an unidentified person is a "new" person. I suspect that
 
 There are two types of `Relationships`: `ToOneRelationship` and `ToManyRelationship`. An `EntityDescription`'s `Relationships` type can contain any number of `Relationship` properties of either of these types. Do not store anything other than `Relationship` properties in the `Relationships` struct of an `EntityDescription`.
 
-To describe a relationship that may be omitted (i.e. the key is not even present in the JSON object), you make the entire `ToOneRelationship` or `ToManyRelationship` optional. However, this is not recommended because you can also represent optional relationships as nullable which means the key is always present. A `ToManyRelationship` can naturally represent the absence of related values with an empty array, so `ToManyRelationship` does not support nullability at all. A `ToOneRelationship` can be marked as nullable (i.e. the value might be `null` or it might be a resource identifier) like this:
+In addition to identifying entities by Id and type, `Relationships` can contain `Meta` or `Links` that follow the same rules as [`Meta`](#jsonapimeta) and [`Links`](#jsonapilinks) elsewhere in the JSON API Document.
+
+To describe a relationship that may be omitted (i.e. the key is not even present in the JSON object), you make the entire `ToOneRelationship` or `ToManyRelationship` optional. However, this is not recommended because you can also represent optional relationships as nullable which means the key is always present. A `ToManyRelationship` can naturally represent the absence of related values with an empty array, so `ToManyRelationship` does not support nullability at all. A `ToOneRelationship` can be marked as nullable (i.e. the value could be either `null` or a resource identifier) like this:
 ```
-let nullableRelative: ToOneRelationship<Person?>
+let nullableRelative: ToOneRelationship<Person?, NoMetadata, NoLinks>
 ```
 
 An entity that does not have relationships can be described by adding the following to an `EntityDescription`:
@@ -271,6 +273,23 @@ public var fullName: Attribute<String> {
 }
 ```
 
+### Copying `Entities`
+`Entity` is a value type, so copying is its default behavior. There are two common mutations you might want to make when copying an `Entity`:
+1. Assigning a new `Identifier` to the copy of an identified `Entity`.
+2. Assigning a new `Identifier` to the copy of an unidentified `Entity`.
+
+The above can be accomplished with code like the following:
+
+```
+// use case 1
+let person1 = person.withNewIdentifier()
+
+// use case 2
+let newlyIdentifiedPerson1 = unidentifiedPerson.identified(byType: String.self)
+
+let newlyIdentifiedPerson2 = unidentifiedPerson.identified(by: "2232")
+```
+
 ### `JSONAPI.Document`
 
 The entirety of a JSON API request or response is encoded or decoded from- or to a `Document`. As an example, a JSON API response containing one `Person` and no included entities could be decoded as follows:

Sources/JSONAPI/Document/Document.swift

@@ -66,8 +66,13 @@ public struct Document<PrimaryResourceBody: JSONAPI.ResourceBody, MetaType: JSON
 			guard case let .errors(errors, meta: _, links: _) = self else { return nil }
 			return errors
 		}
+
+		public var data: Data? {
+			guard case let .data(data) = self else { return nil }
+			return data
+		}
 		
-		public var primaryData: PrimaryResourceBody? {
+		public var primaryResource: PrimaryResourceBody? {
 			guard case let .data(data) = self else { return nil }
 			return data.primary
 		}
@@ -110,7 +115,7 @@ public struct Document<PrimaryResourceBody: JSONAPI.ResourceBody, MetaType: JSON
 		self.apiDescription = apiDescription
 	}
 }
-
+/*
 extension Document where IncludeType == NoIncludes {
 	public init(apiDescription: APIDescription, body: PrimaryResourceBody, meta: MetaType, links: LinksType) {
 		self.init(apiDescription: apiDescription, body: body, includes: .none, meta: meta, links: links)
@@ -182,6 +187,7 @@ extension Document where IncludeType == NoIncludes, MetaType == NoMetadata, Link
 		self.init(apiDescription: .none, body: body)
 	}
 }
+*/
 
 extension Document {
 	private enum RootCodingKeys: String, CodingKey {

Sources/JSONAPI/Document/Includes.swift

@@ -115,4 +115,11 @@ extension Includes where I: _Poly6 {
 }
 
 // MARK: - 7 includes
+public typealias Include7 = Poly7
+extension Includes where I: _Poly7 {
+	public subscript(_ lookup: I.G.Type) -> [I.G] {
+		return values.compactMap { $0.g }
+	}
+}
+
 // MARK: - 8 includes

Sources/JSONAPI/EncodingError.swift

@@ -0,0 +1,14 @@
+//
+//  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/Invariants/ParsingInvariant.swift

@@ -0,0 +1,76 @@
+//
+//  ParsingInvariant.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 12/24/18.
+//
+
+/// An Error produced when an invariant fails.
+public enum InvariantError: Swift.Error {
+	case failure(description: String)
+}
+
+/// Set a reaction to a particular type of invariant failure.
+/// `Warning` and `Quiet` will take a default strategy for handling
+/// the invariant and parsing will not fail. `Error` will cause parsing
+/// to fail due to the given invariant failing.
+public protocol IReaction {
+	/// Perform the given Invariant strategy.
+	static func trigger(invariant: InvariantType.Type) throws
+}
+
+public enum Invariant {
+	/// Used to indicate an invariant failure shoud be considered an error.
+	/// Parsing will fail if an Error invariant fails.
+	public enum Error: IReaction {
+		public static func trigger(invariant: InvariantType.Type) throws {
+			throw InvariantError.failure(description: String(describing: invariant))
+		}
+	}
+
+	/// Used to indicate an invariant failure should be considered a warning.
+	/// The invariant description will be printed to the console but parsing
+	/// will not fail. A default strategy for addressing the invariant will
+	/// be taken. See the given invariant's documentation for details.
+	public enum Warning: IReaction {
+		public static func trigger(invariant: InvariantType.Type) throws {
+			print("**WARN** \(String(describing: invariant))")
+		}
+	}
+
+	/// Used to indicate an invariant failures should be considered inconsequential.
+	/// Parsing will continue and a default strategy for addressing the invariant
+	/// will be taken. See the given invariant's documentation for details.
+	public enum Quiet: IReaction {
+		public static func trigger(invariant: InvariantType.Type) throws {}
+	}
+
+	/// A strategy pairs an invariant type with the desired reaction.
+	public enum Strategy<IType: InvariantType, IReaction: JSONAPI.IReaction>: IStrategy {}
+}
+
+public protocol InvariantType {}
+
+public protocol IStrategy {
+	associatedtype IType: InvariantType
+	associatedtype IReaction: JSONAPI.IReaction
+}
+
+// TODO: Does this invariant make sense? I can't actually know whether arbitrary
+// Id types are "empty" so I think I started down this path without having fully
+// thought through it. Perhaps there are still other obvious invariants to add
+// though.
+public protocol RelationshipNonEmptyIdInvariant: IStrategy where IType == Invariant.Relationships.NonEmptyId {}
+
+extension Invariant {
+	public enum Relationships {
+
+		/// The Empty Id Invariant holds as long as a relationships's Id
+		/// is not "empty"
+		public enum NonEmptyId: InvariantType {}
+
+		public enum Strategies<NonEmptyId: RelationshipNonEmptyIdInvariant> {}
+	}
+}
+
+// Would be used like `ToOneRelationship<OtherEntity, Invariant.Relationships.Strategies<Invariant.Strategy<Invariant.Relationships.NonEmptyId, Invariant.Error>>>`

Sources/JSONAPI/Resource/Attribute.swift

@@ -8,8 +8,10 @@
 public protocol AttributeType: Codable {
 }
 
+// MARK: TransformedAttribute
+/// A TransformedAttribute takes a Codable type and attempts to turn it into another type.
 public struct TransformedAttribute<RawValue: Codable, Transformer: JSONAPI.Transformer>: AttributeType where Transformer.From == RawValue {
-	private let rawValue: RawValue
+	let rawValue: RawValue
 	
 	public let value: Transformer.To
 	
@@ -19,6 +21,15 @@ public struct TransformedAttribute<RawValue: Codable, Transformer: JSONAPI.Trans
 	}
 }
 
+// MARK: ValidatedAttribute
+/// A ValidatedAttribute does not transform its raw value, but it throws
+/// an error if the raw value does not match expectations.
+public typealias ValidatedAttribute<RawValue: Codable, Validator: JSONAPI.Validator> = TransformedAttribute<RawValue, Validator> where RawValue == Validator.From
+
+// MARK: Attribute
+/// An Attribute simply represents a type that can be encoded and decoded.
+public typealias Attribute<T: Codable> = TransformedAttribute<T, IdentityTransformer<T>>
+
 extension TransformedAttribute where Transformer: ReversibleTransformer {
 	public init(transformedValue: Transformer.To) throws {
 		self.value = transformedValue
@@ -43,10 +54,6 @@ extension TransformedAttribute where Transformer == IdentityTransformer<RawValue
 	}
 }
 
-public typealias ValidatedAttribute<RawValue: Codable, Validator: JSONAPI.Validator> = TransformedAttribute<RawValue, Validator> where RawValue == Validator.From
-
-public typealias Attribute<T: Codable> = TransformedAttribute<T, IdentityTransformer<T>>
-
 // MARK: - Codable
 extension TransformedAttribute {
 	public init(from decoder: Decoder) throws {
@@ -73,15 +80,7 @@ extension TransformedAttribute {
 	
 	public func encode(to encoder: Encoder) throws {
 		var container = encoder.singleValueContainer()
-		
-		// See note in decode above about the weirdness
-		// going on here.
-		let anyNil: Any? = nil
-		if let _ = anyNil as? Transformer.From,
-			(rawValue as Any?) == nil {
-			try container.encodeNil()
-		}
-		
+
 		try container.encode(rawValue)
 	}
 }

Sources/JSONAPI/Resource/Entity.swift

@@ -26,23 +26,31 @@ public struct NoAttributes: Attributes {
 	public static var none: NoAttributes { return .init() }
 }
 
+/// Something that is JSONTyped provides a String representation
+/// of its type.
+public protocol JSONTyped {
+	static var type: String { get }
+}
+
+/// An `EntityProxyDescription` is an `EntityDescription`
+/// without Codable conformance.
+public protocol EntityProxyDescription: JSONTyped {
+	associatedtype Attributes: Equatable
+	associatedtype Relationships: Equatable
+}
+
 /// An `EntityDescription` describes a JSON API
 /// Resource Object. The Resource Object
 /// itself is encoded and decoded as an
 /// `Entity`, which gets specialized on an
 /// `EntityDescription`.
-public protocol EntityDescription {
-	associatedtype Attributes: JSONAPI.Attributes
-	associatedtype Relationships: JSONAPI.Relationships
-	
-	static var type: String { get }
-}
+public protocol EntityDescription: EntityProxyDescription where Attributes: JSONAPI.Attributes, Relationships: JSONAPI.Relationships {}
 
 /// EntityProxy is a protocol that can be used to create
 /// types that _act_ like Entities but cannot be encoded
 /// or decoded as Entities.
-public protocol EntityProxy: Equatable {
-	associatedtype Description: EntityDescription
+public protocol EntityProxy: Equatable, JSONTyped {
+	associatedtype Description: EntityProxyDescription
 	associatedtype EntityRawIdType: JSONAPI.MaybeRawId
 
 	typealias Id = JSONAPI.Id<EntityRawIdType, Self>
@@ -71,7 +79,9 @@ extension EntityProxy {
 /// EntityType is the protocol that Entity conforms to. This
 /// protocol lets other types accept any Entity as a generic
 /// specialization.
-public protocol EntityType: EntityProxy, PrimaryResource {
+public protocol EntityType: EntityProxy, PrimaryResource where Description: EntityDescription {
+	associatedtype Meta: JSONAPI.Meta
+	associatedtype Links: JSONAPI.Links
 }
 
 public protocol IdentifiableEntityType: EntityType, Relatable where EntityRawIdType: JSONAPI.RawIdType {}
@@ -81,6 +91,10 @@ public protocol IdentifiableEntityType: EntityType, Relatable where EntityRawIdT
 /// "Resource Object."
 /// See https://jsonapi.org/format/#document-resource-objects
 public struct Entity<Description: JSONAPI.EntityDescription, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links, EntityRawIdType: JSONAPI.MaybeRawId>: EntityType {
+
+	public typealias Meta = MetaType
+	public typealias Links = LinksType
+
 	/// The `Entity`'s Id. This can be of type `Unidentified` if
 	/// the entity is being created clientside and the
 	/// server is being asked to create a unique Id. Otherwise,
@@ -108,9 +122,8 @@ public struct Entity<Description: JSONAPI.EntityDescription, MetaType: JSONAPI.M
 	}
 }
 
-extension Entity: IdentifiableEntityType, Relatable, WrappedRelatable where EntityRawIdType: JSONAPI.RawIdType {
+extension Entity: Identifiable, IdentifiableEntityType, Relatable where EntityRawIdType: JSONAPI.RawIdType {
 	public typealias Identifier = Entity.Id
-	public typealias WrappedIdentifier = Identifier
 }
 
 extension Entity: CustomStringConvertible {
@@ -140,6 +153,7 @@ extension Entity where EntityRawIdType == Unidentified {
 	}
 }
 
+/*
 extension Entity where Description.Attributes == NoAttributes {
 	public init(id: Entity.Id, relationships: Description.Relationships, meta: MetaType, links: LinksType) {
 		self.init(id: id, attributes: NoAttributes(), relationships: relationships, meta: meta, links: links)
@@ -326,6 +340,12 @@ extension Entity where MetaType == NoMetadata, EntityRawIdType: CreatableRawIdTy
 	}
 }
 
+extension Entity where MetaType == NoMetadata, EntityRawIdType == Unidentified {
+	public init(attributes: Description.Attributes, relationships: Description.Relationships, links: LinksType) {
+		self.init(attributes: attributes, relationships: relationships, meta: .none, links: links)
+	}
+}
+
 extension Entity where LinksType == NoLinks {
 	public init(id: Entity.Id, attributes: Description.Attributes, relationships: Description.Relationships, meta: MetaType) {
 		self.init(id: id, attributes: attributes, relationships: relationships, meta: meta, links: .none)
@@ -338,6 +358,12 @@ extension Entity where LinksType == NoLinks, EntityRawIdType: CreatableRawIdType
 	}
 }
 
+extension Entity where LinksType == NoLinks, EntityRawIdType == Unidentified {
+	public init(attributes: Description.Attributes, relationships: Description.Relationships, meta: MetaType) {
+		self.init(attributes: attributes, relationships: relationships, meta: meta, links: .none)
+	}
+}
+
 extension Entity where MetaType == NoMetadata, LinksType == NoLinks {
 	public init(id: Entity.Id, attributes: Description.Attributes, relationships: Description.Relationships) {
 		self.init(id: id, attributes: attributes, relationships: relationships, meta: .none, links: .none)
@@ -350,12 +376,55 @@ extension Entity where MetaType == NoMetadata, LinksType == NoLinks, EntityRawId
 	}
 }
 
+extension Entity where MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == Unidentified {
+	public init(attributes: Description.Attributes, relationships: Description.Relationships) {
+		self.init(attributes: attributes, relationships: relationships, meta: .none, links: .none)
+	}
+}
+*/
+
 // MARK: Pointer for Relationships use.
 public extension Entity where EntityRawIdType: JSONAPI.RawIdType {
+
+	/// An Entity.Pointer is a `ToOneRelationship` with no metadata or links.
+	/// This is just a convenient way to reference an Entity so that
+	/// other Entities' Relationships can be built up from it.
+	public typealias Pointer = ToOneRelationship<Entity, NoMetadata, NoLinks>
+
+	/// Entity.Pointers is a `ToManyRelationship` with no metadata or links.
+	/// This is just a convenient way to reference a bunch of Entities so
+	/// that other Entities' Relationships can be built up from them.
+	public typealias Pointers = ToManyRelationship<Entity, NoMetadata, NoLinks>
+
 	/// Get a pointer to this entity that can be used as a
 	/// relationship to another entity.
-	public var pointer: ToOneRelationship<Entity> {
-		return ToOneRelationship(entity: self)
+	public var pointer: Pointer {
+		return Pointer(entity: self)
+	}
+
+	public func pointer<MType: JSONAPI.Meta, LType: JSONAPI.Links>(withMeta meta: MType, links: LType) -> ToOneRelationship<Entity, MType, LType> {
+		return ToOneRelationship(entity: self, meta: meta, links: links)
+	}
+}
+
+// MARK: Identifying Unidentified Entities
+public extension Entity where EntityRawIdType == Unidentified {
+	/// Create a new Entity from this one with a newly created
+	/// unique Id of the given type.
+	public func identified<RawIdType: CreatableRawIdType>(byType: RawIdType.Type) -> Entity<Description, MetaType, LinksType, RawIdType> {
+		return .init(attributes: attributes, relationships: relationships, meta: meta, links: links)
+	}
+
+	/// Create a new Entity from this one with the given Id.
+	public func identified<RawIdType: JSONAPI.RawIdType>(by id: RawIdType) -> Entity<Description, MetaType, LinksType, RawIdType> {
+		return .init(id: Entity<Description, MetaType, LinksType, RawIdType>.Identifier(rawValue: id), attributes: attributes, relationships: relationships, meta: meta, links: links)
+	}
+}
+
+public extension Entity where EntityRawIdType: CreatableRawIdType {
+	/// Create a copy of this Entity with a new unique Id.
+	public func withNewIdentifier() -> Entity {
+		return Entity(attributes: attributes, relationships: relationships, meta: meta, links: links)
 	}
 }
 
@@ -379,8 +448,19 @@ public extension EntityProxy {
 	/// allows you to write `entity[\.propertyName]` instead
 	/// of `entity.relationships.propertyName`.
 	subscript<T, TFRM: Transformer, U>(_ path: KeyPath<Description.Attributes, TransformedAttribute<T, TFRM>?>) -> U? where TFRM.To == U? {
+		// Implementation Note: Handles Transform that returns optional
+		// type.
 		return attributes[keyPath: path].flatMap { $0.value }
 	}
+
+	/// Access the computed attribute at the given keypath. This just
+	/// allows you to write `entity[\.propertyName]` instead
+	/// of `entity.relationships.propertyName`.
+	subscript<T>(_ path: KeyPath<Description.Attributes, T>) -> T {
+		// Implementation Note: Handles attributes that are not
+		// AttributeType. These should only exist as computed properties.
+		return attributes[keyPath: path]
+	}
 }
 
 // MARK: Relationship Access
@@ -388,16 +468,41 @@ public extension EntityProxy {
 	/// Access to an Id of a `ToOneRelationship`.
 	/// This allows you to write `entity ~> \.other` instead
 	/// of `entity.relationships.other.id`.
-	public static func ~><OtherEntity: OptionalRelatable>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity>>) -> OtherEntity.WrappedIdentifier {
+	public static func ~><OtherEntity: Identifiable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>>) -> OtherEntity.Identifier {
 		return entity.relationships[keyPath: path].id
 	}
 
+	/// Access to an Id of an optional `ToOneRelationship`.
+	/// This allows you to write `entity ~> \.other` instead
+	/// of `entity.relationships.other?.id`.
+	public static func ~><OtherEntity: OptionalRelatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>?>) -> OtherEntity.Identifier {
+		// Implementation Note: This signature applies to `ToOneRelationship<E?, _, _>?`
+		// whereas the one below applies to `ToOneRelationship<E, _, _>?`
+		return entity.relationships[keyPath: path]?.id
+	}
+
+	/// Access to an Id of an optional `ToOneRelationship`.
+	/// This allows you to write `entity ~> \.other` instead
+	/// of `entity.relationships.other?.id`.
+	public static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>?>) -> OtherEntity.Identifier? {
+		// Implementation Note: This signature applies to `ToOneRelationship<E, _, _>?`
+		// whereas the one above applies to `ToOneRelationship<E?, _, _>?`
+		return entity.relationships[keyPath: path]?.id
+	}
+
 	/// Access to all Ids of a `ToManyRelationship`.
 	/// This allows you to write `entity ~> \.others` instead
 	/// of `entity.relationships.others.ids`.
-	public static func ~><OtherEntity: Relatable>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity>>) -> [OtherEntity.Identifier] {
+	public static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity, MType, LType>>) -> [OtherEntity.Identifier] {
 		return entity.relationships[keyPath: path].ids
 	}
+
+	/// Access to all Ids of an optional `ToManyRelationship`.
+	/// This allows you to write `entity ~> \.others` instead
+	/// of `entity.relationships.others?.ids`.
+	public static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity, MType, LType>?>) -> [OtherEntity.Identifier]? {
+		return entity.relationships[keyPath: path]?.ids
+	}
 }
 
 infix operator ~>

Sources/JSONAPI/Resource/Id.swift

@@ -34,13 +34,31 @@ public struct Unidentified: MaybeRawId, CustomStringConvertible {
 	public var description: String { return "Unidentified" }
 }
 
-public protocol MaybeId: Codable {
-	associatedtype EntityType: JSONAPI.EntityProxy
+public protocol OptionalId: Codable {
+	associatedtype IdentifiableType: JSONAPI.JSONTyped
 	associatedtype RawType: MaybeRawId
+
+	var rawValue: RawType { get }
+	init(rawValue: RawType)
 }
 
-public protocol IdType: MaybeId, CustomStringConvertible, Hashable where RawType: RawIdType {
-	var rawValue: RawType { get }
+public protocol IdType: OptionalId, CustomStringConvertible, Hashable where RawType: RawIdType {}
+
+extension Optional: MaybeRawId where Wrapped: Codable & Equatable {}
+extension Optional: OptionalId where Wrapped: IdType {
+	public typealias IdentifiableType = Wrapped.IdentifiableType
+	public typealias RawType = Wrapped.RawType?
+
+	public var rawValue: Wrapped.RawType? {
+		guard case .some(let value) = self else {
+			return nil
+		}
+		return value.rawValue
+	}
+
+	public init(rawValue: Wrapped.RawType?) {
+		self = rawValue.map { Wrapped(rawValue: $0) }
+	}
 }
 
 public extension IdType {
@@ -53,7 +71,7 @@ public protocol CreatableIdType: IdType {
 
 /// An Entity ID. These IDs can be encoded to or decoded from
 /// JSON API IDs.
-public struct Id<RawType: MaybeRawId, EntityType: JSONAPI.EntityProxy>: Codable, Equatable, MaybeId {
+public struct Id<RawType: MaybeRawId, IdentifiableType: JSONAPI.JSONTyped>: Equatable, OptionalId {
 
 	public let rawValue: RawType
 	
@@ -63,7 +81,8 @@ public struct Id<RawType: MaybeRawId, EntityType: JSONAPI.EntityProxy>: Codable,
 
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.singleValueContainer()
-		rawValue = try container.decode(RawType.self)
+		let rawValue = try container.decode(RawType.self)
+		self.init(rawValue: rawValue)
 	}
 
 	public func encode(to encoder: Encoder) throws {
@@ -72,7 +91,11 @@ public struct Id<RawType: MaybeRawId, EntityType: JSONAPI.EntityProxy>: Codable,
 	}
 }
 
-extension Id: Hashable, CustomStringConvertible, IdType where RawType: RawIdType {}
+extension Id: Hashable, CustomStringConvertible, IdType where RawType: RawIdType {
+	public static func id(from rawValue: RawType) -> Id<RawType, IdentifiableType> {
+		return Id(rawValue: rawValue)
+	}
+}
 
 extension Id: CreatableIdType where RawType: CreatableRawIdType {
 	public init() {

Sources/JSONAPI/Resource/Poly.swift

@@ -5,8 +5,6 @@
 //  Created by Mathew Polzin on 11/22/18.
 //
 
-import Result
-
 /// Poly is a protocol to which types that
 /// are polymorphic belong to. Specifically,
 /// Poly1, Poly2, Poly3, etc. types conform
@@ -28,7 +26,7 @@ private func decode<Entity: JSONAPI.EntityType>(_ type: Entity.Type, from contai
 	} catch (let err) {
 		ret = .failure(DecodingError.typeMismatch(Entity.Description.self,
 												  .init(codingPath: container.codingPath,
-														debugDescription: err.localizedDescription,
+														debugDescription: String(describing: err),
 														underlyingError: err)))
 	}
 	return ret
@@ -646,3 +644,158 @@ extension Poly6: CustomStringConvertible {
 		return "Poly(\(str))"
 	}
 }
+
+// MARK: - 7 types
+public protocol _Poly7: _Poly6 {
+	associatedtype G: EntityType
+	var g: G? { get }
+
+	init(_ g: G)
+}
+
+public extension _Poly7 {
+	subscript(_ lookup: G.Type) -> G? {
+		return g
+	}
+}
+
+public enum Poly7<A: EntityType, B: EntityType, C: EntityType, D: EntityType, E: EntityType, F: EntityType, G: EntityType>: _Poly7 {
+	case a(A)
+	case b(B)
+	case c(C)
+	case d(D)
+	case e(E)
+	case f(F)
+	case g(G)
+
+	public var a: A? {
+		guard case let .a(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ a: A) {
+		self = .a(a)
+	}
+
+	public var b: B? {
+		guard case let .b(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ b: B) {
+		self = .b(b)
+	}
+
+	public var c: C? {
+		guard case let .c(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ c: C) {
+		self = .c(c)
+	}
+
+	public var d: D? {
+		guard case let .d(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ d: D) {
+		self = .d(d)
+	}
+
+	public var e: E? {
+		guard case let .e(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ e: E) {
+		self = .e(e)
+	}
+
+	public var f: F? {
+		guard case let .f(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ f: F) {
+		self = .f(f)
+	}
+
+	public var g: G? {
+		guard case let .g(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ g: G) {
+		self = .g(g)
+	}
+
+	public init(from decoder: Decoder) throws {
+		let container = try decoder.singleValueContainer()
+
+		let attempts = [
+			try decode(A.self, from: container).map { Poly7.a($0) },
+			try decode(B.self, from: container).map { Poly7.b($0) },
+			try decode(C.self, from: container).map { Poly7.c($0) },
+			try decode(D.self, from: container).map { Poly7.d($0) },
+			try decode(E.self, from: container).map { Poly7.e($0) },
+			try decode(F.self, from: container).map { Poly7.f($0) },
+			try decode(G.self, from: container).map { Poly7.g($0) }]
+
+		let maybeVal: Poly7<A, B, C, D, E, F, G>? = attempts
+			.compactMap { $0.value }
+			.first
+
+		guard let val = maybeVal else {
+			throw EncodingError.invalidValue(Poly7<A, B, C, D, E, F, G>.self, .init(codingPath: decoder.codingPath, debugDescription: "Failed to find an include of the expected type. Attempts: \(attempts.map { $0.error }.compactMap { $0 })"))
+		}
+
+		self = val
+	}
+
+	public func encode(to encoder: Encoder) throws {
+		var container = encoder.singleValueContainer()
+
+		switch self {
+		case .a(let a):
+			try container.encode(a)
+		case .b(let b):
+			try container.encode(b)
+		case .c(let c):
+			try container.encode(c)
+		case .d(let d):
+			try container.encode(d)
+		case .e(let e):
+			try container.encode(e)
+		case .f(let f):
+			try container.encode(f)
+		case .g(let g):
+			try container.encode(g)
+		}
+	}
+}
+
+extension Poly7: CustomStringConvertible {
+	public var description: String {
+		let str: String
+		switch self {
+		case .a(let a):
+			str = String(describing: a)
+		case .b(let b):
+			str = String(describing: b)
+		case .c(let c):
+			str = String(describing: c)
+		case .d(let d):
+			str = String(describing: d)
+		case .e(let e):
+			str = String(describing: e)
+		case .f(let f):
+			str = String(describing: f)
+		case .g(let g):
+			str = String(describing: g)
+		}
+
+		return "Poly(\(str))"
+	}
+}

Sources/JSONAPI/Resource/Relationship.swift

@@ -5,30 +5,59 @@
 //  Created by Mathew Polzin on 8/31/18.
 //
 
-public protocol RelationshipType: Codable {}
+public protocol RelationshipType {
+	associatedtype LinksType
+	associatedtype MetaType
+
+	var links: LinksType { get }
+	var meta: MetaType { get }
+}
 
 /// An Entity relationship that can be encoded to or decoded from
 /// a JSON API "Resource Linkage."
 /// See https://jsonapi.org/format/#document-resource-object-linkage
 /// A convenient typealias might make your code much more legible: `One<EntityDescription>`
-public struct ToOneRelationship<Relatable: JSONAPI.OptionalRelatable>: RelationshipType, Equatable {
+public struct ToOneRelationship<Identifiable: JSONAPI.Identifiable, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>: RelationshipType, Equatable {
 
-	public let id: Relatable.WrappedIdentifier
+	public let id: Identifiable.Identifier
 
-	public init(id: Relatable.WrappedIdentifier) {
+	public let meta: MetaType
+	public let links: LinksType
+
+	public init(id: Identifiable.Identifier, meta: MetaType, links: LinksType) {
 		self.id = id
+		self.meta = meta
+		self.links = links
 	}
 }
 
-extension ToOneRelationship where Relatable.WrappedIdentifier == Relatable.Identifier {
-	public init<E: EntityType>(entity: E) where E.Description == Relatable.Description, E.Id == Relatable.Identifier {
-		id = entity.id
+extension ToOneRelationship where MetaType == NoMetadata, LinksType == NoLinks {
+	public init(id: Identifiable.Identifier) {
+		self.init(id: id, meta: .none, links: .none)
 	}
 }
 
-extension ToOneRelationship where Relatable.WrappedIdentifier == Relatable.Identifier? {
-	public init<E: EntityType>(entity: E?) where E.Description == Relatable.Description, E.Id == Relatable.Identifier {
-		id = entity?.id
+extension ToOneRelationship {
+	public init<E: EntityType>(entity: E, meta: MetaType, links: LinksType) where E.Id == Identifiable.Identifier {
+		self.init(id: entity.id, meta: meta, links: links)
+	}
+}
+
+extension ToOneRelationship where MetaType == NoMetadata, LinksType == NoLinks {
+	public init<E: EntityType>(entity: E) where E.Id == Identifiable.Identifier {
+		self.init(id: entity.id, meta: .none, links: .none)
+	}
+}
+
+extension ToOneRelationship where Identifiable: OptionalRelatable {
+	public init<E: EntityType>(entity: E?, meta: MetaType, links: LinksType) where E.Id == Identifiable.Wrapped.Identifier {
+		self.init(id: entity?.id, meta: meta, links: links)
+	}
+}
+
+extension ToOneRelationship where Identifiable: OptionalRelatable, MetaType == NoMetadata, LinksType == NoLinks {
+	public init<E: EntityType>(entity: E?) where E.Id == Identifiable.Wrapped.Identifier {
+		self.init(id: entity?.id, meta: .none, links: .none)
 	}
 }
 
@@ -36,73 +65,105 @@ extension ToOneRelationship where Relatable.WrappedIdentifier == Relatable.Ident
 /// a JSON API "Resource Linkage."
 /// See https://jsonapi.org/format/#document-resource-object-linkage
 /// A convenient typealias might make your code much more legible: `Many<EntityDescription>`
-public struct ToManyRelationship<Relatable: JSONAPI.Relatable>: RelationshipType, Equatable {
+public struct ToManyRelationship<Relatable: JSONAPI.Relatable, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>: RelationshipType, Equatable {
 
 	public let ids: [Relatable.Identifier]
 
-	public init(ids: [Relatable.Identifier]) {
+	public let meta: MetaType
+	public let links: LinksType
+
+	public init(ids: [Relatable.Identifier], meta: MetaType, links: LinksType) {
 		self.ids = ids
+		self.meta = meta
+		self.links = links
 	}
 
-	public init<T: JSONAPI.Relatable>(relationships: [ToOneRelationship<T>]) where T.WrappedIdentifier == Relatable.Identifier {
-		ids = relationships.map { $0.id }
+	public init<T: JSONAPI.Identifiable>(pointers: [ToOneRelationship<T, NoMetadata, NoLinks>], meta: MetaType, links: LinksType) where T.Identifier == Relatable.Identifier {
+		ids = pointers.map { $0.id }
+		self.meta = meta
+		self.links = links
 	}
 
-	private init() {
-		ids = []
+	public init<E: EntityType>(entities: [E], meta: MetaType, links: LinksType) where E.Id == Relatable.Identifier {
+		self.init(ids: entities.map { $0.id }, meta: meta, links: links)
 	}
-	
+
+	private init(meta: MetaType, links: LinksType) {
+		self.init(ids: [], meta: meta, links: links)
+	}
+
+	public static func none(withMeta meta: MetaType, links: LinksType) -> ToManyRelationship {
+		return ToManyRelationship(meta: meta, links: links)
+	}
+}
+
+extension ToManyRelationship where MetaType == NoMetadata, LinksType == NoLinks {
+
+	public init(ids: [Relatable.Identifier]) {
+		self.init(ids: ids, meta: .none, links: .none)
+	}
+
+	public init<T: JSONAPI.Identifiable>(pointers: [ToOneRelationship<T, NoMetadata, NoLinks>]) where T.Identifier == Relatable.Identifier {
+		self.init(pointers: pointers, meta: .none, links: .none)
+	}
+
 	public static var none: ToManyRelationship {
-		return .init()
+		return .none(withMeta: .none, links: .none)
+	}
+
+	public init<E: EntityType>(entities: [E]) where E.Id == Relatable.Identifier {
+		self.init(entities: entities, meta: .none, links: .none)
 	}
 }
 
-extension ToManyRelationship {
-	public init<E: EntityType>(entities: [E]) where E.Description == Relatable.Description, E.Id == Relatable.Identifier {
-		ids = entities.map { $0.id }
-	}
+public protocol Identifiable: JSONTyped {
+	associatedtype Identifier: Equatable
 }
 
-/// The WrappedRelatable (a.k.a OptionalRelatable) protocol
-/// describes Optional<T: Relatable> and Relatable types.
-public protocol WrappedRelatable: Codable, Equatable {
-	associatedtype Description: EntityDescription
-	associatedtype Identifier: JSONAPI.IdType
-	associatedtype WrappedIdentifier: Codable, Equatable
-}
-public typealias OptionalRelatable = WrappedRelatable
-
 /// The Relatable protocol describes anything that
 /// has an IdType Identifier
-public protocol Relatable: WrappedRelatable {}
+public protocol Relatable: Identifiable where Identifier: JSONAPI.IdType {
+}
 
-extension Optional: OptionalRelatable where Wrapped: Relatable {
-	public typealias Description = Wrapped.Description
-	public typealias Identifier = Wrapped.Identifier
-	public typealias WrappedIdentifier = Identifier?
+/// OptionalRelatable just describes an Optional
+/// with a Reltable Wrapped type.
+public protocol OptionalRelatable: Identifiable where Identifier == Wrapped.Identifier? {
+	associatedtype Wrapped: JSONAPI.Relatable
+}
+
+extension Optional: Identifiable, OptionalRelatable, JSONTyped where Wrapped: JSONAPI.Relatable {
+	public typealias Identifier = Wrapped.Identifier?
+
+	public static var type: String { return Wrapped.type }
 }
 
 // MARK: Codable
 private enum ResourceLinkageCodingKeys: String, CodingKey {
 	case data = "data"
+	case meta = "meta"
+	case links = "links"
 }
 private enum ResourceIdentifierCodingKeys: String, CodingKey {
 	case id = "id"
 	case entityType = "type"
 }
 
-public enum JSONAPIEncodingError: Swift.Error {
-	case typeMismatch(expected: String, found: String)
-	case illegalEncoding(String)
-	case illegalDecoding(String)
-	case missingOrMalformedMetadata
-	case missingOrMalformedLinks
-}
-
-extension ToOneRelationship {
+extension ToOneRelationship: Codable where Identifiable.Identifier: OptionalId {
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.container(keyedBy: ResourceLinkageCodingKeys.self)
 
+		if let noMeta = NoMetadata() as? MetaType {
+			meta = noMeta
+		} else {
+			meta = try container.decode(MetaType.self, forKey: .meta)
+		}
+
+		if let noLinks = NoLinks() as? LinksType {
+			links = noLinks
+		} else {
+			links = try container.decode(LinksType.self, forKey: .links)
+		}
+
 		// A little trickery follows. If the id is nil, the
 		// container.decode(Identifier.self) will fail even if Identifier
 		// is Optional. However, we can check if decoding nil
@@ -110,7 +171,7 @@ extension ToOneRelationship {
 		// type at which point we can store nil in `id`.
 		let anyNil: Any? = nil
 		if try container.decodeNil(forKey: .data),
-			let val = anyNil as? Relatable.WrappedIdentifier {
+			let val = anyNil as? Identifiable.Identifier {
 			id = val
 			return
 		}
@@ -119,11 +180,11 @@ extension ToOneRelationship {
 		
 		let type = try identifier.decode(String.self, forKey: .entityType)
 		
-		guard type == Relatable.Description.type else {
-			throw JSONAPIEncodingError.typeMismatch(expected: Relatable.Description.type, found: type)
+		guard type == Identifiable.type else {
+			throw JSONAPIEncodingError.typeMismatch(expected: Identifiable.type, found: type)
 		}
 		
-		id = try identifier.decode(Relatable.WrappedIdentifier.self, forKey: .id)
+		id = Identifiable.Identifier(rawValue: try identifier.decode(Identifiable.Identifier.RawType.self, forKey: .id))
 	}
 	
 	public func encode(to encoder: Encoder) throws {
@@ -133,17 +194,46 @@ extension ToOneRelationship {
 			try container.encodeNil(forKey: .data)
 		}
 
+		if MetaType.self != NoMetadata.self {
+			try container.encode(meta, forKey: .meta)
+		}
+
+		if LinksType.self != NoLinks.self {
+			try container.encode(links, forKey: .links)
+		}
+
+		// If id is nil, instead of {id: , type: } we will just
+		// encode `null`
+		let anyNil: Any? = nil
+		let nilId = anyNil as? Identifiable.Identifier
+		guard id != nilId else {
+			try container.encodeNil(forKey: .data)
+			return
+		}
+
 		var identifier = container.nestedContainer(keyedBy: ResourceIdentifierCodingKeys.self, forKey: .data)
 		
-		try identifier.encode(id, forKey: .id)
-		try identifier.encode(Relatable.Description.type, forKey: .entityType)
+		try identifier.encode(id.rawValue, forKey: .id)
+		try identifier.encode(Identifiable.type, forKey: .entityType)
 	}
 }
 
-extension ToManyRelationship {
+extension ToManyRelationship: Codable {
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.container(keyedBy: ResourceLinkageCodingKeys.self)
-		
+
+		if let noMeta = NoMetadata() as? MetaType {
+			meta = noMeta
+		} else {
+			meta = try container.decode(MetaType.self, forKey: .meta)
+		}
+
+		if let noLinks = NoLinks() as? LinksType {
+			links = noLinks
+		} else {
+			links = try container.decode(LinksType.self, forKey: .links)
+		}
+
 		var identifiers = try container.nestedUnkeyedContainer(forKey: .data)
 		
 		var newIds = [Relatable.Identifier]()
@@ -152,24 +242,33 @@ extension ToManyRelationship {
 			
 			let type = try identifier.decode(String.self, forKey: .entityType)
 			
-			guard type == Relatable.Description.type else {
-				throw JSONAPIEncodingError.typeMismatch(expected: Relatable.Description.type, found: type)
+			guard type == Relatable.type else {
+				throw JSONAPIEncodingError.typeMismatch(expected: Relatable.type, found: type)
 			}
 			
-			newIds.append(try identifier.decode(Relatable.Identifier.self, forKey: .id))
+			newIds.append(Relatable.Identifier(rawValue: try identifier.decode(Relatable.Identifier.RawType.self, forKey: .id)))
 		}
 		ids = newIds
 	}
 	
 	public func encode(to encoder: Encoder) throws {
 		var container = encoder.container(keyedBy: ResourceLinkageCodingKeys.self)
+
+		if MetaType.self != NoMetadata.self {
+			try container.encode(meta, forKey: .meta)
+		}
+
+		if LinksType.self != NoLinks.self {
+			try container.encode(links, forKey: .links)
+		}
+
 		var identifiers = container.nestedUnkeyedContainer(forKey: .data)
 		
 		for id in ids {
 			var identifier = identifiers.nestedContainer(keyedBy: ResourceIdentifierCodingKeys.self)
 			
-			try identifier.encode(id, forKey: .id)
-			try identifier.encode(Relatable.Description.type, forKey: .entityType)
+			try identifier.encode(id.rawValue, forKey: .id)
+			try identifier.encode(Relatable.type, forKey: .entityType)
 		}
 	}
 }

Sources/JSONAPI/Result.swift

@@ -0,0 +1,45 @@
+//
+//  Result.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 12/5/18.
+//
+
+enum Result<T, E: Swift.Error> {
+	case success(T)
+	case failure(E)
+
+	var value: T? {
+		guard case .success(let val) = self else {
+			return nil
+		}
+		return val
+	}
+
+	var error: E? {
+		guard case .failure(let err) = self else {
+			return nil
+		}
+		return err
+	}
+
+	func map<U>(_ transform: (T) -> U) -> Result<U, E> {
+		switch self {
+		case .failure(let err):
+			return .failure(err)
+		case .success(let val):
+			return .success(transform(val))
+		}
+	}
+}
+
+extension Result: CustomStringConvertible where T: CustomStringConvertible, E: CustomStringConvertible {
+	var description: String {
+		switch self {
+		case .success(let val):
+			return String(describing: val)
+		case .failure(let err):
+			return String(describing: err)
+		}
+	}
+}

Sources/JSONAPITestLib/Attribute+Literal.swift

@@ -39,6 +39,14 @@ extension TransformedAttribute: ExpressibleByFloatLiteral where RawValue: Expres
 	}
 }
 
+extension Optional: ExpressibleByFloatLiteral where Wrapped: ExpressibleByFloatLiteral {
+	public typealias FloatLiteralType = Wrapped.FloatLiteralType
+
+	public init(floatLiteral value: FloatLiteralType) {
+		self = .some(Wrapped(floatLiteral: value))
+	}
+}
+
 extension TransformedAttribute: ExpressibleByBooleanLiteral where RawValue: ExpressibleByBooleanLiteral, Transformer == IdentityTransformer<RawValue> {
 	public typealias BooleanLiteralType = RawValue.BooleanLiteralType
 
@@ -47,6 +55,14 @@ extension TransformedAttribute: ExpressibleByBooleanLiteral where RawValue: Expr
 	}
 }
 
+extension Optional: ExpressibleByBooleanLiteral where Wrapped: ExpressibleByBooleanLiteral {
+	public typealias BooleanLiteralType = Wrapped.BooleanLiteralType
+
+	public init(booleanLiteral value: BooleanLiteralType) {
+		self = .some(Wrapped(booleanLiteral: value))
+	}
+}
+
 extension TransformedAttribute: ExpressibleByIntegerLiteral where RawValue: ExpressibleByIntegerLiteral, Transformer == IdentityTransformer<RawValue> {
 	public typealias IntegerLiteralType = RawValue.IntegerLiteralType
 
@@ -55,6 +71,14 @@ extension TransformedAttribute: ExpressibleByIntegerLiteral where RawValue: Expr
 	}
 }
 
+extension Optional: ExpressibleByIntegerLiteral where Wrapped: ExpressibleByIntegerLiteral {
+	public typealias IntegerLiteralType = Wrapped.IntegerLiteralType
+
+	public init(integerLiteral value: IntegerLiteralType) {
+		self = .some(Wrapped(integerLiteral: value))
+	}
+}
+
 // regretably, array and dictionary literals are not so easy because Dictionaries and Arrays
 // cannot be turned back into variadic arguments to pass onto the RawValue type's constructor.
 
@@ -79,6 +103,16 @@ extension TransformedAttribute: ExpressibleByDictionaryLiteral where RawValue: D
 	}
 }
 
+extension Optional: DictionaryType where Wrapped: DictionaryType {
+	public typealias Key = Wrapped.Key
+
+	public typealias Value = Wrapped.Value
+
+	public init<S>(_ keysAndValues: S, uniquingKeysWith combine: (Dictionary<Key, Value>.Value, Dictionary<Key, Value>.Value) throws -> Dictionary<Key, Value>.Value) rethrows where S : Sequence, S.Element == (Key, Value) {
+		self = try .some(Wrapped(keysAndValues, uniquingKeysWith: combine))
+	}
+}
+
 public protocol ArrayType {
 	associatedtype Element
 
@@ -94,3 +128,11 @@ extension TransformedAttribute: ExpressibleByArrayLiteral where RawValue: ArrayT
 		self.init(value: RawValue(elements))
 	}
 }
+
+extension Optional: ArrayType where Wrapped: ArrayType {
+	public typealias Element = Wrapped.Element
+
+	public init<S>(_ s: S) where Element == S.Element, S : Sequence {
+		self = .some(Wrapped(s))
+	}
+}

Sources/JSONAPITestLib/EntityCheck.swift

@@ -45,6 +45,10 @@ extension TransformedAttribute: AttributeTypeWithOptionalArray where RawValue: O
 private protocol OptionalRelationshipType {}
 extension Optional: OptionalRelationshipType where Wrapped: RelationshipType {}
 
+private protocol _RelationshipType {}
+extension ToOneRelationship: _RelationshipType {}
+extension ToManyRelationship: _RelationshipType {}
+
 public extension Entity {
 	public static func check(_ entity: Entity) throws {
 		var problems = [EntityCheckError]()
@@ -72,7 +76,8 @@ public extension Entity {
 		}
 
 		for relationship in relationshipsMirror.children {
-			if relationship.value as? RelationshipType == nil {
+			if relationship.value as? _RelationshipType == nil,
+				relationship.value as? OptionalRelationshipType == nil {
 				problems.append(.nonRelationship(named: relationship.label ?? "unnamed"))
 			}
 		}

Sources/JSONAPITestLib/Relationship+Literal.swift

@@ -7,38 +7,38 @@
 
 import JSONAPI
 
-extension ToOneRelationship: ExpressibleByNilLiteral where Relatable.WrappedIdentifier: ExpressibleByNilLiteral {
+extension ToOneRelationship: ExpressibleByNilLiteral where Identifiable.Identifier: ExpressibleByNilLiteral, MetaType == NoMetadata, LinksType == NoLinks {
 	public init(nilLiteral: ()) {
 
-		self.init(id: Relatable.WrappedIdentifier(nilLiteral: ()))
+		self.init(id: Identifiable.Identifier(nilLiteral: ()))
 	}
 }
 
-extension ToOneRelationship: ExpressibleByUnicodeScalarLiteral where Relatable.WrappedIdentifier: ExpressibleByUnicodeScalarLiteral {
-	public typealias UnicodeScalarLiteralType =  Relatable.WrappedIdentifier.UnicodeScalarLiteralType
+extension ToOneRelationship: ExpressibleByUnicodeScalarLiteral where Identifiable.Identifier: ExpressibleByUnicodeScalarLiteral, MetaType == NoMetadata, LinksType == NoLinks {
+	public typealias UnicodeScalarLiteralType =  Identifiable.Identifier.UnicodeScalarLiteralType
 
 	public init(unicodeScalarLiteral value: UnicodeScalarLiteralType) {
-		self.init(id: Relatable.WrappedIdentifier(unicodeScalarLiteral: value))
+		self.init(id: Identifiable.Identifier(unicodeScalarLiteral: value))
 	}
 }
 
-extension ToOneRelationship: ExpressibleByExtendedGraphemeClusterLiteral where Relatable.WrappedIdentifier: ExpressibleByExtendedGraphemeClusterLiteral {
-	public typealias ExtendedGraphemeClusterLiteralType =  Relatable.WrappedIdentifier.ExtendedGraphemeClusterLiteralType
+extension ToOneRelationship: ExpressibleByExtendedGraphemeClusterLiteral where Identifiable.Identifier: ExpressibleByExtendedGraphemeClusterLiteral, MetaType == NoMetadata, LinksType == NoLinks {
+	public typealias ExtendedGraphemeClusterLiteralType =  Identifiable.Identifier.ExtendedGraphemeClusterLiteralType
 
 	public init(extendedGraphemeClusterLiteral value: ExtendedGraphemeClusterLiteralType) {
-		self.init(id: Relatable.WrappedIdentifier(extendedGraphemeClusterLiteral: value))
+		self.init(id: Identifiable.Identifier(extendedGraphemeClusterLiteral: value))
 	}
 }
 
-extension ToOneRelationship: ExpressibleByStringLiteral where Relatable.WrappedIdentifier: ExpressibleByStringLiteral {
-	public typealias StringLiteralType = Relatable.WrappedIdentifier.StringLiteralType
+extension ToOneRelationship: ExpressibleByStringLiteral where Identifiable.Identifier: ExpressibleByStringLiteral, MetaType == NoMetadata, LinksType == NoLinks {
+	public typealias StringLiteralType = Identifiable.Identifier.StringLiteralType
 
 	public init(stringLiteral value: StringLiteralType) {
-		self.init(id: Relatable.WrappedIdentifier(stringLiteral: value))
+		self.init(id: Identifiable.Identifier(stringLiteral: value))
 	}
 }
 
-extension ToManyRelationship: ExpressibleByArrayLiteral {
+extension ToManyRelationship: ExpressibleByArrayLiteral where MetaType == NoMetadata, LinksType == NoLinks {
 	public typealias ArrayLiteralElement = Relatable.Identifier
 
 	public init(arrayLiteral elements: ArrayLiteralElement...) {

Tests/JSONAPITests/APIDescription/APIDescriptionTests.swift

@@ -10,6 +10,10 @@ import JSONAPI
 
 class APIDescriptionTests: XCTestCase {
 
+	func test_NoDescriptionString() {
+		XCTAssertEqual(String(describing: NoAPIDescription()), "No JSON:API Object")
+	}
+
 	func test_empty() {
 		let description = decoded(type: APIDescription<NoMetadata>.self, data: api_description_empty)