Added Meta-Attribute support and documentation

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

@@ -0,0 +1,173 @@
+import Foundation
+import JSONAPI
+
+// MARK: - Preamble (setup)
+
+// We make String a CreatableRawIdType. This is actually done in
+// this Playground's Entities.swift file, so it is commented out here.
+/*
+var GlobalStringId: Int = 0
+extension String: CreatableRawIdType {
+	public static func unique() -> String {
+		GlobalStringId += 1
+		return String(GlobalStringId)
+	}
+}
+*/
+
+// We create a typealias given that we do not expect JSON:API Resource
+// Objects for this particular API to have Metadata or Links associated
+// with them. We also expect them to have String Identifiers.
+typealias JSONEntity<Description: EntityDescription> = JSONAPI.Entity<Description, NoMetadata, NoLinks, String>
+
+// Similarly, we create a typealias for unidentified entities. JSON:API
+// only allows unidentified entities (i.e. no "id" field) for client
+// requests that create new entities. In these situations, the server
+// is expected to assign the new entity a unique ID.
+typealias UnidentifiedJSONEntity<Description: EntityDescription> = JSONAPI.Entity<Description, NoMetadata, NoLinks, Unidentified>
+
+// We create typealiases given that we do not expect JSON:API Relationships
+// for this particular API to have Metadata or Links associated
+// with them.
+typealias ToOneRelationship<Entity: Identifiable> = JSONAPI.ToOneRelationship<Entity, NoMetadata, NoLinks>
+typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoMetadata, NoLinks>
+
+// We create a typealias for a Document given that we do not expect
+// JSON:API Documents for this particular API to have Metadata, Links,
+// useful Errors, or a JSON:API Object (i.e. APIDescription).
+typealias Document<PrimaryResourceBody: JSONAPI.ResourceBody, IncludeType: JSONAPI.Include> = JSONAPI.Document<PrimaryResourceBody, NoMetadata, NoLinks, IncludeType, NoAPIDescription, UnknownJSONAPIError>
+
+// MARK: Entity Definitions
+
+enum AuthorDescription: EntityDescription {
+	public static var jsonType: String { return "authors" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let name: Attribute<String>
+	}
+
+	public typealias Relationships = NoRelationships
+}
+
+typealias Author = JSONEntity<AuthorDescription>
+
+enum ArticleDescription: EntityDescription {
+	public static var jsonType: String { return "articles" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let title: Attribute<String>
+		public let abstract: Attribute<String>
+	}
+
+	public struct Relationships: JSONAPI.Relationships {
+		public let author: ToOneRelationship<Author>
+	}
+}
+
+typealias Article = JSONEntity<ArticleDescription>
+
+// MARK: Document Definitions
+
+// We create a typealias to represent a document containing one Article
+// and including its Author
+typealias SingleArticleDocumentWithIncludes = Document<SingleResourceBody<Article>, Include1<Author>>
+
+// ... and a typealias to represent a document containing one Article and
+// not including any related entities.
+typealias SingleArticleDocument = Document<SingleResourceBody<Article>, NoIncludes>
+
+// MARK: - Server Pseudo-example
+
+// Skipping over all the API and database stuff, here's a chunk of code
+// that creates a document. Note that this document is the entirety
+// of a JSON:API response body.
+func articleDocument(includeAuthor: Bool) -> Either<SingleArticleDocument, SingleArticleDocumentWithIncludes> {
+	// Let's pretend all of this is coming from a database:
+
+	let authorId = Author.Identifier(rawValue: "1234")
+
+	let article = Article(id: .init(rawValue: "5678"),
+						  attributes: .init(title: .init(value: "JSON:API in Swift"),
+											abstract: .init(value: "Not yet written")),
+						  relationships: .init(author: .init(id: authorId)),
+						  meta: .none,
+						  links: .none)
+
+	let document = SingleArticleDocument(apiDescription: .none,
+										 body: .init(entity: article),
+										 includes: .none,
+										 meta: .none,
+										 links: .none)
+
+	switch includeAuthor {
+	case false:
+		return .a(document)
+
+	case true:
+		let author = Author(id: authorId,
+							attributes: .init(name: .init(value: "Janice Bluff")),
+							relationships: .none,
+							meta: .none,
+							links: .none)
+
+		let includes: Includes<SingleArticleDocumentWithIncludes.Include> = .init(values: [.init(author)])
+
+		return .b(document.including(.init(values: [.init(author)])))
+	}
+}
+
+let encoder = JSONEncoder()
+encoder.keyEncodingStrategy = .convertToSnakeCase
+encoder.outputFormatting = .prettyPrinted
+
+let responseBody = articleDocument(includeAuthor: true)
+let responseData = try! encoder.encode(responseBody)
+
+// Next step would be encoding and setting as the HTTP body of a response.
+// we will just print it out instead:
+print("-----")
+print(String(data: responseData, encoding: .utf8)!)
+
+// ... and if we had received a request for an article without
+// including the author:
+let otherResponseBody = articleDocument(includeAuthor: false)
+let otherResponseData = try! encoder.encode(otherResponseBody)
+print("-----")
+print(String(data: otherResponseData, encoding: .utf8)!)
+
+// MARK: - Client Pseudo-example
+
+enum NetworkError: Swift.Error {
+	case serverError
+	case quantityMismatch
+}
+
+// Skipping over all the API stuff, here's a chunk of code that will
+// decode a document. We will assume we have made a request for a
+// single article including the author.
+func docode(articleResponseData: Data) throws -> (article: Article, author: Author) {
+	let decoder = JSONDecoder()
+	decoder.keyDecodingStrategy = .convertFromSnakeCase
+
+	let articleDocument = try decoder.decode(SingleArticleDocumentWithIncludes.self, from: articleResponseData)
+
+	switch articleDocument.body {
+	case .data(let data):
+		let authors = data.includes[Author.self]
+
+		guard authors.count == 1 else {
+			throw NetworkError.quantityMismatch
+		}
+
+		return (article: data.primary.value, author: authors[0])
+	case .errors(let errors, meta: _, links: _):
+		throw NetworkError.serverError
+	}
+}
+
+let response = try! docode(articleResponseData: responseData)
+
+// Next step would be to do something useful with the article and author but we will print them instead.
+print("-----")
+print(response.article)
+print(response.author)

JSONAPI.playground/Pages/Full Document Verbose Generation.xcplaygroundpage/Contents.swift

