Merge pull request #17 from mattpolzin/swift-5

Default to Swift version 5.0 and Swift Tools version 5.0

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

@@ -1,5 +1,6 @@
 import Foundation
 import JSONAPI
+import Poly
 
 // MARK: - Preamble (setup)
 

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)
@@ -53,11 +49,15 @@ print("-----")
 
 // MARK: - Pass successfully parsed body to other parts of the code
 
+/*
+ ---- CRASHING IN XCODE 10.2 PLAYGROUND ----
+
 if case let .data(bodyData) = peopleResponse.body {
 	print("first person's name: \(bodyData.primary.values[0][\.fullName])")
 } else {
 	print("no body data")
 }
+ */
 
 // MARK: - Work in the abstract
 

JSONAPI.playground/Sources/Entities.swift

@@ -63,7 +63,7 @@ public enum PersonDescription: EntityDescription {
 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 {
+	init(id: Person.Id? = nil,name: [String], favoriteColor: String, friends: [Person], dogs: [Dog], home: House) throws {
 		self = Person(id: id ?? Person.Id(), attributes: .init(name: .init(value: name), favoriteColor: .init(value: favoriteColor)), relationships: .init(friends: .init(entities: friends), dogs: .init(entities: dogs), home: .init(entity: home)), meta: .none, links: .none)
 	}
 }
@@ -120,11 +120,11 @@ public enum AlternativeDogDescription: EntityDescription {
 public typealias AlternativeDog = ExampleEntity<AlternativeDogDescription>
 
 public extension Entity where Description == DogDescription, MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == String {
-	public init(name: String, owner: Person?) throws {
+	init(name: String, owner: Person?) throws {
 		self = Dog(attributes: .init(name: .init(value: name)), relationships: DogDescription.Relationships(owner: .init(entity: owner)), meta: .none, links: .none)
 	}
 
-	public init(name: String, owner: Person.Id) throws {
+	init(name: String, owner: Person.Id) throws {
 		self = Dog(attributes: .init(name: .init(value: name)), relationships: .init(owner: .init(id: owner)), meta: .none, links: .none)
 	}
 }
@@ -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/contents.xcplayground

@@ -1,7 +1,9 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<playground version='6.0' target-platform='macos' executeOnSourceChanges='false'>
+<playground version='6.0' target-platform='macos'>
     <pages>
         <page name='Test Library'/>
         <page name='Usage'/>
+        <page name='Full Client &amp; Server Example'/>
+        <page name='Full Document Verbose Generation'/>
     </pages>
 </playground>

JSONAPI.podspec

@@ -0,0 +1,141 @@
+#
+#  Be sure to run `pod spec lint JSONAPI.podspec' to ensure this is a
+#  valid spec and to remove all comments including this before submitting the spec.
+#
+#  To learn more about Podspec attributes see https://docs.cocoapods.org/specification.html
+#  To see working Podspecs in the CocoaPods repo see https://github.com/CocoaPods/Specs/
+#
+
+Pod::Spec.new do |spec|
+
+  # ―――  Spec Metadata  ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  These will help people to find your library, and whilst it
+  #  can feel like a chore to fill in it's definitely to your advantage. The
+  #  summary should be tweet-length, and the description more in depth.
+  #
+
+  spec.name         = "JSONAPI"
+  spec.version      = "0.20.0"
+  spec.summary      = "Swift Codable JSON API framework."
+
+  # This description is used to generate tags and improve search results.
+  #   * Think: What does it do? Why did you write it? What is the focus?
+  #   * Try to keep it short, snappy and to the point.
+  #   * Write the description between the DESC delimiters below.
+  #   * Finally, don't worry about the indent, CocoaPods strips it!
+  spec.description  = <<-DESC
+  A Swift package for encoding to- and decoding from JSON API compliant requests and responses.
+
+See the JSON API Spec here: https://jsonapi.org/format/
+                   DESC
+
+  spec.homepage     = "https://github.com/mattpolzin/JSONAPI"
+  # spec.screenshots  = "www.example.com/screenshots_1.gif", "www.example.com/screenshots_2.gif"
+
+
+  # ―――  Spec License  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Licensing your code is important. See https://choosealicense.com for more info.
+  #  CocoaPods will detect a license file if there is a named LICENSE*
+  #  Popular ones are 'MIT', 'BSD' and 'Apache License, Version 2.0'.
+  #
+
+  # spec.license      = "MIT"
+  spec.license      = { :type => "MIT", :file => "LICENSE.txt" }
+
+
+  # ――― Author Metadata  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Specify the authors of the library, with email addresses. Email addresses
+  #  of the authors are extracted from the SCM log. E.g. $ git log. CocoaPods also
+  #  accepts just a name if you'd rather not provide an email address.
+  #
+  #  Specify a social_media_url where others can refer to, for example a twitter
+  #  profile URL.
+  #
+
+  spec.author             = { "Mathew Polzin" => "matt.polzin@gmail.com" }
+  # Or just: spec.author    = "Mathew Polzin"
+  # spec.authors            = { "Mathew Polzin" => "matt.polzin@gmail.com" }
+  # spec.social_media_url   = "https://twitter.com/Mathew Polzin"
+
+  # ――― Platform Specifics ――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  If this Pod runs only on iOS or OS X, then specify the platform and
+  #  the deployment target. You can optionally include the target after the platform.
+  #
+
+  # spec.platform     = :ios
+  # spec.platform     = :ios, "5.0"
+
+  #  When using multiple platforms
+  spec.ios.deployment_target = "8.0"
+  spec.osx.deployment_target = "10.9"
+  # spec.watchos.deployment_target = "2.0"
+  # spec.tvos.deployment_target = "9.0"
+
+
+  # ――― Source Location ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Specify the location from where the source should be retrieved.
+  #  Supports git, hg, bzr, svn and HTTP.
+  #
+
+  spec.source       = { :git => "https://github.com/mattpolzin/JSONAPI.git", :tag => "#{spec.version}" }
+
+
+  # ――― Source Code ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  CocoaPods is smart about how it includes source code. For source files
+  #  giving a folder will include any swift, h, m, mm, c & cpp files.
+  #  For header files it will include any header in the folder.
+  #  Not including the public_header_files will make all headers public.
+  #
+
+  spec.source_files  = "Sources", "Sources/**/*.{swift}"
+  # spec.exclude_files = "Classes/Exclude"
+
+  # spec.public_header_files = "Classes/**/*.h"
+
+
+  # ――― Resources ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  A list of resources included with the Pod. These are copied into the
+  #  target bundle with a build phase script. Anything else will be cleaned.
+  #  You can preserve files from being cleaned, please don't preserve
+  #  non-essential files like tests, examples and documentation.
+  #
+
+  # spec.resource  = "icon.png"
+  # spec.resources = "Resources/*.png"
+
+  # spec.preserve_paths = "FilesToSave", "MoreFilesToSave"
+
+
+  # ――― Project Linking ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Link your library with frameworks, or libraries. Libraries do not include
+  #  the lib prefix of their name.
+  #
+
+  spec.framework  = "Poly"
+  # spec.frameworks = "SomeFramework", "AnotherFramework"
+
+  # spec.library   = "iconv"
+  # spec.libraries = "iconv", "xml2"
+
+
+  # ――― Project Settings ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  If your library depends on compiler flags you can set them in the xcconfig hash
+  #  where they will only apply to your library. If you depend on other Podspecs
+  #  you can include multiple dependencies to ensure it works.
+
+  spec.swift_version = "5.0"
+  # spec.requires_arc = true
+
+  # spec.xcconfig = { "HEADER_SEARCH_PATHS" => "$(SDKROOT)/usr/include/libxml2" }
+  spec.dependency "Poly", "~> 2.0"
+
+end

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,15 @@
 {
   "object": {
     "pins": [
-
+      {
+        "package": "Poly",
+        "repositoryURL": "https://github.com/mattpolzin/Poly.git",
+        "state": {
+          "branch": null,
+          "revision": "d24d4c1214dd05f89eb1182a46592856dd0a0645",
+          "version": "2.0.0"
+        }
+      }
     ]
   },
   "version": 1

Package.swift

@@ -1,30 +1,38 @@
-// swift-tools-version:4.2
+// swift-tools-version:5.0
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import PackageDescription
 
 let package = Package(
     name: "JSONAPI",
+    platforms: [
+      .macOS(.v10_10),
+      .iOS(.v10)
+    ],
     products: [
         .library(
             name: "JSONAPI",
             targets: ["JSONAPI"]),
 		.library(
-			name: "JSONAPITestLib",
-			targets: ["JSONAPITestLib"])
+			name: "JSONAPITesting",
+			targets: ["JSONAPITesting"])
     ],
     dependencies: [
+		.package(url: "https://github.com/mattpolzin/Poly.git", from: "2.0.0"),
     ],
     targets: [
         .target(
             name: "JSONAPI",
-            dependencies: []),
+            dependencies: ["Poly"]),
 		.target(
-			name: "JSONAPITestLib",
+			name: "JSONAPITesting",
 			dependencies: ["JSONAPI"]),
         .testTarget(
             name: "JSONAPITests",
-            dependencies: ["JSONAPITestLib"])
+            dependencies: ["JSONAPI", "JSONAPITesting"]),
+        .testTarget(
+            name: "JSONAPITestingTests",
+            dependencies: ["JSONAPI", "JSONAPITesting"])
     ],
-  	swiftLanguageVersions: [.v4_2]
+  	swiftLanguageVersions: [.v5]
 )

README.md

@@ -8,59 +8,63 @@ See the JSON API Spec here: https://jsonapi.org/format/
 :warning: Although I find the type-safety of this framework appealing, the Swift compiler currently has enough trouble with it that it can become difficult to reason about errors produced by small typos. Similarly, auto-complete fails to provide reasonable suggestions much of the time. If you get the code right, everything compiles, otherwise it can suck to figure out what is wrong. This is mostly a concern when creating entities in-code (servers and test suites must do this). Writing a client that uses this framework to ingest JSON API Compliant API responses is much less painful. :warning:
 
 ## Table of Contents
-<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
+<!-- TOC depthFrom:1 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)
-	- [Meta-Relationships](#meta-relationships)
-- [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)
+- [JSONAPI](#jsonapi)
+	- [Table of Contents](#table-of-contents)
+	- [Primary Goals](#primary-goals)
+		- [Caveat](#caveat)
+	- [Dev Environment](#dev-environment)
+		- [Prerequisites](#prerequisites)
+		- [CocoaPods](#cocoapods)
+		- [Xcode project](#xcode-project)
+		- [Running the Playground](#running-the-playground)
+	- [Project Status](#project-status)
+		- [JSON:API](#jsonapi)
+			- [Document](#document)
+			- [Resource Object](#resource-object)
+			- [Relationship Object](#relationship-object)
+			- [Links Object](#links-object)
+		- [Misc](#misc)
+		- [Testing](#testing)
+			- [Entity Validator](#entity-validator)
+		- [Potential Improvements](#potential-improvements)
+	- [Usage](#usage)
+		- [`JSONAPI.EntityDescription`](#jsonapientitydescription)
+		- [`JSONAPI.Entity`](#jsonapientity)
+			- [`Meta`](#meta)
+			- [`Links`](#links)
+			- [`MaybeRawId`](#mayberawid)
+				- [`RawIdType`](#rawidtype)
+			- [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)
+		- [Meta-Relationships](#meta-relationships)
+	- [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)
+- [JSONAPI+Testing](#jsonapitesting)
+- [JSONAPI+Arbitrary](#jsonapiarbitrary)
+- [JSONAPI+OpenAPI](#jsonapiopenapi)
 
 <!-- /TOC -->
 
@@ -79,7 +83,15 @@ If you find something wrong with this library and it isn't already mentioned und
 
 ## Dev Environment
 ### Prerequisites
-1. Swift 4.2+ and Swift Package Manager
+1. Swift 4.2+
+2. Swift Package Manager *OR* Cocoapods
+
+### CocoaPods
+To use this framework in your project via Cocoapods instead of Swift Package Manager, add the following dependencies to your Podfile.
+```
+	pod 'Poly', :git => 'https://github.com/mattpolzin/Poly.git'
+	pod 'JSONAPI', :git => 'https://github.com/mattpolzin/JSONAPI.git'
+```
 
 ### Xcode project
 To create an Xcode project for JSONAPI, run
@@ -92,31 +104,79 @@ Note that Playground support for importing non-system Frameworks is still a bit
 
 ## Project Status
 
-### Encoding/Decoding
+### JSON:API
 #### Document
-- [x] `data`
-- [x] `included`
-- [x] `errors`
-- [x] `meta`
-- [x] `jsonapi`
-- [x] `links`
+- `data`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [x] OpenAPI
+- `included`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [x] OpenAPI
+- `errors`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [ ] OpenAPI
+- `meta`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [ ] OpenAPI
+- `jsonapi` (i.e. API Information)
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [ ] OpenAPI
+- `links`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [ ] OpenAPI
 
 #### Resource Object
-- [x] `id`
-- [x] `type`
-- [x] `attributes`
-- [x] `relationships`
-- [x] `links`
-- [x] `meta`
+- `id`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [x] OpenAPI
+- `type`
+	- [x] Encoding/Decoding
+	- [x] OpenAPI
+- `attributes`
+	- [x] Encoding/Decoding
+	- [x] OpenAPI
+- `relationships`
+	- [x] Encoding/Decoding
+	- [x] OpenAPI
+- `links`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [ ] OpenAPI
+- `meta`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [ ] OpenAPI
 
 #### Relationship Object
-- [x] `data`
-- [x] `links`
-- [x] `meta`
+- `data`
+	- [x] Encoding/Decoding
+	- [x] Arbitrary
+	- [x] OpenAPI
+- `links`
+	- [x] Encoding/Decoding
+	- [ ] Arbitrary
+	- [ ] OpenAPI
+- `meta`
+	- [x] Encoding/Decoding
+	- [ ] Arbitrary
+	- [ ] OpenAPI
 
 #### Links Object
-- [x] `href`
-- [x] `meta`
+- `href`
+	- [x] Encoding/Decoding
+	- [ ] Arbitrary
+	- [ ] OpenAPI
+- `meta`
+	- [x] Encoding/Decoding
+	- [ ] Arbitrary
+	- [ ] OpenAPI
 
 ### Misc
 - [x] Support transforms on `Attributes` values (e.g. to support different representations of `Date`)
@@ -124,7 +184,7 @@ Note that Playground support for importing non-system Frameworks is still a bit
 - [ ] 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
+### Testing
 #### Entity Validator
 - [x] Disallow optional array in `Attribute` (should be empty array, not `null`).
 - [x] Only allow `TransformedAttribute` and its derivatives as stored properties within `Attributes` struct. Computed properties can still be any type because they do not get encoded or decoded.
@@ -207,23 +267,23 @@ An `Entity` needs to be specialized on four generic types. The first is the `Ent
 
 #### `Meta`
 
-The second generic specialization on `Entity` is `Meta`. This is described in its own section [below](#jsonapimeta). All `Meta` at any level of a JSON API Document follow the same rules.
+The second generic specialization on `Entity` is `Meta`. This is described in its own section [below](#jsonapimeta). All `Meta` at any level of a JSON API Document follow the same rules. You can use `NoMetadata` if you do not need to package any metadata with the `Entity`.
 
 #### `Links`
 
-The third generic specialization on `Entity` is `Links`. This is described in its own section [below](#jsonnapilinks). All `Links` at any level of a JSON API Document follow the same rules, although the **SPEC** makes different suggestions as to what types of links might live on which parts of the Document.
-
-#### `IdType`
-
- The second is the raw type of `Id` to use for the `Entity`. The actual `Id` of the `Entity` will not be a `RawIdType`, though. The `Id` will package a value of `RawIdType` with a specialized reference back to the `Entity` type it identifies. This just looks like `Id<RawIdType, Entity<EntityDescription, RawIdType>>`.
-
-Having the `Entity` type associated with the `Id` makes it easy to store all of your entities in a hash broken out by `Entity` type; You can pass `Ids` around and always know where to look for the `Entity` to which the `Id` refers.
-
-A `RawIdType` is the underlying type that uniquely identifies an `Entity`. This is often a `String` or a `UUID`.
+The third generic specialization on `Entity` is `Links`. This is described in its own section [below](#jsonnapilinks). All `Links` at any level of a JSON API Document follow the same rules, although the **SPEC** makes different suggestions as to what types of links might live on which parts of the Document. You can use `NoLinks` if you do not need to package any links with the `Entity`.
 
 #### `MaybeRawId`
 
-`MaybeRawId` is either a `RawIdType` that can be used to uniquely identify `Entities` or it is `Unidentified` which is used to indicate an `Entity` does not have an `Id` (which is useful when a client is requesting that the server create an `Entity` and assign it a new `Id`).
+The last generic specialization on `Entity` is `MaybeRawId`. This is either a `RawIdType` that can be used to uniquely identify `Entities` or it is `Unidentified` which is used to indicate an `Entity` does not have an `Id` (which is useful when a client is requesting that the server create an `Entity` and assign it a new `Id`).
+
+##### `RawIdType`
+
+The raw type of `Id` to use for the `Entity`. The actual `Id` of the `Entity` will not be a `RawIdType`, though. The `Id` will package a value of `RawIdType` with a specialized reference back to the `Entity` type it identifies. This just looks like `Id<RawIdType, Entity<EntityDescription, Meta, Links, RawIdType>>`.
+
+Having the `Entity` type associated with the `Id` makes it easy to store all of your entities in a hash broken out by `Entity` type; You can pass `Ids` around and always know where to look for the `Entity` to which the `Id` refers. This encapsulation provides some type safety because the Ids of two `Entities` with the "raw ID" of `"1"` but different types will not compare as equal.
+
+A `RawIdType` is the underlying type that uniquely identifies an `Entity`. This is often a `String` or a `UUID`.
 
 #### Convenient `typealiases`
 
@@ -781,5 +841,11 @@ 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.
+# JSONAPI+Testing
+The `JSONAPI` framework is packaged with a test library to help you test your `JSONAPI` integration. The test library is called `JSONAPITesting`. 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 `JSONAPITesting` in action in the Playground included with the `JSONAPI` repository.
+
+# JSONAPI+Arbitrary
+This library has moved into its own Package. See https://github.com/mattpolzin/JSONAPI-Arbitrary
+
+# JSONAPI+OpenAPI
+This library has moved into its own Package. See https://github.com/mattpolzin/JSONAPI-OpenAPI

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

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

@@ -15,7 +15,7 @@ public extension TransformedAttribute {
 	/// Generally, this is the most useful operation. The transformer gives you
 	/// control over the decoding of the Attribute, but once the Attribute exists,
 	/// mapping on it is most useful for creating computed Attribute properties.
-	public func map<T: Codable>(_ transform: (Transformer.To) throws -> T) rethrows -> Attribute<T> {
+	func map<T: Codable>(_ transform: (Transformer.To) throws -> T) rethrows -> Attribute<T> {
 		return Attribute<T>(value: try transform(value))
 	}
 }
@@ -30,7 +30,7 @@ public extension 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> {
+	func map<T: Codable>(_ transform: (ValueType) throws -> T) rethrows -> Attribute<T> {
 		return Attribute<T>(value: try transform(value))
 	}
 }

Sources/JSONAPI/Resource/Attribute.swift

@@ -16,7 +16,7 @@ public protocol AttributeType: Codable {
 
 /// 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
 	

Sources/JSONAPI/Resource/Entity.swift

@@ -397,20 +397,20 @@ public extension Entity where EntityRawIdType: JSONAPI.RawIdType {
 	/// An Entity.Pointer is a `ToOneRelationship` with no metadata or links.
 	/// This is just a convenient way to reference an Entity so that
 	/// other Entities' Relationships can be built up from it.
-	public typealias Pointer = ToOneRelationship<Entity, NoMetadata, NoLinks>
+	typealias Pointer = ToOneRelationship<Entity, NoMetadata, NoLinks>
 
 	/// Entity.Pointers is a `ToManyRelationship` with no metadata or links.
 	/// This is just a convenient way to reference a bunch of Entities so
 	/// that other Entities' Relationships can be built up from them.
-	public typealias Pointers = ToManyRelationship<Entity, NoMetadata, NoLinks>
+	typealias Pointers = ToManyRelationship<Entity, NoMetadata, NoLinks>
 
 	/// Get a pointer to this entity that can be used as a
 	/// relationship to another entity.
-	public var pointer: Pointer {
+	var pointer: Pointer {
 		return Pointer(entity: self)
 	}
 
-	public func pointer<MType: JSONAPI.Meta, LType: JSONAPI.Links>(withMeta meta: MType, links: LType) -> ToOneRelationship<Entity, MType, LType> {
+	func pointer<MType: JSONAPI.Meta, LType: JSONAPI.Links>(withMeta meta: MType, links: LType) -> ToOneRelationship<Entity, MType, LType> {
 		return ToOneRelationship(entity: self, meta: meta, links: links)
 	}
 }
@@ -419,19 +419,19 @@ public extension Entity where EntityRawIdType: JSONAPI.RawIdType {
 public extension Entity where EntityRawIdType == Unidentified {
 	/// Create a new Entity from this one with a newly created
 	/// unique Id of the given type.
-	public func identified<RawIdType: CreatableRawIdType>(byType: RawIdType.Type) -> Entity<Description, MetaType, LinksType, RawIdType> {
+	func identified<RawIdType: CreatableRawIdType>(byType: RawIdType.Type) -> Entity<Description, MetaType, LinksType, RawIdType> {
 		return .init(attributes: attributes, relationships: relationships, meta: meta, links: links)
 	}
 
 	/// Create a new Entity from this one with the given Id.
-	public func identified<RawIdType: JSONAPI.RawIdType>(by id: RawIdType) -> Entity<Description, MetaType, LinksType, RawIdType> {
+	func identified<RawIdType: JSONAPI.RawIdType>(by id: RawIdType) -> Entity<Description, MetaType, LinksType, RawIdType> {
 		return .init(id: Entity<Description, MetaType, LinksType, RawIdType>.Identifier(rawValue: id), attributes: attributes, relationships: relationships, meta: meta, links: links)
 	}
 }
 
 public extension Entity where EntityRawIdType: CreatableRawIdType {
 	/// Create a copy of this Entity with a new unique Id.
-	public func withNewIdentifier() -> Entity {
+	func withNewIdentifier() -> Entity {
 		return Entity(attributes: attributes, relationships: relationships, meta: meta, links: links)
 	}
 }
@@ -485,14 +485,14 @@ public extension EntityProxy {
 	/// Access to an Id of a `ToOneRelationship`.
 	/// This allows you to write `entity ~> \.other` instead
 	/// of `entity.relationships.other.id`.
-	public static func ~><OtherEntity: Identifiable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>>) -> OtherEntity.Identifier {
+	static func ~><OtherEntity: Identifiable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>>) -> OtherEntity.Identifier {
 		return entity.relationships[keyPath: path].id
 	}
 
 	/// Access to an Id of an optional `ToOneRelationship`.
 	/// This allows you to write `entity ~> \.other` instead
 	/// of `entity.relationships.other?.id`.
-	public static func ~><OtherEntity: OptionalRelatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>?>) -> OtherEntity.Identifier {
+	static func ~><OtherEntity: OptionalRelatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>?>) -> OtherEntity.Identifier {
 		// Implementation Note: This signature applies to `ToOneRelationship<E?, _, _>?`
 		// whereas the one below applies to `ToOneRelationship<E, _, _>?`
 		return entity.relationships[keyPath: path]?.id
@@ -501,7 +501,7 @@ public extension EntityProxy {
 	/// Access to an Id of an optional `ToOneRelationship`.
 	/// This allows you to write `entity ~> \.other` instead
 	/// of `entity.relationships.other?.id`.
-	public static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>?>) -> OtherEntity.Identifier? {
+	static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity, MType, LType>?>) -> OtherEntity.Identifier? {
 		// Implementation Note: This signature applies to `ToOneRelationship<E, _, _>?`
 		// whereas the one above applies to `ToOneRelationship<E?, _, _>?`
 		return entity.relationships[keyPath: path]?.id
@@ -510,14 +510,14 @@ public extension EntityProxy {
 	/// Access to all Ids of a `ToManyRelationship`.
 	/// This allows you to write `entity ~> \.others` instead
 	/// of `entity.relationships.others.ids`.
-	public static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity, MType, LType>>) -> [OtherEntity.Identifier] {
+	static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity, MType, LType>>) -> [OtherEntity.Identifier] {
 		return entity.relationships[keyPath: path].ids
 	}
 
 	/// Access to all Ids of an optional `ToManyRelationship`.
 	/// This allows you to write `entity ~> \.others` instead
 	/// of `entity.relationships.others?.ids`.
-	public static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity, MType, LType>?>) -> [OtherEntity.Identifier]? {
+	static func ~><OtherEntity: Relatable, MType: JSONAPI.Meta, LType: JSONAPI.Links>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity, MType, LType>?>) -> [OtherEntity.Identifier]? {
 		return entity.relationships[keyPath: path]?.ids
 	}
 }
@@ -527,14 +527,14 @@ 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 {
+	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] {
+	static func ~><Identifier: IdType>(entity: Self, path: KeyPath<Description.Relationships, (Self) -> [Identifier]>) -> [Identifier] {
 		return entity.relationships[keyPath: path](entity)
 	}
 }
@@ -552,7 +552,7 @@ private enum ResourceObjectCodingKeys: String, CodingKey {
 }
 
 public extension Entity {
-	public func encode(to encoder: Encoder) throws {
+	func encode(to encoder: Encoder) throws {
 		var container = encoder.container(keyedBy: ResourceObjectCodingKeys.self)
 		
 		try container.encode(Entity.jsonType, forKey: .type)
@@ -578,7 +578,7 @@ public extension Entity {
 		}
 	}
 
-	public init(from decoder: Decoder) throws {
+	init(from decoder: Decoder) throws {
 		
 		let container = try decoder.container(keyedBy: ResourceObjectCodingKeys.self)
 		

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 {}

Sources/JSONAPI/Result.swift

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

Sources/JSONAPITesting/EntityCheck.swift

@@ -1,6 +1,6 @@
 //
 //  EntityCheck.swift
-//  JSONAPITestLib
+//  JSONAPITesting
 //
 //  Created by Mathew Polzin on 11/27/18.
 //
@@ -55,7 +55,7 @@ extension TransformedAttribute: _AttributeType {}
 extension Attribute: _AttributeType {}
 
 public extension Entity {
-	public static func check(_ entity: Entity) throws {
+	static func check(_ entity: Entity) throws {
 		var problems = [EntityCheckError]()
 
 		let attributesMirror = Mirror(reflecting: entity.attributes)