Split Attribute out into its own Type (no longer just a type alias to TransformedAttribute)

.gitignore

@@ -2,3 +2,4 @@
 /.build
 /Packages
 /*.xcodeproj
+/*.xcworkspace

Examples.swift

@@ -1,78 +0,0 @@
-//
-//  Examples.swift
-//  JSONAPI
-//
-//  Created by Mathew Polzin on 11/12/18.
-//
-
-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.
-
-********/
-
-
-typealias ExampleEntity<Description: EntityDescription> = Entity<Description, Id<String, Description>>
-
-// MARK: - A few resource objects (entities)
-enum PersonDescription: EntityDescription {
-
-	static var type: String { return "people" }
-	
-	struct Attributes: JSONAPI.Attributes {
-		let name: [String]
-		let favoriteColor: String
-	}
-	
-	struct Relationships: JSONAPI.Relationships {
-		let friends: ToManyRelationship<Person>
-		let dogs: ToManyRelationship<Dog>
-		let home: ToOneRelationship<House>
-	}
-}
-
-typealias Person = ExampleEntity<PersonDescription>
-
-enum DogDescription: EntityDescription {
-
-	static var type: String { return "dogs" }
-
-	struct Attributes: JSONAPI.Attributes {
-		let name: String
-	}
-
-	struct Relationships: JSONAPI.Relationships {
-		let owner: ToOneRelationship<Person?>
-	}
-}
-
-typealias Dog = ExampleEntity<DogDescription>
-
-enum HouseDescription: EntityDescription {
-
-	static var type: String { return "houses" }
-
-	typealias Attributes = NoAttributes
-	typealias Relationships = NoRelatives
-}
-
-typealias House = ExampleEntity<HouseDescription>
-
-// MARK: - Parse a response body with one Dog in it
-typealias SingleDogResponse = JSONAPIDocument<SingleResourceBody<Dog>, NoIncludes, BasicJSONAPIError>
-
-let dummyData = "".data(using: .utf8)!
-let dogResponse = try! JSONDecoder().decode(SingleDogResponse.self, from: dummyData)
-let dog = dogResponse.body.data?.primary.value
-
-// MARK: Parse a response body with multiple people in it and dogs and houses included
-typealias BatchPeopleResponse = JSONAPIDocument<ManyResourceBody<Person>, Include2<Dog, House>, BasicJSONAPIError>
-
-let peopleResponse = try! JSONDecoder().decode(BatchPeopleResponse.self, from: dummyData)
-let people = peopleResponse.body.data?.primary.values
-let dogs = peopleResponse.body.data?.included[Dog.self]
-let houses = peopleResponse.body.data?.included[House.self]

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

@@ -0,0 +1,24 @@
+//: [Previous](@previous)
+
+import Foundation
+import JSONAPI
+import JSONAPITestLib
+
+/*******
+
+Please enjoy these examples, but allow me the forced casting and the lack of error checking for the sake of brevity.
+
+********/
+
+// 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), meta: .none, links: .none)
+
+// MARK: - JSON API structure checking
+// The JSONAPITestLib provides a `check` function for each Entity type
+// that uses reflection to catch mistakes that are not forbidden by
+// Swift's type system but will result in unexpected results when
+// encoding/decoding. It is a good idea to add a `check` to each of
+// your unit tests that create Entities.
+try Dog.check(dog)

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

@@ -0,0 +1,70 @@
+
+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.
+
+********/
+
+// MARK: - Create a request or response body with one Dog in it
+let dogFromCode = try! Dog(name: "Buddy", owner: nil)
+
+typealias SingleDogDocument = JSONAPI.Document<SingleResourceBody<Dog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, UnknownJSONAPIError>
+
+let singleDogDocument = SingleDogDocument(apiDescription: .none, body: .init(entity: dogFromCode), includes: .none, meta: .none, links: .none)
+
+let singleDogData = try! JSONEncoder().encode(singleDogDocument)
+
+// MARK: - Parse a request or response body with one Dog in it
+let dogResponse = try! JSONDecoder().decode(SingleDogDocument.self, from: singleDogData)
+let dogFromData = dogResponse.body.primaryResource?.value
+let dogOwner: Person.Identifier? = dogFromData.flatMap { $0 ~> \.owner }
+
+// MARKL - Parse a request or response body with one Dog in it using an alternative model
+typealias AltSingleDogDocument = JSONAPI.Document<SingleResourceBody<AlternativeDog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, UnknownJSONAPIError>
+let altDogResponse = try! JSONDecoder().decode(AltSingleDogDocument.self, from: singleDogData)
+let altDogFromData = altDogResponse.body.primaryResource?.value
+let altDogHuman: Person.Identifier? = altDogFromData.flatMap { $0 ~> \.human }
+
+// 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(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(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
+
+let peopleResponse = try! JSONDecoder().decode(BatchPeopleDocument.self, from: batchPeopleData)
+let peopleFromData = peopleResponse.body.primaryResource?.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("first person's name: \(bodyData.primary.values[0][\.fullName])")
+} else {
+	print("no body data")
+}
+
+// MARK: - Work in the abstract
+
+func process<T: JSONAPIDocument>(document: T) {
+	guard case let .data(body) = document.body else {
+		return
+	}
+	let x: T.Body.Data = body
+}
+process(document: peopleResponse)