@@ -0,0 +1,213 @@
+
+import Foundation
+import JSONAPI
+
+/*
+
+This is not realistically what JSONAPI code will look like. It makes
+every bit of sense to typealias the long-winded generics of this
+framework to make working with them more concise and readable.
+
+The purpose of this example, then, is not to show "good" JSONAPI
+code, but rather to generate a JSONAPI example document that uses
+all the various (often optional) parts of a JSONAPI document.
+
+The JSON example produced in this manner can be used to compare the
+nomenclature of this library with the nomenclature of the JSON:API Spec.
+
+*/
+
+// MARK: - Extensions
+extension Foundation.URL: JSONAPIURL {}
+
+// extension String: CreatableRawIdType {} found in playground Entities.swift file.
+
+// MARK: - Definitions
+/// Metadata associated with entities
+struct EntityMetadata: JSONAPI.Meta {
+	let creationDate: Date
+	let updatedDate: Date
+}
+
+/// Metadata associated with links
+struct LinkMeta: JSONAPI.Meta {
+	/// Don't trust this link past the expiry date.
+	let expiry: Date
+}
+
+/// Links associated with entities
+struct EntityLinks: JSONAPI.Links {
+	let `self`: Link<Foundation.URL, LinkMeta>
+
+	init(selfLink: Link<Foundation.URL, LinkMeta>) {
+		self.`self` = selfLink
+	}
+}
+
+/// Metadata associated with relationships
+struct ToManyRelationshipMetadata: JSONAPI.Meta {
+	/// Pagination for the relationship (to support really large
+	/// to-many relationships)
+	let pagination: Pagination
+
+	struct Pagination: Codable, Equatable {
+		let total: Int
+		let limit: Int
+		let offset: Int
+	}
+}
+
+/// Links associated with relationships
+struct ToManyRelationshipLinks: JSONAPI.Links {
+	/// next page of relationships.
+	let next: Link<Foundation.URL, LinkMeta>
+}
+
+/// Description of an Author entity.
+enum AuthorDescription: EntityDescription {
+	static var jsonType: String { return "authors" }
+
+	struct Attributes: JSONAPI.Attributes {
+		let name: Attribute<String>
+	}
+
+	struct Relationships: JSONAPI.Relationships {
+		let articles: ToManyRelationship<Article, ToManyRelationshipMetadata, ToManyRelationshipLinks>
+	}
+}
+
+typealias Author = JSONAPI.Entity<AuthorDescription, EntityMetadata, EntityLinks, String>
+
+/// Description of an Article entity.
+enum ArticleDescription: EntityDescription {
+	static var jsonType: String { return "articles" }
+
+	struct Attributes: JSONAPI.Attributes {
+		let title: Attribute<String>
+	}
+
+	struct Relationships: JSONAPI.Relationships {
+		/// The primary attributed author of the article.
+		let primaryAuthor: ToOneRelationship<Author, NoMetadata, NoLinks>
+		/// All authors excluding the primary author.
+		/// It is customary to print the primary author's
+		/// name first, followed by the other authors.
+		let otherAuthors: ToManyRelationship<Author, ToManyRelationshipMetadata, ToManyRelationshipLinks>
+	}
+}
+
+typealias Article = JSONAPI.Entity<ArticleDescription, EntityMetadata, EntityLinks, String>
+
+/// Metadata associated with the API Description
+struct APIDescriptionMetadata: JSONAPI.Meta {
+	/// A clever codename for this API version.
+	let codename: String
+}
+
+/// Metadata associated with any Document
+struct DocumentMetadata: JSONAPI.Meta {
+	/// Assuming caching is in play, this is when
+	/// the cached document being returned was created.
+	let updatedDate: Date
+}
+
+/// Links associated with an Article Document
+struct SingleArticleDocumentLinks: JSONAPI.Links {
+	let otherArticlesByPrimaryAuthor: Link<Foundation.URL, LinkMeta>
+}
+
+/// Error that can occur when retrieving a Single Article Document
+enum ArticleDocumentError: String, JSONAPIError, Codable {
+	case unknownError = "unknown"
+	case missing = "missing"
+
+	static var unknown: ArticleDocumentError {
+		return .unknownError
+	}
+}
+
+typealias SingleArticleDocument = JSONAPI.Document<SingleResourceBody<Article>, DocumentMetadata, SingleArticleDocumentLinks, Include1<Author>, APIDescription<APIDescriptionMetadata>, ArticleDocumentError>
+
+// MARK: - Instantiations
+let authorId1 = Author.Identifier()
+let authorId2 = Author.Identifier()
+let authorId3 = Author.Identifier()
+
+let now = Date()
+let tomorrow = Calendar.current.date(byAdding: .day, value: 1, to: now)!
+
+let tomorrowEntityMeta = EntityMetadata(creationDate: Calendar.current.date(byAdding: .day, value: -10, to: now)!,
+										updatedDate: Calendar.current.date(byAdding: .day, value: -2, to: now)!)
+let articleLinks = EntityLinks(selfLink: .init(url: URL(string: "https://articles.com/article/1234")!,
+											   meta: .init(expiry: tomorrow)))
+let article = Article(attributes: .init(title: .init(value: "How to read JSONAPI")),
+					  relationships: .init(primaryAuthor: .init(id: authorId1),
+										   otherAuthors: .init(ids: [authorId2, authorId3],
+															   meta: .init(pagination: .init(total: 2,
+																							 limit: 50,
+																							 offset: 0)),
+															   links: .init(next: .init(url: URL(string: "https://articles.com/article/1234?otherAuthors[offset]=50")!,
+																						meta: .init(expiry: tomorrow))))),
+					  meta: tomorrowEntityMeta,
+					  links: articleLinks)
+
+let author1Links = EntityLinks(selfLink: .init(url: URL(string: "https://articles.com/author/\(authorId1.rawValue)")!,
+											   meta: .init(expiry: tomorrow)))
+let author1 = Author(id: authorId1,
+					 attributes: .init(name: .init(value: "James Kinney")),
+					 relationships: .init(articles: .init(ids: [article.id, Article.Identifier(), Article.Identifier()],
+														  meta: .init(pagination: .init(total: 3,
+																						limit: 50,
+																						offset: 0)),
+														  links: .init(next: .init(url: URL(string: "https://articles.com/author/\(authorId1.rawValue)?articles[offset]=50")!, meta: .init(expiry: tomorrow))))),
+					 meta: tomorrowEntityMeta,
+					 links: author1Links)
+
+let author2Links = EntityLinks(selfLink: .init(url: URL(string: "https://articles.com/author/\(authorId2.rawValue)")!,
+											   meta: .init(expiry: tomorrow)))
+let author2 = Author(id: authorId2,
+					 attributes: .init(name: .init(value: "James Kinney")),
+					 relationships: .init(articles: .init(ids: [article.id, Article.Identifier()],
+														  meta: .init(pagination: .init(total: 2,
+																						limit: 50,
+																						offset: 0)),
+														  links: .init(next: .init(url: URL(string: "https://articles.com/author/\(authorId2.rawValue)?articles[offset]=50")!, meta: .init(expiry: tomorrow))))),
+					 meta: tomorrowEntityMeta,
+					 links: author2Links)
+
+let author3Links = EntityLinks(selfLink: .init(url: URL(string: "https://articles.com/author/\(authorId3.rawValue)")!,
+											   meta: .init(expiry: tomorrow)))
+let author3 = Author(id: authorId3,
+					 attributes: .init(name: .init(value: "James Kinney")),
+					 relationships: .init(articles: .init(ids: [article.id],
+														  meta: .init(pagination: .init(total: 1,
+																						limit: 50,
+																						offset: 0)),
+														  links: .init(next: .init(url: URL(string: "https://articles.com/author/\(authorId3.rawValue)?articles[offset]=50")!, meta: .init(expiry: tomorrow))))),
+					 meta: tomorrowEntityMeta,
+					 links: author3Links)
+
+let apiDescription = APIDescription<APIDescriptionMetadata>(version: "1.2",
+															meta: APIDescriptionMetadata(codename: "cobra"))
+
+let documentMetadata = DocumentMetadata(updatedDate: Date())
+
+let documentLinks = SingleArticleDocumentLinks(otherArticlesByPrimaryAuthor: .init(url: URL(string: "https://articles.com/articles?author=\(authorId1.rawValue)")!,
+																				   meta: .init(expiry: tomorrow)))
+
+let singleArticleDocument = SingleArticleDocument(apiDescription: apiDescription,
+												  body: .init(entity: article),
+												  includes: .init(values: [.init(author1), .init(author2), .init(author3)]),
+												  meta: documentMetadata,
+												  links: documentLinks)
+
+// MARK: - Encoding
+let encoder = JSONEncoder()
+encoder.keyEncodingStrategy = .convertToSnakeCase
+encoder.dateEncodingStrategy = .iso8601
+encoder.outputFormatting = .prettyPrinted
+
+let jsonData = try! encoder.encode(singleArticleDocument)
+
+// MARK: - Printing JSON
+print(String(data: jsonData, encoding: .utf8)!)

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

@@ -19,7 +19,14 @@ 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.primaryData?.value
+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()]
@@ -36,7 +43,7 @@ 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.primaryData?.values
+let peopleFromData = peopleResponse.body.primaryResource?.values
 let dogsFromData = peopleResponse.body.includes?[Dog.self]
 let housesFromData = peopleResponse.body.includes?[House.self]
 

JSONAPI.playground/Sources/Entities.swift

