Fix bug causing a supplied encoder to be used for generating an example but not for helping determine the correct Date formatting.

Add Include support to OpenAPI schema of JSONAPI Document.

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

@@ -0,0 +1,174 @@
+import Foundation
+import JSONAPI
+import Poly
+
+// 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/OpenAPI Documentation.xcplaygroundpage/Contents.swift

@@ -0,0 +1,30 @@
+//: [Previous](@previous)
+
+import Foundation
+import JSONAPI
+import JSONAPIOpenAPI
+
+// print Entity Schema
+let encoder = JSONEncoder()
+encoder.outputFormatting = .prettyPrinted
+
+let personSchemaData = try? encoder.encode(Person.openAPINode())
+
+print("Person Schema")
+print("====")
+print(personSchemaData.map { String(data: $0, encoding: .utf8)! } ?? "Schema Construction Failed")
+print("====")
+
+let dogDocumentSchemaData = try? encoder.encode(SingleDogDocument.openAPINodeWithExample(using: encoder))
+
+print("Dog Document Schema")
+print("====")
+print(dogDocumentSchemaData.map { String(data: $0, encoding: .utf8)! } ?? "Schema Construction Failed")
+print("====")
+
+let batchPersonSchemaData = try? encoder.encode(BatchPeopleDocument.openAPINodeWithExample(using: encoder))
+
+print("Batch Person Document Schema")
+print("====")
+print(batchPersonSchemaData.map { String(data: $0, encoding: .utf8)! } ?? "Schema Construction Failed")
+print("====")

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

@@ -2,7 +2,7 @@
 
 import Foundation
 import JSONAPI
-import JSONAPITestLib
+import JSONAPITesting
 
 /*******
 
@@ -11,12 +11,12 @@ Please enjoy these examples, but allow me the forced casting and the lack of err
 ********/
 
 // MARK: - Literal Expressibility
-// The JSONAPITestLib provides literal expressibility for key types to
+// The JSONAPITesting framework 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
+// The JSONAPITesting framework 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

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

@@ -11,8 +11,6 @@ Please enjoy these examples, but allow me the forced casting and the lack of err
 // 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)
