fixing up documentation and code samples

Author: mattpolzin

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

@@ -30,8 +30,8 @@ typealias UnidentifiedJSONEntity<Description: ResourceObjectDescription> = JSONA
 // Create relationship typealiases because we do not expect
 // JSON:API Relationships for this particular API to have
 // Metadata or Links associated with them.
-typealias ToOneRelationship<Entity: JSONAPIIdentifiable> = JSONAPI.ToOneRelationship<Entity, NoMetadata, NoLinks>
-typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoMetadata, NoLinks>
+typealias ToOneRelationship<Entity: JSONAPIIdentifiable> = JSONAPI.ToOneRelationship<Entity, NoIdMetadata, NoMetadata, NoLinks>
+typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoIdMetadata, NoMetadata, NoLinks>
 
 // Create a typealias for a Document because we do not expect
 // JSON:API Documents for this particular API to have Metadata, Links,

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

@@ -72,7 +72,7 @@ enum AuthorDescription: ResourceObjectDescription {
 	}
 
 	struct Relationships: JSONAPI.Relationships {
-		let articles: ToManyRelationship<Article, ToManyRelationshipMetadata, ToManyRelationshipLinks>
+		let articles: ToManyRelationship<Article, NoIdMetadata, ToManyRelationshipMetadata, ToManyRelationshipLinks>
 	}
 }
 
@@ -88,11 +88,11 @@ enum ArticleDescription: ResourceObjectDescription {
 
 	struct Relationships: JSONAPI.Relationships {
 		/// The primary attributed author of the article.
-		let primaryAuthor: ToOneRelationship<Author, NoMetadata, NoLinks>
+		let primaryAuthor: ToOneRelationship<Author, NoIdMetadata, 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>
+		let otherAuthors: ToManyRelationship<Author, NoIdMetadata, ToManyRelationshipMetadata, ToManyRelationshipLinks>
 	}
 }
 

JSONAPI.playground/Sources/Entities.swift

@@ -25,8 +25,8 @@ extension String: CreatableRawIdType {
 
 // MARK: - typealiases for convenience
 public typealias ExampleEntity<Description: ResourceObjectDescription> = ResourceObject<Description, NoMetadata, NoLinks, String>
-public typealias ToOne<E: JSONAPIIdentifiable> = ToOneRelationship<E, NoMetadata, NoLinks>
-public typealias ToMany<E: Relatable> = ToManyRelationship<E, NoMetadata, NoLinks>
+public typealias ToOne<E: JSONAPIIdentifiable> = ToOneRelationship<E, NoIdMetadata, NoMetadata, NoLinks>
+public typealias ToMany<E: Relatable> = ToManyRelationship<E, NoIdMetadata, NoMetadata, NoLinks>
 
 // MARK: - A few resource objects (entities)
 public enum PersonDescription: ResourceObjectDescription {

documentation/client-server-example.md

@@ -26,8 +26,8 @@ typealias UnidentifiedJSONEntity<Description: ResourceObjectDescription> = JSONA
 // Create relationship typealiases because we do not expect
 // JSON:API Relationships for this particular API to have
 // Metadata or Links associated with them.
-typealias ToOneRelationship<Entity: JSONAPIIdentifiable> = JSONAPI.ToOneRelationship<Entity, NoMetadata, NoLinks>
-typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoMetadata, NoLinks>
+typealias ToOneRelationship<Entity: JSONAPIIdentifiable> = JSONAPI.ToOneRelationship<Entity, NoIdMetadata, NoMetadata, NoLinks>
+typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoIdMetadata, NoMetadata, NoLinks>
 
 // Create a typealias for a Document because we do not expect
 // JSON:API Documents for this particular API to have Metadata, Links,
@@ -183,4 +183,4 @@ let response = try! docode(articleResponseData: responseData)
 print("-----")
 print(response.article)
 print(response.author)
-```
+```

documentation/project-status.md

@@ -22,6 +22,11 @@
 - [x] `links`
 - [x] `meta`
 
+##### Resource Identifier Object
+- [x] `id`
+- [x] `type`
+- [x] `meta`
+
 #### Links Object
 - [x] `href`
 - [x] `meta`
@@ -43,4 +48,4 @@ These ideas could be implemented in future versions.
 - [ ] (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`.
-- [ ] Error or warning if an included resource object is not related to a primary resource object or another included resource object (Turned off or at least not throwing by default).
+- [ ] Error or warning if an included resource object is not related to a primary resource object or another included resource object (Turned off or at least not throwing by default).

documentation/usage.md

@@ -57,7 +57,7 @@ enum PersonDescription: ResourceObjectDescription {
 	}
 
 	struct Relationships: JSONAPI.Relationships {
-		let friends: ToManyRelationship<Person>
+		let friends: ToManyRelationship<Person, NoIdMetadata, NoMetadata, NoLinks>
 	}
 }
 ```
@@ -153,9 +153,16 @@ In addition to identifying resource objects by ID and type, `Relationships` can
 
 The `MetaRelationship` is special in that it represents a Relationship Object with no `data` (it must contain at least one of `meta` or `links`). The other two relationship types are Relationship Objects with either singular resource linkages (`ToOneRelationship`) or arrays of resource linkages (`ToManyRelationship`).
 
-To describe a relationship that may be omitted (i.e. the key is not even present in the JSON object), you make the entire `MetaRelationship`, `ToOneRelationship` or `ToManyRelationship` optional. A `ToOneRelationship` can be marked as nullable (i.e. the value could be either `null` or a resource identifier) like this:
+To describe a relationship that may be omitted (i.e. the key is not even present in the JSON object), you make the entire `MetaRelationship`, `ToOneRelationship` or `ToManyRelationship` optional. 
 ```swift
-let nullableRelative: ToOneRelationship<Person?, NoMetadata, NoLinks>
+// note the question mark at the very end of the line.
+let optionalRelative: ToOneRelationship<Person, NoIdMetadata, NoMetadata, NoLinks>?
+```
+
+A `ToOneRelationship` can be marked as nullable (i.e. the value could be either `null` or a resource identifier) like this:
+```swift
+// note the question mark just after `Person`.
+let nullableRelative: ToOneRelationship<Person?, NoIdMetadata, NoMetadata, NoLinks>
 ```
 
 A `ToManyRelationship` can naturally represent the absence of related values with an empty array, so `ToManyRelationship` do not support nullability.