@@ -31,7 +31,7 @@ public typealias ToMany<E: Relatable> = ToManyRelationship<E, NoMetadata, NoLink
 // MARK: - A few resource objects (entities)
 public enum PersonDescription: EntityDescription {
 
-	public static var type: String { return "people" }
+	public static var jsonType: String { return "people" }
 	
 	public struct Attributes: JSONAPI.Attributes {
 		public let name: Attribute<[String]>
@@ -64,13 +64,13 @@ 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)), meta: .none, links: .none)
+		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 static var jsonType: String { return "dogs" }
 
 	public struct Attributes: JSONAPI.Attributes {
 		public let name: Attribute<String>
@@ -91,19 +91,47 @@ public enum DogDescription: EntityDescription {
 
 public typealias Dog = ExampleEntity<DogDescription>
 
+public enum AlternativeDogDescription: EntityDescription {
+
+	public static var jsonType: 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 = try Dog(attributes: .init(name: .init(rawValue: name)), relationships: DogDescription.Relationships(owner: .init(entity: owner)), meta: .none, links: .none)
+		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 = try Dog(attributes: .init(name: .init(rawValue: name)), relationships: .init(owner: .init(id: owner)), meta: .none, links: .none)
+		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 static var jsonType: String { return "houses" }
 
 	public typealias Attributes = NoAttributes
 	public typealias Relationships = NoRelationships

README.md

@@ -5,6 +5,62 @@ A Swift package for encoding to- and decoding from **JSON API** compliant reques
 
 See the JSON API Spec here: https://jsonapi.org/format/
 
+## Table of Contents
+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
+
+- [Table of Contents](#table-of-contents)
+- [Primary Goals](#primary-goals)
+	- [Caveat](#caveat)
+- [Dev Environment](#dev-environment)
+	- [Prerequisites](#prerequisites)
+	- [Xcode project](#xcode-project)
+	- [Running the Playground](#running-the-playground)
+- [Project Status](#project-status)
+	- [Encoding/Decoding](#encodingdecoding)
+		- [Document](#document)
+		- [Resource Object](#resource-object)
+		- [Relationship Object](#relationship-object)
+		- [Links Object](#links-object)
+	- [Misc](#misc)
+	- [JSONAPITestLib](#jsonapitestlib)
+		- [Entity Validator](#entity-validator)
+	- [Potential Improvements](#potential-improvements)
+- [Usage](#usage)
+	- [`JSONAPI.EntityDescription`](#jsonapientitydescription)
+	- [`JSONAPI.Entity`](#jsonapientity)
+		- [`Meta`](#meta)
+		- [`Links`](#links)
+		- [`IdType`](#idtype)
+		- [`MaybeRawId`](#mayberawid)
+		- [Convenient `typealiases`](#convenient-typealiases)
+	- [`JSONAPI.Relationships`](#jsonapirelationships)
+	- [`JSONAPI.Attributes`](#jsonapiattributes)
+		- [`Transformer`](#transformer)
+		- [`Validator`](#validator)
+		- [Computed `Attribute`](#computed-attribute)
+	- [Copying `Entities`](#copying-entities)
+	- [`JSONAPI.Document`](#jsonapidocument)
+		- [`ResourceBody`](#resourcebody)
+			- [nullable `PrimaryResource`](#nullable-primaryresource)
+		- [`MetaType`](#metatype)
+		- [`LinksType`](#linkstype)
+		- [`IncludeType`](#includetype)
+		- [`APIDescriptionType`](#apidescriptiontype)
+		- [`Error`](#error)
+	- [`JSONAPI.Meta`](#jsonapimeta)
+	- [`JSONAPI.Links`](#jsonapilinks)
+	- [`JSONAPI.RawIdType`](#jsonapirawidtype)
+	- [Custom Attribute or Relationship Key Mapping](#custom-attribute-or-relationship-key-mapping)
+	- [Custom Attribute Encode/Decode](#custom-attribute-encodedecode)
+	- [Meta-attributes](#meta-attributes)
+- [Example](#example)
+	- [Preamble (Setup shared by server and client)](#preamble-setup-shared-by-server-and-client)
+	- [Server Pseudo-example](#server-pseudo-example)
+	- [Client Pseudo-example](#client-pseudo-example)
+- [JSONAPITestLib](#jsonapitestlib)
+
+<!-- /TOC -->
+
 ## Primary Goals
 
 The primary goals of this framework are:
@@ -62,6 +118,7 @@ Note that Playground support for importing non-system Frameworks is still a bit
 ### Misc
 - [x] Support transforms on `Attributes` values (e.g. to support different representations of `Date`)
 - [x] Support validation on `Attributes`.
+- [ ] Support sparse fieldsets. At the moment, not sure what this support will look like. A client can likely just define a new model to represent a sparse population of another model in a very specific use case. On the server side, it becomes much more appealing to be able to support arbitrary combinations of omitted fields.
 - [ ] Create more descriptive errors that are easier to use for troubleshooting.
 
 ### JSONAPITestLib
@@ -73,6 +130,7 @@ Note that Playground support for importing non-system Frameworks is still a bit
 ### Potential Improvements
 - [ ] (Maybe) Use `KeyPath` to specify `Includes` thus creating type safety around the relationship between a primary resource type and the types of included resources.
 - [ ] (Maybe) Replace `SingleResourceBody` and `ManyResourceBody` with support at the `Document` level to just interpret `PrimaryResource`, `PrimaryResource?`, or `[PrimaryResource]` as the same decoding/encoding strategies.
+- [ ] Support sideposting. JSONAPI spec might become opinionated in the future (https://github.com/json-api/json-api/pull/1197, https://github.com/json-api/json-api/issues/1215, https://github.com/json-api/json-api/issues/1216) but there is also an existing implementation to consider (https://jsonapi-suite.github.io/jsonapi_suite/ruby/writes/nested-writes). At this time, any sidepost implementation would be an awesome tertiary library to be used alongside the primary JSONAPI library. Maybe `JSONAPISideloading`.
 - [ ] Property-based testing (using `SwiftCheck`).
 - [ ] Error or warning if an included entity is not related to a primary entity or another included entity (Turned off or at least not throwing by default).
 
@@ -86,7 +144,7 @@ An `EntityDescription` is the `JSONAPI` framework's representation of what the *
 
 ```
 enum PersonDescription: IdentifiedEntityDescription {
-	static var type: String { return "people" }
+	static var jsonType: String { return "people" }
 
 	struct Attributes: JSONAPI.Attributes {
 		let name: Attribute<[String]>
@@ -100,7 +158,7 @@ enum PersonDescription: IdentifiedEntityDescription {
 ```
 
 The requirements of an `EntityDescription` are:
-1. A static `var` "type" that matches the JSON type; The **SPEC** requires every *Resource Object* to have a "type".
+1. A static `var` "jsonType" that matches the JSON type; The **SPEC** requires every *Resource Object* to have a "type".
 2. A `struct` of `Attributes` **- OR -** `typealias Attributes = NoAttributes`
 3. A `struct` of `Relationships` **- OR -** `typealias Relationships = NoRelationships`
 
@@ -227,6 +285,11 @@ typealias Attributes = NoAttributes
 let favoriteColor: String = person[\.favoriteColor]
 ```
 
+NOTE: Because of support for computed properties that are not wrapped in `Attribute`, `TransformedAttribute`, or `ValidatedAttribute`, the compiler cannot always infer the type of thing you want back when using subscript attribute access. The following code is ambiguous about whether it should return a `String` or an `Attribute<String>`:
+```
+let favoriteColor = person[\.favoriteColor]
+```
+
 #### `Transformer`
 
 Sometimes you need to use a type that does not encode or decode itself in the way you need to represent it as a serialized JSON object. For example, the Swift `Foundation` type `Date` can encode/decode itself to `Double` out of the box, but you might want to represent dates as ISO 8601 compliant `String`s instead. The Foundation library `JSONDecoder` has a setting to make this adjustment, but for the sake of an example, you could create a `Transformer`.
@@ -265,7 +328,7 @@ You can also creator `Validators` and `ValidatedAttribute`s. A `Validator` is ju
 
 #### Computed `Attribute`
 
-You can add computed properties to your `EntityDescription.Attributes` struct if you would like to expose attributes that are not explicitly represented by the JSON. These computed properties should still have the type `Attribute` because that way you can take advantage of the quick access provided by `Entity`'s subscript operator. Here's an example of how you might take the `Person[\.name]` attribute from the example above and create a `fullName` computed property.
+You can add computed properties to your `EntityDescription.Attributes` struct if you would like to expose attributes that are not explicitly represented by the JSON. These computed properties do not have to be wrapped in `Attribute`, `ValidatedAttribute`, or `TransformedAttribute`. This allows computed attributes to be of types that are not `Codable`. Here's an example of how you might take the `Person[\.name]` attribute from the example above and create a `fullName` computed property.
 
 ```
 public var fullName: Attribute<String> {
@@ -273,6 +336,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:
@@ -377,5 +457,293 @@ extension String: CreatableRawIdType {
 }
 ```
 
-# JSONAPITestLib
+### Custom Attribute or Relationship Key Mapping
+There is not anything special going on at the `JSONAPI.Attributes` and `JSONAPI.Relationships` levels, so you can easily provide custom key mappings by taking advantage of `Codable`'s `CodingKeys` pattern. Here are two models that will encode/decode equivalently but offer different naming in your codebase:
+```
+public enum EntityDescription1: JSONAPI.EntityDescription {
+	public static var jsonType: String { return "entity" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let coolProperty: Attribute<String>
+	}
+
+	public typealias Relationships = NoRelationships
+}
+
+public enum EntityDescription2: JSONAPI.EntityDescription {
+	public static var jsonType: String { return "entity" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let wholeOtherThing: Attribute<String>
+
+		enum CodingKeys: String, CodingKey {
+			case wholeOtherThing = "coolProperty"
+		}
+	}
+}
+```
+
+### Custom Attribute Encode/Decode
+You can safely provide your own encoding or decoding functions for your Attributes struct if you need to as long as you are careful that your encode operation correctly reverses your decode operation. Although this is generally not necessary, `AttributeType` provides a convenience method to make your decoding a bit less boilerplate ridden. This is what it looks like:
+```
+public enum EntityDescription1: JSONAPI.EntityDescription {
+	public static var jsonType: String { return "entity" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let property1: Attribute<String>
+		public let property2: Attribute<Int>
+		public let property3: Attribute<String>
+
+		public let weirdThing: Attribute<String>
+
+		enum CodingKeys: String, CodingKey {
+			case property1
+			case property2
+			case property3
+		}
+	}
+
+	public typealias Relationships = NoRelationships
+}
+
+extension EntityDescription1.Attributes {
+	public init(from decoder: Decoder) throws {
+		let container = try decoder.container(keyedBy: CodingKeys.self)
+
+		property1 = try .defaultDecoding(from: container, forKey: .property1)
+		property2 = try .defaultDecoding(from: container, forKey: .property2)
+		property3 = try .defaultDecoding(from: container, forKey: .property3)
+
+		weirdThing = .init(value: "hello world")
+	}
+
+	public func encode(to encoder: Encoder) throws {
+		var container = encoder.container(keyedBy: CodingKeys.self)
+
+		try container.encode(property1, forKey: .property1)
+		try container.encode(property2, forKey: .property2)
+		try container.encode(property3, forKey: .property3)
+	}
+}
+```
+
+### Meta-attributes
+This advanced feature may not ever be useful, but if you find yourself in the situation of dealing with an API that does not 100% follow the **SPEC** then you might find meta-attributes are just the thing to make your entities more natural to work with.
+
+Suppose, for example, you are presented with the unfortunate situation where a piece of information you need is only available as part of the `Id` of an entity. Perhaps a user's `Id` is formatted "{integer}-{createdAt}" where "createdAt" is the unix timestamp when the user account was created. The following `UserDescription` will expose what you need as an attribute. Realistically, this code is still terrible for its error handling. Using a `Result` type and/or invariants would clean things up substantially.
+
+```
+enum UserDescription: EntityDescription {
+	public static var jsonType: String { return "users" }
+
+	struct Attributes: JSONAPI.Attributes {
+		var createdAt: (User) -> Date {
+			return { user in
+				let components = user.id.rawValue.split(separator: "-")
+
+				guard components.count == 2 else {
+					assertionFailure()
+					return Date()
+				}
+
+				let timestamp = TimeInterval(components[1])
+
+				guard let date = timestamp.map(Date.init(timeIntervalSince1970:)) else {
+					assertionFailure()
+					return Date()
+				}
+
+				return date
+			}
+		}
+	}
+
+	typealias Relationships = NoRelationships
+}
+
+typealias User = JSONAPI.Entity<UserDescription, NoMetadata, NoLinks, String>
+```
+
+Given a value `user` of the above entity type, you can access the `createdAt` attribute just like you would any other:
+
+```
+let createdAt = user[\.createdAt]
+```
+
+This works because `createdAt` is defined in the form: `var {name}: ({Entity}) -> {Value}` where `{Entity}` is the `JSONAPI.Entity` described by the `EntityDescription` containing the meta-attribute.
+
+## Example
+The following serves as a sort of pseudo-example. It skips server/client implementation details not related to JSON:API but still gives a more complete picture of what an implementation using this framework might look like. You can play with this example code in the Playground provided with this repo.
+
+### Preamble (Setup shared by server and client)
+```
+// We make String a CreatableRawIdType.
+var GlobalStringId: Int = 0
+extension String: CreatableRawIdType {
+	public static func unique() -> String {
+		GlobalStringId += 1
+		return String(GlobalStringId)
+	}
+}
+
+// We create a typealias given that we do not expect JSON:API Resource
+// Objects for this particular API to have Metadata or Links associated
+// with them. We also expect them to have String Identifiers.
+typealias JSONEntity<Description: EntityDescription> = JSONAPI.Entity<Description, NoMetadata, NoLinks, String>
+
+// Similarly, we create a typealias for unidentified entities. JSON:API
+// only allows unidentified entities (i.e. no "id" field) for client
+// requests that create new entities. In these situations, the server
+// is expected to assign the new entity a unique ID.
+typealias UnidentifiedJSONEntity<Description: EntityDescription> = JSONAPI.Entity<Description, NoMetadata, NoLinks, Unidentified>
+
+// We create typealiases given that we do not expect JSON:API Relationships
+// for this particular API to have Metadata or Links associated
+// with them.
+typealias ToOneRelationship<Entity: Identifiable> = JSONAPI.ToOneRelationship<Entity, NoMetadata, NoLinks>
+typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoMetadata, NoLinks>
+
+// We create a typealias for a Document given that we do not expect
+// JSON:API Documents for this particular API to have Metadata, Links,
+// useful Errors, or a JSON:API Object (i.e. APIDescription).
+typealias Document<PrimaryResourceBody: JSONAPI.ResourceBody, IncludeType: JSONAPI.Include> = JSONAPI.Document<PrimaryResourceBody, NoMetadata, NoLinks, IncludeType, NoAPIDescription, UnknownJSONAPIError>
+
+// MARK: Entity Definitions
+
+enum AuthorDescription: EntityDescription {
+	public static var jsonType: String { return "authors" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let name: Attribute<String>
+	}
+
+	public typealias Relationships = NoRelationships
+}
+
+typealias Author = JSONEntity<AuthorDescription>
+
+enum ArticleDescription: EntityDescription {
+	public static var jsonType: String { return "articles" }
+
+	public struct Attributes: JSONAPI.Attributes {
+		public let title: Attribute<String>
+		public let abstract: Attribute<String>
+	}
+
+	public struct Relationships: JSONAPI.Relationships {
+		public let author: ToOneRelationship<Author>
+	}
+}
+
+typealias Article = JSONEntity<ArticleDescription>
+
+// MARK: Document Definitions
+
+// We create a typealias to represent a document containing one Article
+// and including its Author
+typealias SingleArticleDocumentWithIncludes = Document<SingleResourceBody<Article>, Include1<Author>>
+
+// ... and a typealias to represent a document containing one Article and
+// not including any related entities.
+typealias SingleArticleDocument = Document<SingleResourceBody<Article>, NoIncludes>
+```
+### Server Pseudo-example
+```
+// Skipping over all the API and database stuff, here's a chunk of code
+// that creates a document. Note that this document is the entirety
+// of a JSON:API response body.
+func articleDocument(includeAuthor: Bool) -> Either<SingleArticleDocument, SingleArticleDocumentWithIncludes> {
+	// Let's pretend all of this is coming from a database:
+
+	let authorId = Author.Identifier(rawValue: "1234")
+
+	let article = Article(id: .init(rawValue: "5678"),
+						  attributes: .init(title: .init(value: "JSON:API in Swift"),
+											abstract: .init(value: "Not yet written")),
+						  relationships: .init(author: .init(id: authorId)),
+						  meta: .none,
+						  links: .none)
+
+	let document = SingleArticleDocument(apiDescription: .none,
+										 body: .init(entity: article),
+										 includes: .none,
+										 meta: .none,
+										 links: .none)
+
+	switch includeAuthor {
+	case false:
+		return .a(document)
+
+	case true:
+		let author = Author(id: authorId,
+							attributes: .init(name: .init(value: "Janice Bluff")),
+							relationships: .none,
+							meta: .none,
+							links: .none)
+
+		let includes: Includes<SingleArticleDocumentWithIncludes.Include> = .init(values: [.init(author)])
+
+		return .b(document.including(.init(values: [.init(author)])))
+	}
+}
+
+let encoder = JSONEncoder()
+encoder.keyEncodingStrategy = .convertToSnakeCase
+encoder.outputFormatting = .prettyPrinted
+
+let responseBody = articleDocument(includeAuthor: true)
+let responseData = try! encoder.encode(responseBody)
+
+// Next step would be encoding and setting as the HTTP body of a response.
+// we will just print it out instead:
+print("-----")
+print(String(data: responseData, encoding: .utf8)!)
+
+// ... and if we had received a request for an article without
+// including the author:
+let otherResponseBody = articleDocument(includeAuthor: false)
+let otherResponseData = try! encoder.encode(otherResponseBody)
+print("-----")
+print(String(data: otherResponseData, encoding: .utf8)!)
+```
+
+### Client Pseudo-example
+```
+enum NetworkError: Swift.Error {
+	case serverError
+	case quantityMismatch
+}
+
+// Skipping over all the API stuff, here's a chunk of code that will
+// decode a document. We will assume we have made a request for a
+// single article including the author.
+func docode(articleResponseData: Data) throws -> (article: Article, author: Author) {
+	let decoder = JSONDecoder()
+	decoder.keyDecodingStrategy = .convertFromSnakeCase
+
+	let articleDocument = try decoder.decode(SingleArticleDocumentWithIncludes.self, from: articleResponseData)
+
+	switch articleDocument.body {
+	case .data(let data):
+		let authors = data.includes[Author.self]
+
+		guard authors.count == 1 else {
+			throw NetworkError.quantityMismatch
+		}
+
+		return (article: data.primary.value, author: authors[0])
+	case .errors(let errors, meta: _, links: _):
+		throw NetworkError.serverError
+	}
+}
+
+let response = try! docode(articleResponseData: responseData)
+
+// Next step would be to do something useful with the article and author but we will print them instead.
+print("-----")
+print(response.article)
+print(response.author)
+```
+
+## JSONAPITestLib
 The `JSONAPI` framework is packaged with a test library to help you test your `JSONAPI` integration. The test library is called `JSONAPITestLib`. It provides literal expressibility for `Attribute`, `ToOneRelationship`, and `Id` in many situations so that you can easily write test `Entity` values into your unit tests. It also provides a `check()` function for each `Entity` type that can be used to catch problems with your `JSONAPI` structures that are not caught by Swift's type system. You can see the `JSONAPITestLib` in action in the Playground included with the `JSONAPI` repository.

Sources/JSONAPI/Document/APIDescription.swift

@@ -14,8 +14,15 @@ public protocol APIDescriptionType: Codable, Equatable {
 public struct APIDescription<Meta: JSONAPI.Meta>: APIDescriptionType {
 	public let version: String
 	public let meta: Meta
+
+	public init(version: String, meta: Meta) {
+		self.version = version
+		self.meta = meta
+	}
 }
 
+/// Can be used as `APIDescriptionType` for Documents that do not
+/// have any API Description (a.k.a. "JSON:API Object").
 public struct NoAPIDescription: APIDescriptionType, CustomStringConvertible {
 	public typealias Meta = NoMetadata
 

Sources/JSONAPI/Document/Document.swift

@@ -110,11 +110,16 @@ public struct Document<PrimaryResourceBody: JSONAPI.ResourceBody, MetaType: JSON
 		self.apiDescription = apiDescription
 	}
 
-	public init(apiDescription: APIDescription, body: PrimaryResourceBody, includes: Includes<Include>, meta: MetaType, links: LinksType) {
+	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) {
@@ -189,6 +194,74 @@ extension Document where IncludeType == NoIncludes, MetaType == NoMetadata, Link
 }
 */
 
+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 })
+	}
+}
+
+extension Document where IncludeType == NoIncludes {
+	/// Create a new Document with the given includes.
+	public func including<I: JSONAPI.Include>(_ includes: Includes<I>) -> Document<PrimaryResourceBody, MetaType, LinksType, I, APIDescription, Error> {
+		// Note that if IncludeType is NoIncludes, then we allow anything
+		// to be included, but if IncludeType already specifies a type
+		// of thing to be expected then we lock that down.
+		// See: Document.including() where IncludeType: _Poly1
+		switch body {
+		case .data(let data):
+			return .init(apiDescription: apiDescription,
+						 body: data.primary,
+						 includes: includes,
+						 meta: data.meta,
+						 links: data.links)
+		case .errors(let errors, meta: let meta, links: let links):
+			return .init(apiDescription: apiDescription,
+						 errors: errors,
+						 meta: meta,
+						 links: links)
+		}
+	}
+}
+
+// extending where _Poly1 means all non-zero _Poly arities are included
+extension Document where IncludeType: _Poly1 {
+	/// Create a new Document adding the given includes. This does not
+	/// remove existing includes; it is additive.
+	public func including(_ includes: Includes<IncludeType>) -> Document {
+		// Note that if IncludeType is NoIncludes, then we allow anything
+		// to be included, but if IncludeType already specifies a type
+		// of thing to be expected then we lock that down.
+		// See: Document.including() where IncludeType == NoIncludes
+		switch body {
+		case .data(let data):
+			return .init(apiDescription: apiDescription,
+						 body: data.primary,
+						 includes: data.includes + includes,
+						 meta: data.meta,
+						 links: data.links)
+		case .errors(let errors, meta: let meta, links: let links):
+			return .init(apiDescription: apiDescription,
+						 errors: errors,
+						 meta: meta,
+						 links: links)
+		}
+	}
+}
+
+// MARK: - Codable
 extension Document {
 	private enum RootCodingKeys: String, CodingKey {
 		case data

Sources/JSONAPI/Document/Includes.swift

@@ -50,6 +50,16 @@ public struct Includes<I: Include>: Codable, Equatable {
 	}
 }
 
+extension Includes {
+	public func appending(_ other: Includes<I>) -> Includes {
+		return Includes(values: values + other.values)
+	}
+}
+
+public func +<I: Include>(_ left: Includes<I>, _ right: Includes<I>) -> Includes<I> {
+	return left.appending(right)
+}
+
 extension Includes: CustomStringConvertible {
 	public var description: String {
 		return "Includes(\(String(describing: values))"
@@ -123,3 +133,17 @@ extension Includes where I: _Poly7 {
 }
 
 // MARK: - 8 includes
+public typealias Include8 = Poly8
+extension Includes where I: _Poly8 {
+	public subscript(_ lookup: I.H.Type) -> [I.H] {
+		return values.compactMap { $0.h }
+	}
+}
+
+// MARK: - 9 includes
+public typealias Include9 = Poly9
+extension Includes where I: _Poly9 {
+	public subscript(_ lookup: I.I.Type) -> [I.I] {
+		return values.compactMap { $0.i }
+	}
+}

Sources/JSONAPI/Document/ResourceBody.swift

@@ -19,6 +19,14 @@ extension Optional: MaybePrimaryResource where Wrapped: PrimaryResource {}
 public protocol ResourceBody: Codable, Equatable {
 }
 
+public protocol AppendableResourceBody: ResourceBody {
+	func appending(_ other: Self) -> Self
+}
+
+public func +<R: AppendableResourceBody>(_ left: R, right: R) -> R {
+	return left.appending(right)
+}
+
 public struct SingleResourceBody<Entity: JSONAPI.MaybePrimaryResource>: ResourceBody {
 	public let value: Entity
 
@@ -27,12 +35,16 @@ public struct SingleResourceBody<Entity: JSONAPI.MaybePrimaryResource>: Resource
 	}
 }
 
-public struct ManyResourceBody<Entity: JSONAPI.PrimaryResource>: ResourceBody {
+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)
+	}
 }
 
 /// Use NoResourceBody to indicate you expect a JSON API document to not

Sources/JSONAPI/Resource/Attribute+Functor.swift

@@ -19,3 +19,18 @@ public extension TransformedAttribute {
 		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

@@ -6,9 +6,14 @@
 //
 
 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
@@ -21,16 +26,19 @@ 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 == 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 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)
@@ -45,15 +53,35 @@ extension TransformedAttribute: CustomStringConvertible {
 
 extension TransformedAttribute: Equatable where Transformer.From: Equatable, Transformer.To: Equatable {}
 
-extension TransformedAttribute where Transformer == IdentityTransformer<RawValue> {
-	// If we are using the identity transform, we can skip the transform and guarantee no
-	// error is thrown.
+// 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) {
-		rawValue = value
-		self.value = value
+		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 TransformedAttribute {
 	public init(from decoder: Decoder) throws {
@@ -84,3 +112,36 @@ extension TransformedAttribute {
 		try container.encode(rawValue)
 	}
 }
+
+extension Attribute {
+	public init(from decoder: Decoder) throws {
+		let container = try decoder.singleValueContainer()
+
+		// 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)
+	}
+}
+
+// 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)
+	}
+}

Sources/JSONAPI/Resource/Entity.swift

@@ -8,11 +8,11 @@
 /// A JSON API structure within an Entity that contains
 /// named properties of types `ToOneRelationship` and
 /// `ToManyRelationship`.
-public typealias Relationships = Codable & Equatable
+public protocol Relationships: Codable & Equatable {}
 
 /// A JSON API structure within an Entity that contains
 /// properties of any types that are JSON encodable.
-public typealias Attributes = Codable & Equatable
+public protocol Attributes: Codable & Equatable {}
 
 /// Can be used as `Relationships` Type for Entities that do not
 /// have any Relationships.
@@ -20,16 +20,31 @@ public struct NoRelationships: Relationships {
 	public static var none: NoRelationships { return .init() }
 }
 
+extension NoRelationships: CustomStringConvertible {
+	public var description: String { return "No Relationships" }
+}
+
 /// Can be used as `Attributes` Type for Entities that do not
 /// have any Attributes.
 public struct NoAttributes: Attributes {
 	public static var none: NoAttributes { return .init() }
 }
 
+extension NoAttributes: CustomStringConvertible {
+	public var description: String { return "No Attributes" }
+}
+
 /// Something that is JSONTyped provides a String representation
 /// of its type.
 public protocol JSONTyped {
-	static var type: String { get }
+	static var jsonType: 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
@@ -37,16 +52,13 @@ public protocol JSONTyped {
 /// itself is encoded and decoded as an
 /// `Entity`, which gets specialized on an
 /// `EntityDescription`.
-public protocol EntityDescription: JSONTyped {
-	associatedtype Attributes: JSONAPI.Attributes
-	associatedtype Relationships: JSONAPI.Relationships
-}
+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, JSONTyped {
-	associatedtype Description: EntityDescription
+	associatedtype Description: EntityProxyDescription
 	associatedtype EntityRawIdType: JSONAPI.MaybeRawId
 
 	typealias Id = JSONAPI.Id<EntityRawIdType, Self>
@@ -69,13 +81,13 @@ public protocol EntityProxy: Equatable, JSONTyped {
 
 extension EntityProxy {
 	/// The JSON API compliant "type" of this `Entity`.
-	public static var type: String { return Description.type }
+	public static var jsonType: String { return Description.jsonType }
 }
 
 /// 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
 }
@@ -124,7 +136,7 @@ extension Entity: Identifiable, IdentifiableEntityType, Relatable where EntityRa
 
 extension Entity: CustomStringConvertible {
 	public var description: String {
-		return "Entity<\(Entity.type)>(id: \(String(describing: id)), attributes: \(String(describing: attributes)), relationships: \(String(describing: relationships)))"
+		return "Entity<\(Entity.jsonType)>(id: \(String(describing: id)), attributes: \(String(describing: attributes)), relationships: \(String(describing: relationships)))"
 	}
 }
 
@@ -429,21 +441,21 @@ public extension EntityProxy {
 	/// Access the attribute at the given keypath. This just
 	/// allows you to write `entity[\.propertyName]` instead
 	/// of `entity.relationships.propertyName`.
-	subscript<T, TFRM: Transformer>(_ path: KeyPath<Description.Attributes, TransformedAttribute<T, TFRM>>) -> TFRM.To {
+	subscript<T: AttributeType>(_ path: KeyPath<Description.Attributes, T>) -> T.ValueType {
 		return attributes[keyPath: path].value
 	}
 
 	/// Access the attribute at the given keypath. This just
 	/// allows you to write `entity[\.propertyName]` instead
 	/// of `entity.relationships.propertyName`.
-	subscript<T, TFRM: Transformer>(_ path: KeyPath<Description.Attributes, TransformedAttribute<T, TFRM>?>) -> TFRM.To? {
+	subscript<T: AttributeType>(_ path: KeyPath<Description.Attributes, T?>) -> T.ValueType? {
 		return attributes[keyPath: path]?.value
 	}
 
 	/// Access the attribute at the given keypath. This just
 	/// 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? {
+	subscript<T: AttributeType, U>(_ path: KeyPath<Description.Attributes, T?>) -> U? where T.ValueType == U? {
 		// Implementation Note: Handles Transform that returns optional
 		// type.
 		return attributes[keyPath: path].flatMap { $0.value }
@@ -459,6 +471,15 @@ public extension EntityProxy {
 	}
 }
 
+// MARK: Meta-Attribute Access
+public extension EntityProxy {
+	/// Access an attribute requiring a transformation on the RawValue _and_
+	/// a secondary transformation on this entity (self).
+	subscript<T>(_ path: KeyPath<Description.Attributes, (Self) -> T>) -> T {
+		return attributes[keyPath: path](self)
+	}
+}
+
 // MARK: Relationship Access
 public extension EntityProxy {
 	/// Access to an Id of a `ToOneRelationship`.
@@ -517,7 +538,7 @@ public extension Entity {
 	public func encode(to encoder: Encoder) throws {
 		var container = encoder.container(keyedBy: ResourceObjectCodingKeys.self)
 		
-		try container.encode(Entity.type, forKey: .type)
+		try container.encode(Entity.jsonType, forKey: .type)
 		
 		if EntityRawIdType.self != Unidentified.self {
 			try container.encode(id, forKey: .id)
@@ -546,15 +567,16 @@ public extension Entity {
 		
 		let type = try container.decode(String.self, forKey: .type)
 		
-		guard Entity.type == type else {
-			throw JSONAPIEncodingError.typeMismatch(expected: Description.type, found: type)
+		guard Entity.jsonType == type else {
+			throw JSONAPIEncodingError.typeMismatch(expected: Description.jsonType, found: type)
 		}
 
 		let maybeUnidentified = Unidentified() as? EntityRawIdType
 		id = try maybeUnidentified.map { Entity.Id(rawValue: $0) } ?? container.decode(Entity.Id.self, forKey: .id)
-		
-		attributes = try (NoAttributes() as? Description.Attributes) ?? container.decode(Description.Attributes.self, forKey: .attributes)
-		
+
+		attributes = try (NoAttributes() as? Description.Attributes) ??
+			container.decode(Description.Attributes.self, forKey: .attributes)
+
 		relationships = try (NoRelationships() as? Description.Relationships) ?? container.decode(Description.Relationships.self, forKey: .relationships)
 
 		meta = try (NoMetadata() as? MetaType) ?? container.decode(MetaType.self, forKey: .meta)

Sources/JSONAPI/Resource/Poly.swift

@@ -17,14 +17,14 @@ public protocol Poly: PrimaryResource {}
 
 // MARK: - Generic Decoding
 
-private func decode<Entity: JSONAPI.EntityType>(_ type: Entity.Type, from container: SingleValueDecodingContainer) throws -> Result<Entity, DecodingError> {
-	let ret: Result<Entity, DecodingError>
+private func decode<Thing: Codable>(_ type: Thing.Type, from container: SingleValueDecodingContainer) throws -> Result<Thing, DecodingError> {
+	let ret: Result<Thing, DecodingError>
 	do {
-		ret = try .success(container.decode(Entity.self))
+		ret = try .success(container.decode(Thing.self))
 	} catch (let err as DecodingError) {
 		ret = .failure(err)
 	} catch (let err) {
-		ret = .failure(DecodingError.typeMismatch(Entity.Description.self,
+		ret = .failure(DecodingError.typeMismatch(Thing.self,
 												  .init(codingPath: container.codingPath,
 														debugDescription: String(describing: err),
 														underlyingError: err)))
@@ -47,9 +47,11 @@ public struct Poly0: _Poly0 {
 	}
 }
 
+public typealias PolyWrapped = Codable & Equatable
+
 // MARK: - 1 type
 public protocol _Poly1: _Poly0 {
-	associatedtype A: EntityType
+	associatedtype A: PolyWrapped
 	var a: A? { get }
 
 	init(_ a: A)
@@ -61,7 +63,7 @@ public extension _Poly1 {
 	}
 }
 
-public enum Poly1<A: EntityType>: _Poly1 {
+public enum Poly1<A: PolyWrapped>: _Poly1 {
 	case a(A)
 
 	public var a: A? {
@@ -102,7 +104,7 @@ extension Poly1: CustomStringConvertible {
 
 // MARK: - 2 types
 public protocol _Poly2: _Poly1 {
-	associatedtype B: EntityType
+	associatedtype B: PolyWrapped
 	var b: B? { get }
 
 	init(_ b: B)
@@ -114,7 +116,9 @@ public extension _Poly2 {
 	}
 }
 
-public enum Poly2<A: EntityType, B: EntityType>: _Poly2 {
+public typealias Either = Poly2
+
+public enum Poly2<A: PolyWrapped, B: PolyWrapped>: _Poly2 {
 	case a(A)
 	case b(B)
 
@@ -181,7 +185,7 @@ extension Poly2: CustomStringConvertible {
 
 // MARK: - 3 types
 public protocol _Poly3: _Poly2 {
-	associatedtype C: EntityType
+	associatedtype C: PolyWrapped
 	var c: C? { get }
 
 	init(_ c: C)
@@ -193,7 +197,7 @@ public extension _Poly3 {
 	}
 }
 
-public enum Poly3<A: EntityType, B: EntityType, C: EntityType>: _Poly3 {
+public enum Poly3<A: PolyWrapped, B: PolyWrapped, C: PolyWrapped>: _Poly3 {
 	case a(A)
 	case b(B)
 	case c(C)
@@ -275,7 +279,7 @@ extension Poly3: CustomStringConvertible {
 
 // MARK: - 4 types
 public protocol _Poly4: _Poly3 {
-	associatedtype D: EntityType
+	associatedtype D: PolyWrapped
 	var d: D? { get }
 
 	init(_ d: D)
@@ -287,7 +291,7 @@ public extension _Poly4 {
 	}
 }
 
-public enum Poly4<A: EntityType, B: EntityType, C: EntityType, D: EntityType>: _Poly4 {
+public enum Poly4<A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped>: _Poly4 {
 	case a(A)
 	case b(B)
 	case c(C)
@@ -384,7 +388,7 @@ extension Poly4: CustomStringConvertible {
 
 // MARK: - 5 types
 public protocol _Poly5: _Poly4 {
-	associatedtype E: EntityType
+	associatedtype E: PolyWrapped
 	var e: E? { get }
 
 	init(_ e: E)
@@ -396,7 +400,7 @@ public extension _Poly5 {
 	}
 }
 
-public enum Poly5<A: EntityType, B: EntityType, C: EntityType, D: EntityType, E: EntityType>: _Poly5 {
+public enum Poly5<A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped>: _Poly5 {
 	case a(A)
 	case b(B)
 	case c(C)
@@ -508,7 +512,7 @@ extension Poly5: CustomStringConvertible {
 
 // MARK: - 6 types
 public protocol _Poly6: _Poly5 {
-	associatedtype F: EntityType
+	associatedtype F: PolyWrapped
 	var f: F? { get }
 
 	init(_ f: F)
@@ -520,7 +524,7 @@ public extension _Poly6 {
 	}
 }
 
-public enum Poly6<A: EntityType, B: EntityType, C: EntityType, D: EntityType, E: EntityType, F: EntityType>: _Poly6 {
+public enum Poly6<A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped>: _Poly6 {
 	case a(A)
 	case b(B)
 	case c(C)
@@ -647,7 +651,7 @@ extension Poly6: CustomStringConvertible {
 
 // MARK: - 7 types
 public protocol _Poly7: _Poly6 {
-	associatedtype G: EntityType
+	associatedtype G: PolyWrapped
 	var g: G? { get }
 
 	init(_ g: G)
@@ -659,7 +663,7 @@ public extension _Poly7 {
 	}
 }
 
-public enum Poly7<A: EntityType, B: EntityType, C: EntityType, D: EntityType, E: EntityType, F: EntityType, G: EntityType>: _Poly7 {
+public enum Poly7<A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped, G: PolyWrapped>: _Poly7 {
 	case a(A)
 	case b(B)
 	case c(C)
@@ -799,3 +803,360 @@ extension Poly7: CustomStringConvertible {
 		return "Poly(\(str))"
 	}
 }
+
+// MARK: - 8 types
+public protocol _Poly8: _Poly7 {
+	associatedtype H: PolyWrapped
+	var h: H? { get }
+
+	init(_ h: H)
+}
+
+public extension _Poly8 {
+	subscript(_ lookup: H.Type) -> H? {
+		return h
+	}
+}
+
+public enum Poly8<A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped, G: PolyWrapped, H: PolyWrapped>: _Poly8 {
+	case a(A)
+	case b(B)
+	case c(C)
+	case d(D)
+	case e(E)
+	case f(F)
+	case g(G)
+	case h(H)
+
+	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 var h: H? {
+		guard case let .h(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ h: H) {
+		self = .h(h)
+	}
+
+	public init(from decoder: Decoder) throws {
+		let container = try decoder.singleValueContainer()
+
+		let attempts = [
+			try decode(A.self, from: container).map { Poly8.a($0) },
+			try decode(B.self, from: container).map { Poly8.b($0) },
+			try decode(C.self, from: container).map { Poly8.c($0) },
+			try decode(D.self, from: container).map { Poly8.d($0) },
+			try decode(E.self, from: container).map { Poly8.e($0) },
+			try decode(F.self, from: container).map { Poly8.f($0) },
+			try decode(G.self, from: container).map { Poly8.g($0) },
+			try decode(H.self, from: container).map { Poly8.h($0) }]
+
+		let maybeVal: Poly8<A, B, C, D, E, F, G, H>? = attempts
+			.compactMap { $0.value }
+			.first
+
+		guard let val = maybeVal else {
+			throw EncodingError.invalidValue(Poly8<A, B, C, D, E, F, G, H>.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)
+		case .h(let h):
+			try container.encode(h)
+		}
+	}
+}
+
+extension Poly8: 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)
+		case .h(let h):
+			str = String(describing: h)
+		}
+
+		return "Poly(\(str))"
+	}
+}
+
+// MARK: - 9 types
+public protocol _Poly9: _Poly8 {
+	associatedtype I: PolyWrapped
+	var i: I? { get }
+
+	init(_ i: I)
+}
+
+public extension _Poly9 {
+	subscript(_ lookup: I.Type) -> I? {
+		return i
+	}
+}
+
+public enum Poly9<A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped, G: PolyWrapped, H: PolyWrapped, I: PolyWrapped>: _Poly9 {
+	case a(A)
+	case b(B)
+	case c(C)
+	case d(D)
+	case e(E)
+	case f(F)
+	case g(G)
+	case h(H)
+	case i(I)
+
+	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 var h: H? {
+		guard case let .h(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ h: H) {
+		self = .h(h)
+	}
+
+	public var i: I? {
+		guard case let .i(ret) = self else { return nil }
+		return ret
+	}
+
+	public init(_ i: I) {
+		self = .i(i)
+	}
+
+	public init(from decoder: Decoder) throws {
+		let container = try decoder.singleValueContainer()
+
+		let attempts = [
+			try decode(A.self, from: container).map { Poly9.a($0) },
+			try decode(B.self, from: container).map { Poly9.b($0) },
+			try decode(C.self, from: container).map { Poly9.c($0) },
+			try decode(D.self, from: container).map { Poly9.d($0) },
+			try decode(E.self, from: container).map { Poly9.e($0) },
+			try decode(F.self, from: container).map { Poly9.f($0) },
+			try decode(G.self, from: container).map { Poly9.g($0) },
+			try decode(H.self, from: container).map { Poly9.h($0) },
+			try decode(I.self, from: container).map { Poly9.i($0) }]
+
+		let maybeVal: Poly9<A, B, C, D, E, F, G, H, I>? = attempts
+			.compactMap { $0.value }
+			.first
+
+		guard let val = maybeVal else {
+			throw EncodingError.invalidValue(Poly9<A, B, C, D, E, F, G, H, I>.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)
+		case .h(let h):
+			try container.encode(h)
+		case .i(let i):
+			try container.encode(i)
+		}
+	}
+}
+
+extension Poly9: 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)
+		case .h(let h):
+			str = String(describing: h)
+		case .i(let i):
+			str = String(describing: i)
+		}
+
+		return "Poly(\(str))"
+	}
+}

Sources/JSONAPI/Resource/Relationship.swift

@@ -134,7 +134,7 @@ public protocol OptionalRelatable: Identifiable where Identifier == Wrapped.Iden
 extension Optional: Identifiable, OptionalRelatable, JSONTyped where Wrapped: JSONAPI.Relatable {
 	public typealias Identifier = Wrapped.Identifier?
 
-	public static var type: String { return Wrapped.type }
+	public static var jsonType: String { return Wrapped.jsonType }
 }
 
 // MARK: Codable
@@ -180,8 +180,8 @@ extension ToOneRelationship: Codable where Identifiable.Identifier: OptionalId {
 		
 		let type = try identifier.decode(String.self, forKey: .entityType)
 		
-		guard type == Identifiable.type else {
-			throw JSONAPIEncodingError.typeMismatch(expected: Identifiable.type, found: type)
+		guard type == Identifiable.jsonType else {
+			throw JSONAPIEncodingError.typeMismatch(expected: Identifiable.jsonType, found: type)
 		}
 		
 		id = Identifiable.Identifier(rawValue: try identifier.decode(Identifiable.Identifier.RawType.self, forKey: .id))
@@ -214,7 +214,7 @@ extension ToOneRelationship: Codable where Identifiable.Identifier: OptionalId {
 		var identifier = container.nestedContainer(keyedBy: ResourceIdentifierCodingKeys.self, forKey: .data)
 		
 		try identifier.encode(id.rawValue, forKey: .id)
-		try identifier.encode(Identifiable.type, forKey: .entityType)
+		try identifier.encode(Identifiable.jsonType, forKey: .entityType)
 	}
 }
 
@@ -242,8 +242,8 @@ extension ToManyRelationship: Codable {
 			
 			let type = try identifier.decode(String.self, forKey: .entityType)
 			
-			guard type == Relatable.type else {
-				throw JSONAPIEncodingError.typeMismatch(expected: Relatable.type, found: type)
+			guard type == Relatable.jsonType else {
+				throw JSONAPIEncodingError.typeMismatch(expected: Relatable.jsonType, found: type)
 			}
 			
 			newIds.append(Relatable.Identifier(rawValue: try identifier.decode(Relatable.Identifier.RawType.self, forKey: .id)))
@@ -268,7 +268,7 @@ extension ToManyRelationship: Codable {
 			var identifier = identifiers.nestedContainer(keyedBy: ResourceIdentifierCodingKeys.self)
 			
 			try identifier.encode(id.rawValue, forKey: .id)
-			try identifier.encode(Relatable.type, forKey: .entityType)
+			try identifier.encode(Relatable.jsonType, forKey: .entityType)
 		}
 	}
 }

Sources/JSONAPI/Resource/Transformer.swift

@@ -5,6 +5,7 @@
 //  Created by Mathew Polzin on 11/17/18.
 //
 
+/// A Transformer simply defines a static function that transforms a value.
 public protocol Transformer {
 	associatedtype From
 	associatedtype To
@@ -12,10 +13,13 @@ public protocol Transformer {
 	static func transform(_ value: From) throws -> To
 }
 
+/// ReversibleTransformers define a function that reverses the transform
+/// operation.
 public protocol ReversibleTransformer: Transformer {
 	static func reverse(_ value: To) throws -> From
 }
 
+/// The IdentityTransformer does not perform any transformation on a value.
 public enum IdentityTransformer<T>: ReversibleTransformer {
 	public static func transform(_ value: T) throws -> T { return value }
 	public static func reverse(_ value: T) throws -> T { return value }

Sources/JSONAPITestLib/Attribute+Literal.swift

@@ -1,7 +1,7 @@
 
 import JSONAPI
 
-extension TransformedAttribute: ExpressibleByUnicodeScalarLiteral where RawValue: ExpressibleByUnicodeScalarLiteral, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByUnicodeScalarLiteral where RawValue: ExpressibleByUnicodeScalarLiteral {
 	public typealias UnicodeScalarLiteralType = RawValue.UnicodeScalarLiteralType
 
 	public init(unicodeScalarLiteral value: RawValue.UnicodeScalarLiteralType) {
@@ -9,7 +9,7 @@ extension TransformedAttribute: ExpressibleByUnicodeScalarLiteral where RawValue
 	}
 }
 
-extension TransformedAttribute: ExpressibleByExtendedGraphemeClusterLiteral where RawValue: ExpressibleByExtendedGraphemeClusterLiteral, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByExtendedGraphemeClusterLiteral where RawValue: ExpressibleByExtendedGraphemeClusterLiteral {
 	public typealias ExtendedGraphemeClusterLiteralType = RawValue.ExtendedGraphemeClusterLiteralType
 
 	public init(extendedGraphemeClusterLiteral value: RawValue.ExtendedGraphemeClusterLiteralType) {
@@ -17,7 +17,7 @@ extension TransformedAttribute: ExpressibleByExtendedGraphemeClusterLiteral wher
 	}
 }
 
-extension TransformedAttribute: ExpressibleByStringLiteral where RawValue: ExpressibleByStringLiteral, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByStringLiteral where RawValue: ExpressibleByStringLiteral {
 	public typealias StringLiteralType = RawValue.StringLiteralType
 
 	public init(stringLiteral value: RawValue.StringLiteralType) {
@@ -25,13 +25,13 @@ extension TransformedAttribute: ExpressibleByStringLiteral where RawValue: Expre
 	}
 }
 
-extension TransformedAttribute: ExpressibleByNilLiteral where RawValue: ExpressibleByNilLiteral, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByNilLiteral where RawValue: ExpressibleByNilLiteral {
 	public init(nilLiteral: ()) {
 		self.init(value: RawValue(nilLiteral: ()))
 	}
 }
 
-extension TransformedAttribute: ExpressibleByFloatLiteral where RawValue: ExpressibleByFloatLiteral, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByFloatLiteral where RawValue: ExpressibleByFloatLiteral {
 	public typealias FloatLiteralType = RawValue.FloatLiteralType
 
 	public init(floatLiteral value: RawValue.FloatLiteralType) {
@@ -47,7 +47,7 @@ extension Optional: ExpressibleByFloatLiteral where Wrapped: ExpressibleByFloatL
 	}
 }
 
-extension TransformedAttribute: ExpressibleByBooleanLiteral where RawValue: ExpressibleByBooleanLiteral, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByBooleanLiteral where RawValue: ExpressibleByBooleanLiteral {
 	public typealias BooleanLiteralType = RawValue.BooleanLiteralType
 
 	public init(booleanLiteral value: BooleanLiteralType) {
@@ -63,7 +63,7 @@ extension Optional: ExpressibleByBooleanLiteral where Wrapped: ExpressibleByBool
 	}
 }
 
-extension TransformedAttribute: ExpressibleByIntegerLiteral where RawValue: ExpressibleByIntegerLiteral, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByIntegerLiteral where RawValue: ExpressibleByIntegerLiteral {
 	public typealias IntegerLiteralType = RawValue.IntegerLiteralType
 
 	public init(integerLiteral value: IntegerLiteralType) {
@@ -91,7 +91,7 @@ public protocol DictionaryType {
 }
 extension Dictionary: DictionaryType {}
 
-extension TransformedAttribute: ExpressibleByDictionaryLiteral where RawValue: DictionaryType, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByDictionaryLiteral where RawValue: DictionaryType {
 	public typealias Key = RawValue.Key
 
 	public typealias Value = RawValue.Value
@@ -121,7 +121,7 @@ public protocol ArrayType {
 extension Array: ArrayType {}
 extension ArraySlice: ArrayType {}
 
-extension TransformedAttribute: ExpressibleByArrayLiteral where RawValue: ArrayType, Transformer == IdentityTransformer<RawValue> {
+extension Attribute: ExpressibleByArrayLiteral where RawValue: ArrayType {
 	public typealias ArrayLiteralElement = RawValue.Element
 
 	public init(arrayLiteral elements: ArrayLiteralElement...) {

Sources/JSONAPITestLib/EntityCheck.swift

@@ -41,6 +41,7 @@ extension Optional: OptionalArray where Wrapped: ArrayType {}
 
 private protocol AttributeTypeWithOptionalArray {}
 extension TransformedAttribute: AttributeTypeWithOptionalArray where RawValue: OptionalArray {}
+extension Attribute: AttributeTypeWithOptionalArray where RawValue: OptionalArray {}
 
 private protocol OptionalRelationshipType {}
 extension Optional: OptionalRelationshipType where Wrapped: RelationshipType {}
@@ -49,6 +50,10 @@ private protocol _RelationshipType {}
 extension ToOneRelationship: _RelationshipType {}
 extension ToManyRelationship: _RelationshipType {}
 
+private protocol _AttributeType {}
+extension TransformedAttribute: _AttributeType {}
+extension Attribute: _AttributeType {}
+
 public extension Entity {
 	public static func check(_ entity: Entity) throws {
 		var problems = [EntityCheckError]()
@@ -60,7 +65,7 @@ public extension Entity {
 		}
 
 		for attribute in attributesMirror.children {
-			if attribute.value as? AttributeType == nil,
+			if attribute.value as? _AttributeType == nil,
 				attribute.value as? OptionalAttributeType == nil {
 				problems.append(.nonAttribute(named: attribute.label ?? "unnamed"))
 			}

Tests/JSONAPITests/Attribute/Attribute+FunctorTests.swift

@@ -38,7 +38,7 @@ class Attribute_FunctorTests: XCTestCase {
 // MARK: Test types
 extension Attribute_FunctorTests {
 	enum TestTypeDescription: EntityDescription {
-		public static var type: String { return "test" }
+		public static var jsonType: String { return "test" }
 
 		public struct Attributes: JSONAPI.Attributes {
 			let name: Attribute<String>

Tests/JSONAPITests/Attribute/AttributeTests.swift

@@ -10,12 +10,8 @@ import JSONAPI
 
 class AttributeTests: XCTestCase {
 
-	func test_AttributeIsTransformedAttribute() {
-		XCTAssertEqual(try TransformedAttribute<String, IdentityTransformer<String>>(rawValue: "hello"), try Attribute<String>(rawValue: "hello"))
-	}
-
-	func test_AttributeNonThrowingConstructor() {
-		XCTAssertEqual(try Attribute<String>(rawValue: "hello"), Attribute<String>(value: "hello"))
+	func test_AttributeConstructor() {
+		XCTAssertEqual(Attribute<String>(value: "hello").value, "hello")
 	}
 
 	func test_TransformedAttributeNoThrow() {

Tests/JSONAPITests/Computed Properties/ComputedPropertiesTests.swift

@@ -46,7 +46,7 @@ class ComputedPropertiesTests: XCTestCase {
 // MARK: Test types
 extension ComputedPropertiesTests {
 	public enum TestTypeDescription: EntityDescription {
-		public static var type: String { return "test" }
+		public static var jsonType: String { return "test" }
 
 		public struct Attributes: JSONAPI.Attributes {
 			public let name: Attribute<String>