@@ -34,8 +32,6 @@ let dogs = try! [Dog(name: "Buddy", owner: personIds[0]), Dog(name: "Joy", owner
 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)

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>
@@ -93,7 +93,7 @@ public typealias Dog = ExampleEntity<DogDescription>
 
 public enum AlternativeDogDescription: 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>
@@ -121,17 +121,17 @@ 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
@@ -139,4 +139,6 @@ public enum HouseDescription: EntityDescription {
 
 public typealias House = ExampleEntity<HouseDescription>
 
+public typealias SingleDogDocument = JSONAPI.Document<SingleResourceBody<Dog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, UnknownJSONAPIError>
 
+public typealias BatchPeopleDocument = JSONAPI.Document<ManyResourceBody<Person>, NoMetadata, NoLinks, Include2<Dog, House>, NoAPIDescription, UnknownJSONAPIError>

JSONAPI.playground/Sources/OpenAPISupport.swift

@@ -0,0 +1,71 @@
+import Foundation
+import JSONAPI
+import JSONAPITesting // for the convenience of literal initialization
+import JSONAPIOpenAPI
+import SwiftCheck
+import JSONAPIArbitrary
+
+extension PersonDescription.Attributes: Arbitrary, Sampleable {
+	public static var arbitrary: Gen<PersonDescription.Attributes> {
+		return Gen.compose { c in
+			return PersonDescription.Attributes(name: c.generate(),
+												favoriteColor: c.generate())
+		}
+	}
+
+	public static var sample: PersonDescription.Attributes {
+		return .init(name: ["Abbie", "Eibba"], favoriteColor: "Blue")
+	}
+}
+
+extension PersonDescription.Relationships: Arbitrary, Sampleable {
+	public static var arbitrary: Gen<PersonDescription.Relationships> {
+		return Gen.compose { c in
+			return PersonDescription.Relationships(friends: c.generate(),
+												   dogs: c.generate(),
+												   home: c.generate())
+		}
+	}
+
+	public static var sample: PersonDescription.Relationships {
+		return .init(friends: ["1", "2"], dogs: ["2"], home: "1")
+	}
+}
+
+extension DogDescription.Attributes: Arbitrary, Sampleable {
+	public static var arbitrary: Gen<DogDescription.Attributes> {
+		return Gen.compose { c in
+			return DogDescription.Attributes(name: c.generate())
+		}
+	}
+
+	public static var sample: DogDescription.Attributes {
+		return DogDescription.Attributes.arbitrary.generate
+	}
+}
+
+extension DogDescription.Relationships: Arbitrary, Sampleable {
+	public static var arbitrary: Gen<DogDescription.Relationships> {
+		return Gen.compose { c in
+			return DogDescription.Relationships(owner: c.generate())
+		}
+	}
+
+	public static var sample: DogDescription.Relationships {
+		return DogDescription.Relationships.arbitrary.generate
+	}
+}
+
+extension Document: Sampleable where PrimaryResourceBody: Arbitrary, IncludeType: Arbitrary, MetaType: Arbitrary, LinksType: Arbitrary, Error: Arbitrary, APIDescription: Arbitrary {
+	public static var sample: Document {
+		return Document.arbitrary.generate
+	}
+
+	public static var successSample: Document? {
+		return Document.arbitraryData.generate
+	}
+
+	public static var failureSample: Document? {
+		return Document.arbitraryErrors.generate
+	}
+}

JSONAPI.playground/contents.xcplayground

@@ -3,5 +3,7 @@
     <pages>
         <page name='Test Library'/>
         <page name='Usage'/>
+        <page name='Full Client &amp; Server Example'/>
+        <page name='Full Document Verbose Generation'/>
     </pages>
 </playground>

LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2018 Mathew Polzin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Package.resolved

@@ -1,7 +1,42 @@
 {
   "object": {
     "pins": [
-
+      {
+        "package": "AnyCodable",
+        "repositoryURL": "https://github.com/Flight-School/AnyCodable.git",
+        "state": {
+          "branch": null,
+          "revision": "396ccc3dba5bdee04c1e742e7fab40582861401e",
+          "version": "0.1.0"
+        }
+      },
+      {
+        "package": "FileCheck",
+        "repositoryURL": "https://github.com/llvm-swift/FileCheck.git",
+        "state": {
+          "branch": null,
+          "revision": "89b8480055f9adf8ce2f9ad5e2fac7ac1076242e",
+          "version": "0.0.8"
+        }
+      },
+      {
+        "package": "Poly",
+        "repositoryURL": "https://github.com/mattpolzin/Poly.git",
+        "state": {
+          "branch": null,
+          "revision": "77f45b8963a51c02d71fc4075eba5cff47ff0d07",
+          "version": "1.0.0"
+        }
+      },
+      {
+        "package": "SwiftCheck",
+        "repositoryURL": "https://github.com/typelift/SwiftCheck.git",
+        "state": {
+          "branch": null,
+          "revision": "cf9958085b2ee1643e541e407c3233d1b76c18ff",
+          "version": "0.11.0"
+        }
+      }
     ]
   },
   "version": 1

Package.swift

@@ -10,21 +10,45 @@ let package = Package(
             name: "JSONAPI",
             targets: ["JSONAPI"]),
 		.library(
-			name: "JSONAPITestLib",
-			targets: ["JSONAPITestLib"])
+			name: "JSONAPITesting",
+			targets: ["JSONAPITesting"]),
+		.library(
+			name: "JSONAPIArbitrary",
+			targets: ["JSONAPIArbitrary"]),
+        .library(
+            name: "JSONAPIOpenAPI",
+            targets: ["JSONAPIOpenAPI"])
     ],
     dependencies: [
+		.package(url: "https://github.com/mattpolzin/Poly.git", from: "1.0.0"),
+        .package(url: "https://github.com/Flight-School/AnyCodable.git", from: "0.1.0"),
+		.package(url: "https://github.com/typelift/SwiftCheck.git", from: "0.11.0")
     ],
     targets: [
         .target(
             name: "JSONAPI",
-            dependencies: []),
+            dependencies: ["Poly"]),
 		.target(
-			name: "JSONAPITestLib",
+			name: "JSONAPITesting",
 			dependencies: ["JSONAPI"]),
+		.target(
+			name: "JSONAPIArbitrary",
+			dependencies: ["JSONAPI", "SwiftCheck"]),
+        .target(
+            name: "JSONAPIOpenAPI",
+            dependencies: ["JSONAPI", "AnyCodable", "JSONAPIArbitrary"]),
         .testTarget(
             name: "JSONAPITests",
-            dependencies: ["JSONAPITestLib"])
+            dependencies: ["JSONAPI", "JSONAPITesting"]),
+        .testTarget(
+            name: "JSONAPITestingTests",
+            dependencies: ["JSONAPI", "JSONAPITesting"]),
+		.testTarget(
+			name: "JSONAPIArbitraryTests",
+			dependencies: ["JSONAPI", "SwiftCheck", "JSONAPIArbitrary"]),
+        .testTarget(
+            name: "JSONAPIOpenAPITests",
+            dependencies: ["JSONAPI", "JSONAPIOpenAPI"])
     ],
   	swiftLanguageVersions: [.v4_2]
 )

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