JSONAPI.playground/Sources/Entities.swift

@@ -0,0 +1,142 @@
+//
+//  Examples.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 11/12/18.
+//
+
+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.
+
+********/
+
+// MARK: - String as CreatableRawIdType
+var GlobalStringId: Int = 0
+extension String: CreatableRawIdType {
+	public static func unique() -> String {
+		GlobalStringId += 1
+		return String(GlobalStringId)
+	}
+}
+
+// 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 {
+
+	public static var type: String { return "people" }
+	
+	public struct Attributes: JSONAPI.Attributes {
+		public let name: Attribute<[String]>
+		public let favoriteColor: Attribute<String>
+
+		public var fullName: Attribute<String> {
+			return name.map { $0.joined(separator: " ") }
+		}
+
+		public init(name: Attribute<[String]>, favoriteColor: Attribute<String>) {
+			self.name = name
+			self.favoriteColor = favoriteColor
+		}
+	}
+	
+	public struct Relationships: JSONAPI.Relationships {
+		public let friends: ToMany<Person>
+		public let dogs: ToMany<Dog>
+		public let home: ToOne<House>
+
+		public init(friends: ToMany<Person>, dogs: ToMany<Dog>, home: ToOne<House>) {
+			self.friends = friends
+			self.dogs = dogs
+			self.home = home
+		}
+	}
+}
+
+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 = Person(id: id ?? Person.Id(), attributes: .init(name: .init(value: name), favoriteColor: .init(value: favoriteColor)), relationships: .init(friends: .init(entities: friends), dogs: .init(entities: dogs), home: .init(entity: home)), meta: .none, links: .none)
+	}
+}
+
+public enum DogDescription: EntityDescription {
+
+	public static var type: String { return "dogs" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let name: Attribute<String>
+
+		public init(name: Attribute<String>) {
+			self.name = name
+		}
+	}
+
+	public struct Relationships: JSONAPI.Relationships {
+		public let owner: ToOne<Person?>
+
+		public init(owner: ToOne<Person?>) {
+			self.owner = owner
+		}
+	}
+}
+
+public typealias Dog = ExampleEntity<DogDescription>
+
+public enum AlternativeDogDescription: EntityDescription {
+
+	public static var type: String { return "dogs" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let name: Attribute<String>
+
+		public init(name: Attribute<String>) {
+			self.name = name
+		}
+	}
+
+	public struct Relationships: JSONAPI.Relationships {
+		public let human: ToOne<Person?>
+
+		public init(human: ToOne<Person?>) {
+			self.human = human
+		}
+
+		// define custom key mapping:
+		enum CodingKeys: String, CodingKey {
+			case human = "owner"
+		}
+	}
+}
+
+public typealias AlternativeDog = ExampleEntity<AlternativeDogDescription>
+
+public extension Entity where Description == DogDescription, MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == String {
+	public init(name: String, owner: Person?) throws {
+		self = Dog(attributes: .init(name: .init(value: name)), relationships: DogDescription.Relationships(owner: .init(entity: owner)), meta: .none, links: .none)
+	}
+
+	public init(name: String, owner: Person.Id) throws {
+		self = Dog(attributes: .init(name: .init(value: name)), relationships: .init(owner: .init(id: owner)), meta: .none, links: .none)
+	}
+}
+
+public enum HouseDescription: EntityDescription {
+
+	public static var type: String { return "houses" }
+
+	public typealias Attributes = NoAttributes
+	public typealias Relationships = NoRelationships
+}
+
+public typealias House = ExampleEntity<HouseDescription>
+
+

JSONAPI.playground/contents.xcplayground

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<playground version='6.0' target-platform='macos' executeOnSourceChanges='false'>
+    <pages>
+        <page name='Test Library'/>
+        <page name='Usage'/>
+    </pages>
+</playground>

Package.resolved

@@ -1,15 +1,7 @@
 {
   "object": {
     "pins": [
-      {
-        "package": "Result",
-        "repositoryURL": "https://github.com/antitypical/Result.git",
-        "state": {
-          "branch": null,
-          "revision": "8fc088dcf72802801efeecba76ea8fb041fb773d",
-          "version": "4.0.0"
-        }
-      }
+
     ]
   },
   "version": 1

Package.swift

@@ -6,23 +6,25 @@ import PackageDescription
 let package = Package(
     name: "JSONAPI",
     products: [
-        // Products define the executables and libraries produced by a package, and make them visible to other packages.
         .library(
             name: "JSONAPI",
             targets: ["JSONAPI"]),
+		.library(
+			name: "JSONAPITestLib",
+			targets: ["JSONAPITestLib"])
     ],
     dependencies: [
-        .package(url: "https://github.com/antitypical/Result.git", from: "4.0.0")
     ],
     targets: [
-        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
-        // Targets can depend on other targets in this package, and on products in packages which this package depends on.
         .target(
             name: "JSONAPI",
-            dependencies: ["Result"]),
+            dependencies: []),
+		.target(
+			name: "JSONAPITestLib",
+			dependencies: ["JSONAPI"]),
         .testTarget(
             name: "JSONAPITests",
-            dependencies: ["JSONAPI"]),
+            dependencies: ["JSONAPITestLib"])
     ],
   	swiftLanguageVersions: [.v4_2]
 )

Sources/JSONAPI/Document/APIDescription.swift

@@ -0,0 +1,59 @@
+//
+//  APIDescription.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 12/1/18.
+//
+
+/// This is what the JSON API Spec calls the "JSON:API Object"
+public protocol APIDescriptionType: Codable, Equatable {
+	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 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 init() {}
+
+	public static var none: NoAPIDescription { return .init() }
+
+	public var description: String { return "No JSON:API Object" }
+}
+
+extension APIDescription {
+	private enum CodingKeys: String, CodingKey {
+		case version
+		case meta
+	}
+
+	public init(from decoder: Decoder) throws {
+		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
+		version = (try? container.decode(String.self, forKey: .version)) ?? "1.0"
+
+		if let metaVal = NoMetadata() as? Meta {
+			meta = metaVal
+		} else {
+			meta = try container.decode(Meta.self, forKey: .meta)
+		}
+	}
+
+	public func encode(to encoder: Encoder) throws {
+		var container = encoder.container(keyedBy: CodingKeys.self)
+
+		try container.encode(version, forKey: .version)
+
+		if Meta.self != NoMetadata.self {
+			try container.encode(meta, forKey: .meta)
+		}
+	}
+}

Sources/JSONAPI/Document/Document.swift

@@ -5,6 +5,19 @@
 //  Created by Mathew Polzin on 11/5/18.
 //
 
+public protocol JSONAPIDocument: Codable, Equatable {
+	associatedtype PrimaryResourceBody: JSONAPI.ResourceBody
+	associatedtype MetaType: JSONAPI.Meta
+	associatedtype LinksType: JSONAPI.Links
+	associatedtype IncludeType: JSONAPI.Include
+	associatedtype APIDescription: APIDescriptionType
+	associatedtype Error: JSONAPIError
+
+	typealias Body = Document<PrimaryResourceBody, MetaType, LinksType, IncludeType, APIDescription, Error>.Body
+
+	var body: Body { get }
+}
+
 /// A JSON API Document represents the entire body
 /// of a JSON API request or the entire body of
 /// a JSON API response.
@@ -12,29 +25,191 @@
 /// API uses snake case, you will want to use
 /// a conversion such as the one offerred by the
 /// Foundation JSONEncoder/Decoder: `KeyDecodingStrategy`