@@ -5,6 +5,8 @@
 //  Created by Mathew Polzin on 11/5/18.
 //
 
+import Poly
+
 public protocol JSONAPIDocument: Codable, Equatable {
 	associatedtype PrimaryResourceBody: JSONAPI.ResourceBody
 	associatedtype MetaType: JSONAPI.Meta
@@ -110,11 +112,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) {
@@ -208,6 +215,54 @@ extension Document.Body.Data where PrimaryResourceBody: AppendableResourceBody,
 	}
 }
 
+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 {

Sources/JSONAPI/Document/Includes.swift

@@ -5,7 +5,9 @@
 //  Created by Mathew Polzin on 11/10/18.
 //
 
-public typealias Include = Poly
+import Poly
+
+public typealias Include = JSONPoly
 
 public struct Includes<I: Include>: Codable, Equatable {
 	public static var none: Includes { return .init(values: []) }

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,12 +6,17 @@
 //
 
 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 rawValue: RawValue
 	
 	public let value: Transformer.To
 	
@@ -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 {
@@ -85,6 +113,31 @@ extension TransformedAttribute {
 	}
 }
 
+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 {

Sources/JSONAPI/Resource/Entity.swift

@@ -20,16 +20,24 @@ 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`
@@ -73,7 +81,7 @@ 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
@@ -128,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)))"
 	}
 }
 
@@ -433,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 }
@@ -463,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`.
@@ -505,6 +522,23 @@ public extension EntityProxy {
 	}
 }
 
+// MARK: Meta-Relationship Access
+public extension EntityProxy {
+	/// Access to an Id of a `ToOneRelationship`.
+	/// This allows you to write `entity ~> \.other` instead
+	/// of `entity.relationships.other.id`.
+	public static func ~><Identifier: IdType>(entity: Self, path: KeyPath<Description.Relationships, (Self) -> Identifier>) -> Identifier {
+		return entity.relationships[keyPath: path](entity)
+	}
+
+	/// Access to all Ids of a `ToManyRelationship`.
+	/// This allows you to write `entity ~> \.others` instead
+	/// of `entity.relationships.others.ids`.
+	public static func ~><Identifier: IdType>(entity: Self, path: KeyPath<Description.Relationships, (Self) -> [Identifier]>) -> [Identifier] {
+		return entity.relationships[keyPath: path](entity)
+	}
+}
+
 infix operator ~>
 
 // MARK: - Codable
@@ -521,7 +555,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)
@@ -550,8 +584,8 @@ 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

Sources/JSONAPI/Resource/Poly+PrimaryResource.swift

@@ -0,0 +1,57 @@
+//
+//  Poly+PrimaryResource.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 11/22/18.
+//
+
+import Poly
+
+/// Poly is a protocol to which types that
+/// are polymorphic belong to. Specifically,
+/// Poly1, Poly2, Poly3, etc. types conform
+/// to the Poly protocol. These types allow
+/// typesafe grouping of a number of
+/// disparate types under one roof for
+/// the purposes of JSON API compliant
+/// encoding or decoding.
+public typealias JSONPoly = Poly & PrimaryResource
+
+public typealias PolyWrapped = Codable & Equatable
+
+extension Poly0: PrimaryResource {
+	public init(from decoder: Decoder) throws {
+		throw JSONAPIEncodingError.illegalDecoding("Attempted to decode Poly0, which should represent a thing that is not expected to be found in a document.")
+	}
+
+	public func encode(to encoder: Encoder) throws {
+		throw JSONAPIEncodingError.illegalEncoding("Attempted to encode Poly0, which should represent a thing that is not expected to be found in a document.")
+	}
+}
+
+// MARK: - 1 type
+extension Poly1: PrimaryResource, MaybePrimaryResource where A: PolyWrapped {}
+
+// MARK: - 2 types
+extension Poly2: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped {}
+
+// MARK: - 3 types
+extension Poly3: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped, C: PolyWrapped {}
+
+// MARK: - 4 types
+extension Poly4: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped {}
+
+// MARK: - 5 types
+extension Poly5: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped {}
+
+// MARK: - 6 types
+extension Poly6: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped {}
+
+// MARK: - 7 types
+extension Poly7: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped, G: PolyWrapped {}
+
+// MARK: - 8 types
+extension Poly8: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped, G: PolyWrapped, H: PolyWrapped {}
+
+// MARK: - 9 types
+extension Poly9: PrimaryResource, MaybePrimaryResource where A: PolyWrapped, B: PolyWrapped, C: PolyWrapped, D: PolyWrapped, E: PolyWrapped, F: PolyWrapped, G: PolyWrapped, H: PolyWrapped, I: PolyWrapped {}