-public struct JSONAPIDocument<ResourceBody: JSONAPI.ResourceBody, Include: IncludeDecoder, Error: JSONAPIError>: Equatable {
+public struct Document<PrimaryResourceBody: JSONAPI.ResourceBody, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links, IncludeType: JSONAPI.Include, APIDescription: APIDescriptionType, Error: JSONAPIError>: JSONAPIDocument {
+	public typealias Include = IncludeType
+
+	/// The JSON API Spec calls this the JSON:API Object. It contains version
+	/// and metadata information about the API itself.
+	public let apiDescription: APIDescription
+
+	/// The Body of the Document. This body is either one or more errors
+	/// with links and metadata attempted to parse but not guaranteed or
+	/// it is a successful data struct containing all the primary and
+	/// included resources, the metadata, and the links that this
+	/// document type specifies.
 	public let body: Body
-//	public let meta: Meta?
-//	public let jsonApi: APIDescription?
-//	public let links: Links?
 	
 	public enum Body: Equatable {
-		case errors([Error])
-		case data(primary: ResourceBody, included: Includes<Include>)
-		
+		case errors([Error], meta: MetaType?, links: LinksType?)
+		case data(Data)
+
+		public struct Data: Equatable {
+			public let primary: PrimaryResourceBody
+			public let includes: Includes<Include>
+			public let meta: MetaType
+			public let links: LinksType
+
+			public init(primary: PrimaryResourceBody, includes: Includes<Include>, meta: MetaType, links: LinksType) {
+				self.primary = primary
+				self.includes = includes
+				self.meta = meta
+				self.links = links
+			}
+		}
+
 		public var isError: Bool {
 			guard case .errors = self else { return false }
 			return true
 		}
-		
-		public var data: (primary: ResourceBody, included: Includes<Include>)? {
-			guard case let .data(primary: body, included: includes) = self else { return nil }
-			return (primary: body, included: includes)
+
+		public var errors: [Error]? {
+			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 primaryResource: PrimaryResourceBody? {
+			guard case let .data(data) = self else { return nil }
+			return data.primary
+		}
+
+		public var includes: Includes<Include>? {
+			guard case let .data(data) = self else { return nil }
+			return data.includes
+		}
+
+		public var meta: MetaType? {
+			switch self {
+			case .data(let data):
+				return data.meta
+			case .errors(_, meta: let metadata?, links: _):
+				return metadata
+			default:
+				return nil
+			}
+		}
+
+		public var links: LinksType? {
+			switch self {
+			case .data(let data):
+				return data.links
+			case .errors(_, meta: _, links: let links?):
+				return links
+			default:
+				return nil
+			}
+		}
+	}
+
+	public init(apiDescription: APIDescription, errors: [Error], meta: MetaType? = nil, links: LinksType? = nil) {
+		body = .errors(errors, meta: meta, links: links)
+		self.apiDescription = apiDescription
+	}
+
+	public init(apiDescription: APIDescription, body: PrimaryResourceBody, includes: Includes<Include>, meta: MetaType, links: LinksType) {
+		self.body = .data(.init(primary: body, includes: includes, meta: meta, links: links))
+		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)
 	}
 }
 
-extension JSONAPIDocument: Codable {
+extension Document where MetaType == NoMetadata {
+	public init(apiDescription: APIDescription, body: PrimaryResourceBody, includes: Includes<Include>, links: LinksType) {
+		self.init(apiDescription: apiDescription, body: body, includes: includes, meta: .none, links: links)
+	}
+}
+
+extension Document where LinksType == NoLinks {
+	public init(apiDescription: APIDescription, body: PrimaryResourceBody, includes: Includes<Include>, meta: MetaType) {
+		self.init(apiDescription: apiDescription, body: body, includes: includes, meta: meta, links: .none)
+	}
+}
+
+extension Document where APIDescription == NoAPIDescription {
+	public init(body: PrimaryResourceBody, includes: Includes<Include>, meta: MetaType, links: LinksType) {
+		self.init(apiDescription: .none, body: body, includes: includes, meta: meta, links: links)
+	}
+}
+
+extension Document where IncludeType == NoIncludes, LinksType == NoLinks {
+	public init(apiDescription: APIDescription, body: PrimaryResourceBody, meta: MetaType) {
+		self.init(apiDescription: apiDescription, body: body, meta: meta, links: .none)
+	}
+}
+
+extension Document where IncludeType == NoIncludes, MetaType == NoMetadata {
+	public init(apiDescription: APIDescription, body: PrimaryResourceBody, links: LinksType) {
+		self.init(apiDescription: apiDescription, body: body, meta: .none, links: links)
+	}
+}
+
+extension Document where IncludeType == NoIncludes, APIDescription == NoAPIDescription {
+	public init(body: PrimaryResourceBody, meta: MetaType, links: LinksType) {
+		self.init(apiDescription: .none, body: body, meta: meta, links: links)
+	}
+}
+
+extension Document where MetaType == NoMetadata, LinksType == NoLinks {
+	public init(apiDescription: APIDescription, body: PrimaryResourceBody, includes: Includes<Include>) {
+		self.init(apiDescription: apiDescription, body: body, includes: includes, links: .none)
+	}
+}
+
+extension Document where MetaType == NoMetadata, APIDescription == NoAPIDescription {
+	public init(body: PrimaryResourceBody, includes: Includes<Include>, links: LinksType) {
+		self.init(apiDescription: .none, body: body, includes: includes, links: links)
+	}
+}
+
+extension Document where IncludeType == NoIncludes, MetaType == NoMetadata, LinksType == NoLinks {
+	public init(apiDescription: APIDescription, body: PrimaryResourceBody) {
+		self.init(apiDescription: apiDescription, body: body, includes: .none)
+	}
+}
+
+extension Document where MetaType == NoMetadata, LinksType == NoLinks, APIDescription == NoAPIDescription {
+	public init(body: PrimaryResourceBody, includes: Includes<Include>) {
+		self.init(apiDescription: .none, body: body, includes: includes)
+	}
+}
+
+extension Document where IncludeType == NoIncludes, MetaType == NoMetadata, LinksType == NoLinks, APIDescription == NoAPIDescription {
+	public init(body: PrimaryResourceBody) {
+		self.init(apiDescription: .none, body: body)
+	}
+}
+*/
+
+extension Document.Body.Data where PrimaryResourceBody: AppendableResourceBody {
+	public func merging(_ other: Document.Body.Data,
+						combiningMetaWith metaMerge: (MetaType, MetaType) -> MetaType,
+						combiningLinksWith linksMerge: (LinksType, LinksType) -> LinksType) -> Document.Body.Data {
+		return Document.Body.Data(primary: primary.appending(other.primary),
+								  includes: includes.appending(other.includes),
+								  meta: metaMerge(meta, other.meta),
+								  links: linksMerge(links, other.links))
+	}
+}
+
+extension Document.Body.Data where PrimaryResourceBody: AppendableResourceBody, MetaType == NoMetadata, LinksType == NoLinks {
+	public func merging(_ other: Document.Body.Data) -> Document.Body.Data {
+		return merging(other,
+					   combiningMetaWith: { _, _ in .none },
+					   combiningLinksWith: { _, _ in .none })
+	}
+}
+
+// MARK: - Codable
+extension Document {
 	private enum RootCodingKeys: String, CodingKey {
 		case data
 		case errors
@@ -47,38 +222,127 @@ extension JSONAPIDocument: Codable {
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.container(keyedBy: RootCodingKeys.self)
 
+		if let noData = NoAPIDescription() as? APIDescription {
+			apiDescription = noData
+		} else {
+			apiDescription = try container.decode(APIDescription.self, forKey: .jsonapi)
+		}
+
 		let errors = try container.decodeIfPresent([Error].self, forKey: .errors)
 
+		let meta: MetaType?
+		if let noMeta = NoMetadata() as? MetaType {
+			meta = noMeta
+		} else {
+			do {
+				meta = try container.decode(MetaType.self, forKey: .meta)
+			} catch {
+				meta = nil
+			}
+		}
+
+		let links: LinksType?
+		if let noLinks = NoLinks() as? LinksType {
+			links = noLinks
+		} else {
+			do {
+				links = try container.decode(LinksType.self, forKey: .links)
+			} catch {
+				links = nil
+			}
+		}
+
+		// If there are errors, there cannot be a body. Return errors and any metadata found.
 		if let errors = errors {
-			body = .errors(errors)
+			body = .errors(errors, meta: meta, links: links)
 			return
 		}
 
-		let data = try container.decode(ResourceBody.self, forKey: .data)
+		let data: PrimaryResourceBody
+		if let noData = NoResourceBody() as? PrimaryResourceBody {
+			data = noData
+		} else {
+			data = try container.decode(PrimaryResourceBody.self, forKey: .data)
+		}
+
 		let maybeIncludes = try container.decodeIfPresent(Includes<Include>.self, forKey: .included)
 		
 		// TODO come back to this and make robust
+
+		guard let metaVal = meta else {
+			throw JSONAPIEncodingError.missingOrMalformedMetadata
+		}
+		guard let linksVal = links else {
+			throw JSONAPIEncodingError.missingOrMalformedLinks
+		}
 		
-		body = .data(primary: data, included: maybeIncludes ?? Includes<Include>.none)
+		body = .data(.init(primary: data, includes: maybeIncludes ?? Includes<Include>.none, meta: metaVal, links: linksVal))
 	}
 
 	public func encode(to encoder: Encoder) throws {
 		var container = encoder.container(keyedBy: RootCodingKeys.self)
 
 		switch body {
-		case .errors(let errors):
+		case .errors(let errors, meta: let meta, links: let links):
 			var errContainer = container.nestedUnkeyedContainer(forKey: .errors)
 
 			for error in errors {
 				try errContainer.encode(error)
 			}
 
-		case .data(primary: let resourceBody, included: let includes):
-			try container.encode(resourceBody, forKey: .data)
+			if MetaType.self != NoMetadata.self,
+				let metaVal = meta {
+				try container.encode(metaVal, forKey: .meta)
+			}
+
+			if LinksType.self != NoLinks.self,
+				let linksVal = links {
+				try container.encode(linksVal, forKey: .links)
+			}
+
+		case .data(let data):
+			try container.encode(data.primary, forKey: .data)
 
 			if Include.self != NoIncludes.self {
-				try container.encode(includes, forKey: .included)
+				try container.encode(data.includes, forKey: .included)
 			}
+
+			if MetaType.self != NoMetadata.self {
+				try container.encode(data.meta, forKey: .meta)
+			}
+
+			if LinksType.self != NoLinks.self {
+				try container.encode(data.links, forKey: .links)
+			}
+		}
+
+		if APIDescription.self != NoAPIDescription.self {
+			try container.encode(apiDescription, forKey: .jsonapi)
 		}
 	}
 }
+
+// MARK: - CustomStringConvertible
+
+extension Document: CustomStringConvertible {
+	public var description: String {
+		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/Document/Error.swift

@@ -9,7 +9,7 @@ public protocol JSONAPIError: Swift.Error, Equatable, Codable {
 	static var unknown: Self { get }
 }
 
-public enum BasicJSONAPIError: JSONAPIError {
+public enum UnknownJSONAPIError: JSONAPIError {
 	case unknownError
 	
 	public init(from decoder: Decoder) throws {
@@ -21,7 +21,7 @@ public enum BasicJSONAPIError: JSONAPIError {
 		try container.encode("unknown")
 	}
 	
-	public static var unknown: BasicJSONAPIError {
+	public static var unknown: UnknownJSONAPIError {
 		return .unknownError
 	}
 }

Sources/JSONAPI/Document/ResourceBody.swift

@@ -1,28 +1,67 @@
 //
-//  ResourceBody.swift
+//  PrimaryResourceBody.swift
 //  JSONAPI
 //
 //  Created by Mathew Polzin on 11/10/18.
 //
 
+public protocol MaybePrimaryResource: Equatable, Codable {}
+
+/// A PrimaryResource is a type that can be used in the body of a JSON API
+/// document as the primary resource.
+public protocol PrimaryResource: MaybePrimaryResource {}
+
+extension Optional: MaybePrimaryResource where Wrapped: PrimaryResource {}
+
+/// A ResourceBody 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: Codable, Equatable {
 }
 
-public struct SingleResourceBody<Entity: JSONAPI.EntityType>: ResourceBody {
-	public let value: Entity?
+public protocol AppendableResourceBody: ResourceBody {
+	func appending(_ other: Self) -> Self
 }
 
-public struct ManyResourceBody<Entity: JSONAPI.EntityType>: ResourceBody {
+public func +<R: AppendableResourceBody>(_ left: R, right: R) -> R {
+	return left.appending(right)
+}
+
+public struct SingleResourceBody<Entity: JSONAPI.MaybePrimaryResource>: ResourceBody {
+	public let value: Entity
+
+	public init(entity: Entity) {
+		self.value = entity
+	}
+}
+
+public struct ManyResourceBody<Entity: JSONAPI.PrimaryResource>: AppendableResourceBody {
 	public let values: [Entity]
+
+	public init(entities: [Entity]) {
+		values = entities
+	}
+
+	public func appending(_ other: ManyResourceBody) -> ManyResourceBody {
+		return ManyResourceBody(entities: values + other.values)
+	}
 }
 
-// MARK: Decodable
+/// Use NoResourceBody to indicate you expect a JSON API document to not
+/// contain a "data" top-level key.
+public struct NoResourceBody: ResourceBody {
+	public static var none: NoResourceBody { return NoResourceBody() }
+}
+
+// MARK: Codable
 extension SingleResourceBody {
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.singleValueContainer()
 
-		if container.decodeNil() {
-			value = nil
+		let anyNil: Any? = nil
+		if container.decodeNil(),
+			let val = anyNil as? Entity {
+			value = val
 			return
 		}
 
@@ -32,7 +71,7 @@ extension SingleResourceBody {
 	public func encode(to encoder: Encoder) throws {
 		var container = encoder.singleValueContainer()
 
-		if value == nil {
+		if (value as Any?) == nil {
 			try container.encodeNil()
 			return
 		}
@@ -59,3 +98,17 @@ extension ManyResourceBody {
 		}
 	}
 }
+
+// MARK: CustomStringConvertible
+
+extension SingleResourceBody: CustomStringConvertible {
+	public var description: String {
+		return "PrimaryResourceBody(\(String(describing: value)))"
+	}
+}
+
+extension ManyResourceBody: CustomStringConvertible {
+	public var description: String {
+		return "PrimaryResourceBody(\(String(describing: values)))"
+	}
+}

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/Meta/Links.swift

@@ -0,0 +1,67 @@
+//
+//  Links.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 11/24/18.
+//
+
+/// 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 init() {}
+
+	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 meta: Meta
+
+	public init(url: URL, meta: Meta) {
+		self.url = url
+		self.meta = meta
+	}
+}
+
+extension Link where Meta == NoMetadata {
+	public init(url: URL) {
+		self.init(url: url, meta: .none)
+	}
+}
+
+public extension Link {
+	private enum CodingKeys: String, CodingKey {
+		case href
+		case meta
+	}
+
+	init(from decoder: Decoder) throws {
+		guard Meta.self == NoMetadata.self,
+			let noMeta = NoMetadata() as? Meta else {
+				let container = try decoder.container(keyedBy: CodingKeys.self)
+				meta = try container.decode(Meta.self, forKey: .meta)
+				url = try container.decode(URL.self, forKey: .href)
+				return
+		}
+		let container = try decoder.singleValueContainer()
+		url = try container.decode(URL.self)
+		meta = noMeta
+	}
+
+	func encode(to encoder: Encoder) throws {
+		guard Meta.self == NoMetadata.self else {
+			var container = encoder.container(keyedBy: CodingKeys.self)
+			try container.encode(url, forKey: .href)
+			try container.encode(meta, forKey: .meta)
+			return
+		}
+		var container = encoder.singleValueContainer()
+
+		try container.encode(url)
+	}
+}

Sources/JSONAPI/Meta/Meta.swift

@@ -0,0 +1,28 @@
+//
+//  Meta.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 11/21/18.
+//
+
+/// Conform a type to this protocol to indicate it can be encoded to or decoded from
+/// the meta data attached to a component of a JSON API document. Different meta data
+/// can be stored all over the place: On the root document, on a resource object, on
+/// link objects, etc.
+///
+/// JSON API Metadata is totally open ended. It can take whatever JSON-compliant structure
+/// the server and client agree upon.
+public protocol Meta: Codable, Equatable {
+}
+
+// We make Optional a Meta if it wraps a Meta so that Metadata can be specified as
+// nullable.
+extension Optional: Meta where Wrapped: 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/Attribute+Functor.swift

@@ -0,0 +1,36 @@
+//
+//  Attribute+Functor.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 11/28/18.
+//
+
+public extension TransformedAttribute {
+	/// Map an Attribute to a new wrapped type.
+	/// Note that the resulting Attribute will have no transformer, even if the
+	/// source Attribute has a transformer.
+	/// You are mapping the output of the source transform into
+	/// the RawValue of a new transformerless Attribute.
+	///
+	/// Generally, this is the most useful operation. The transformer gives you
+	/// control over the decoding of the Attribute, but once the Attribute exists,
+	/// mapping on it is most useful for creating computed Attribute properties.
+	public func map<T: Codable>(_ transform: (Transformer.To) throws -> T) rethrows -> Attribute<T> {
+		return Attribute<T>(value: try transform(value))
+	}
+}
+
+public extension Attribute {
+	/// Map an Attribute to a new wrapped type.
+	/// Note that the resulting Attribute will have no transformer, even if the
+	/// source Attribute has a transformer.
+	/// You are mapping the output of the source transform into
+	/// the RawValue of a new transformerless Attribute.
+	///
+	/// Generally, this is the most useful operation. The transformer gives you
+	/// control over the decoding of the Attribute, but once the Attribute exists,
+	/// mapping on it is most useful for creating computed Attribute properties.
+	public func map<T: Codable>(_ transform: (ValueType) throws -> T) rethrows -> Attribute<T> {
+		return Attribute<T>(value: try transform(value))
+	}
+}

Sources/JSONAPI/Resource/Attribute.swift

@@ -5,8 +5,18 @@
 //  Created by Mathew Polzin on 11/13/18.
 //
 
-public struct TransformAttribute<RawValue: Codable, Transformer: JSONAPI.Transformer>: Codable where Transformer.From == RawValue {
-	private let rawValue: RawValue
+public protocol AttributeType: Codable {
+	associatedtype RawValue: Codable
+	associatedtype ValueType
+
+	var value: ValueType { get }
+}
+
+// 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 {
+	let rawValue: RawValue
 	
 	public let value: Transformer.To
 	
@@ -16,12 +26,64 @@ public struct TransformAttribute<RawValue: Codable, Transformer: JSONAPI.Transfo
 	}
 }
 
-public typealias Attribute<T: Codable> = TransformAttribute<T, IdentityTransformer<T>>
+extension TransformedAttribute where Transformer == IdentityTransformer<RawValue> {
+	// If we are using the identity transform, we can skip the transform and guarantee no
+	// error is thrown.
+	public init(value: RawValue) {
+		rawValue = value
+		self.value = value
+	}
+}
 
-extension TransformAttribute: Equatable where Transformer.From: Equatable, Transformer.To: Equatable {}
+extension TransformedAttribute where Transformer: ReversibleTransformer {
+	/// Initialize a TransformedAttribute from its transformed value. The
+	/// RawValue, which is what gets encoded/decoded, is determined using
+	/// The Transformer's reverse function.
+	public init(transformedValue: Transformer.To) throws {
+		self.value = transformedValue
+		rawValue = try Transformer.reverse(value)
+	}
+}
+
+extension TransformedAttribute: CustomStringConvertible {
+	public var description: String {
+		return "Attribute<\(String(describing: Transformer.From.self)) -> \(String(describing: Transformer.To.self))>(\(String(describing: value)))"
+	}
+}
+
+extension TransformedAttribute: Equatable where Transformer.From: Equatable, Transformer.To: Equatable {}
+
+// 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 struct Attribute<RawValue: Codable>: AttributeType {
+	let attribute: TransformedAttribute<RawValue, IdentityTransformer<RawValue>>
+
+	public var value: RawValue {
+		return attribute.value
+	}
+
+	public init(value: RawValue) {
+		attribute = .init(value: value)
+	}
+}
+
+extension Attribute: CustomStringConvertible {
+	public var description: String {
+		return "Attribute<\(String(describing: RawValue.self))>(\(String(describing: value)))"
+	}
+}
+
+extension Attribute: Equatable where RawValue: Equatable {}
 
 // MARK: - Codable
-extension TransformAttribute {
+extension TransformedAttribute {
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.singleValueContainer()
 		
@@ -46,28 +108,40 @@ extension TransformAttribute {
 	
 	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)
 	}
 }
 
-// MARK: - Transformers
+extension Attribute {
+	public init(from decoder: Decoder) throws {
+		let container = try decoder.singleValueContainer()
 
-public protocol Transformer {
-	associatedtype From
-	associatedtype To
-	
-	static func transform(_ from: From) throws -> To
+		// A little trickery follows. If the value is nil, the
+		// container.decode(Value.self) will fail even if Value
+		// is Optional. However, we can check if decoding nil
+		// succeeds and then attempt to coerce nil to a Value
+		// type at which point we can store nil in `value`.
+		let anyNil: Any? = nil
+		if container.decodeNil(),
+			let val = anyNil as? RawValue {
+			attribute = .init(value: val)
+		} else {
+			attribute = try container.decode(TransformedAttribute<RawValue, IdentityTransformer<RawValue>>.self)
+		}
+	}
+
+	public func encode(to encoder: Encoder) throws {
+		var container = encoder.singleValueContainer()
+
+		try container.encode(attribute)
+	}
 }
 
-public enum IdentityTransformer<T>: Transformer {
-	public static func transform(_ from: T) throws -> T { return from }
+// MARK: Attribute decoding and encoding defaults
+
+extension AttributeType {
+	public static func defaultDecoding<Container: KeyedDecodingContainerProtocol>(from container: Container, forKey key: Container.Key) throws -> Self {
+		return try container.decode(Self.self, forKey: key)
+	}
 }