Nullable Relationship ReadME

.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# Each line is a file pattern followed by one or more owners.
+# More on CODEOWNERS files: https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners
+
+# Default owners
+* @hashicorp/team-ip-compliance
+* @hashicorp/tf-core-cloud
+
+# Add override rules below. Each line is a file/folder pattern followed by one or more owners.
+# Being an owner means those groups or individuals will be added as reviewers to PRs affecting
+# those areas of the code.
+# Examples:
+# /docs/  @docs-team
+# *.js    @js-team
+# *.go    @go-team

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  unit-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go: [ '1.21', '1.20', '1.19', '1.18']
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+        with:
+          go-version: ${{ matrix.go }}
+
+      - name: test
+        run: go test -race . -v

README.md

@@ -1,19 +1,19 @@
 # jsonapi
 
-[![Build Status](https://travis-ci.org/google/jsonapi.svg?branch=master)](https://travis-ci.org/google/jsonapi)
-[![Go Report Card](https://goreportcard.com/badge/github.com/google/jsonapi)](https://goreportcard.com/report/github.com/google/jsonapi)
-[![GoDoc](https://godoc.org/github.com/google/jsonapi?status.svg)](http://godoc.org/github.com/google/jsonapi)
-[![No Maintenance Intended](http://unmaintained.tech/badge.svg)](http://unmaintained.tech/)
+[![Build Status](https://github.com/hashicorp/jsonapi/actions/workflows/ci.yml/badge.svg?main)](https://github.com/hashicorp/jsonapi/actions/workflows/ci.yml?query=branch%3Amain)
+[![Go Report Card](https://goreportcard.com/badge/github.com/hashicorp/jsonapi)](https://goreportcard.com/report/github.com/hashicorp/jsonapi)
+[![GoDoc](https://godoc.org/github.com/hashicorp/jsonapi?status.svg)](http://godoc.org/github.com/hashicorp/jsonapi)
 
 A serializer/deserializer for JSON payloads that comply to the
-[JSON API - jsonapi.org](http://jsonapi.org) spec in go.
-
+[JSON API - jsonapi.org](http://jsonapi.org) v1.1 spec in go.
 
+This package was forked from [google/jsonapi](https://github.com/google/jsonapi) and
+adds several enhancements such as [links](#links) and [polymorphic relationships](#polyrelation).
 
 ## Installation
 
 ```
-go get -u github.com/google/jsonapi
+go get -u github.com/hashicorp/jsonapi
 ```
 
 Or, see [Alternative Installation](#alternative-installation).
@@ -77,7 +77,7 @@ all of your data easily.
 
 ## Example App
 
-[examples/app.go](https://github.com/google/jsonapi/blob/master/examples/app.go)
+[examples/app.go](https://github.com/hashicorp/jsonapi/blob/main/examples/app.go)
 
 This program demonstrates the implementation of a create, a show,
 and a list [http.Handler](http://golang.org/pkg/net/http#Handler).  It
@@ -91,9 +91,9 @@ To run,
 * Make sure you have [Go installed](https://golang.org/doc/install)
 * Create the following directories or similar: `~/go`
 * Set `GOPATH` to `PWD` in your shell session, `export GOPATH=$PWD`
-* `go get github.com/google/jsonapi`.  (Append `-u` after `get` if you
+* `go get github.com/hashicorp/jsonapi`.  (Append `-u` after `get` if you
   are updating.)
-* `cd $GOPATH/src/github.com/google/jsonapi/examples`
+* `cd $GOPATH/src/github.com/hashicorp/jsonapi/examples`
 * `go build && ./examples`
 
 ## `jsonapi` Tag Reference
@@ -179,6 +179,69 @@ used as the key in the `relationships` hash for the record. The optional
 third argument is `omitempty` - if present will prevent non existent to-one and
 to-many from being serialized.
 
+
+#### `polyrelation`
+
+```
+`jsonapi:"polyrelation,<key name in relationships hash>,<optional: omitempty>"`
+```
+
+Polymorphic relations can be represented exactly as relations, except that
+an intermediate type is needed within your model struct that provides a choice
+for the actual value to be populated within.
+
+Example:
+
+```go
+type Video struct {
+	ID          int    `jsonapi:"primary,videos"`
+	SourceURL   string `jsonapi:"attr,source-url"`
+	CaptionsURL string `jsonapi:"attr,captions-url"`
+}
+
+type Image struct {
+	ID        int    `jsonapi:"primary,images"`
+	SourceURL string `jsonapi:"attr,src"`
+	AltText   string `jsonapi:"attr,alt"`
+}
+
+type OneOfMedia struct {
+	Video *Video
+	Image *Image
+}
+
+type Post struct {
+	ID      int           `jsonapi:"primary,posts"`
+	Title   string        `jsonapi:"attr,title"`
+	Body    string        `jsonapi:"attr,body"`
+	Gallery []*OneOfMedia `jsonapi:"polyrelation,gallery"`
+	Hero    *OneOfMedia   `jsonapi:"polyrelation,hero"`
+}
+```
+
+During decoding, the `polyrelation` annotation instructs jsonapi to assign each relationship
+to either `Video` or `Image` within the value of the associated field, provided that the
+payload contains either a "videos" or "images" type. This field value must be
+a pointer to a special choice type struct (also known as a tagged union, or sum type) containing
+other pointer fields to jsonapi models. The actual field assignment depends on that type having
+a jsonapi "primary" annotation with a type matching the relationship type found in the response.
+All other fields will be remain empty. If no matching types are represented by the choice type,
+all fields will be empty.
+
+During encoding, the very first non-nil field will be used to populate the payload. Others
+will be ignored. Therefore, it's critical to set the value of only one field within the choice
+struct. When accepting input values on this type of choice type, it would a good idea to enforce
+and check that the value is set on only one field.
+
+#### `links`
+```
+`jsonapi:"links,omitempty"`
+```
+
+A field annotated with `links` will have the links members of the request unmarshaled to it. Note
+that this field should _always_ be annotated with `omitempty`, as marshaling of links members is
+instead handled by the `Linkable` interface (see `Links` below).
+
 ## Methods Reference
 
 **All `Marshal` and `Unmarshal` methods expect pointers to struct
@@ -190,7 +253,7 @@ about the rest?
 ### Create Record Example
 
 You can Unmarshal a JSON API payload using
-[jsonapi.UnmarshalPayload](http://godoc.org/github.com/google/jsonapi#UnmarshalPayload).
+[jsonapi.UnmarshalPayload](http://godoc.org/github.com/hashicorp/jsonapi#UnmarshalPayload).
 It reads from an [io.Reader](https://golang.org/pkg/io/#Reader)
 containing a JSON API payload for one record (but can have related
 records).  Then, it materializes a struct that you created and passed in
@@ -199,7 +262,7 @@ the top level, in request payloads at the moment. Bulk creates and
 updates are not supported yet.
 
 After saving your record, you can use,
-[MarshalOnePayload](http://godoc.org/github.com/google/jsonapi#MarshalOnePayload),
+[MarshalOnePayload](http://godoc.org/github.com/hashicorp/jsonapi#MarshalOnePayload),
 to write the JSON API response to an
 [io.Writer](https://golang.org/pkg/io/#Writer).
 
@@ -209,15 +272,15 @@ to write the JSON API response to an
 UnmarshalPayload(in io.Reader, model interface{})
 ```
 
-Visit [godoc](http://godoc.org/github.com/google/jsonapi#UnmarshalPayload)
+Visit [godoc](http://godoc.org/github.com/hashicorp/jsonapi#UnmarshalPayload)
 
 #### `MarshalPayload`
 
 ```go
 MarshalPayload(w io.Writer, models interface{}) error
 ```
 
-Visit [godoc](http://godoc.org/github.com/google/jsonapi#MarshalPayload)
+Visit [godoc](http://godoc.org/github.com/hashicorp/jsonapi#MarshalPayload)
 
 Writes a JSON API response, with related records sideloaded, into an
 `included` array.  This method encodes a response for either a single record or
@@ -253,7 +316,7 @@ func CreateBlog(w http.ResponseWriter, r *http.Request) {
 UnmarshalManyPayload(in io.Reader, t reflect.Type) ([]interface{}, error)
 ```
 
-Visit [godoc](http://godoc.org/github.com/google/jsonapi#UnmarshalManyPayload)
+Visit [godoc](http://godoc.org/github.com/hashicorp/jsonapi#UnmarshalManyPayload)
 
 Takes an `io.Reader` and a `reflect.Type` representing the uniform type
 contained within the `"data"` JSON API member.
@@ -346,6 +409,128 @@ func (post Post) JSONAPIRelationshipMeta(relation string) *Meta {
 }
 ```
 
+### Nullable attributes
+
+Certain APIs may interpret the meaning of `null` attribute values as significantly
+different from unspecified values (those that do not show up in the request).
+The default use of the `omitempty` struct tag does not allow for sending
+significant `null`s.
+
+A type is provided for this purpose if needed: `NullableAttr[T]`. This type
+provides an API for sending and receiving significant `null` values for
+attribute values of any type.
+
+In the example below, a payload is presented for a fictitious API that makes use
+of significant `null` values. Once enabled, the `UnsettableTime` setting can
+only be disabled by updating it to a `null` value. 
+
+The payload struct below makes use of a `NullableAttr` with an inner `time.Time`
+to allow this behavior:
+
+```go
+type Settings struct {
+	ID             int                              `jsonapi:"primary,videos"`
+	UnsettableTime jsonapi.NullableAttr[time.Time]  `jsonapi:"attr,unsettable_time,rfc3339,omitempty"`
+}
+```
+
+To enable the setting as described above, an non-null `time.Time` value is
+sent to the API.  This is done by using the exported
+`NewNullableAttrWithValue[T]()` method:
+
+```go
+s := Settings{
+    ID: 1,
+    UnsettableTime: jsonapi.NewNullableAttrWithValue[time.Time](time.Now()),
+}
+```
+
+To disable the setting, a `null` value needs to be sent to the API. This is done
+by using the exported `NewNullNullableAttr[T]()` method:
+
+```go
+s := Settings{
+    ID: 1,
+    UnsettableTime: jsonapi.NewNullNullableAttr[time.Time](),
+}
+```
+
+Once a payload has been marshaled, the attribute value is flattened to a
+primitive value:
+```
+    "unsettable_time": "2021-01-01T02:07:14Z",
+```
+
+Significant nulls are also included and flattened, even when specifying `omitempty`:
+```
+    "unsettable_time": null,
+```
+
+Once a payload is unmarshaled, the target attribute field is hydrated with
+the value in the payload and can be retrieved with the `Get()` method:
+```go
+t, err := s.UnsettableTime.Get()
+```
+
+All other struct tags used in the attribute definition will be honored when
+marshaling and unmarshaling non-null values for the inner type.
+
+### Nullable Relationship
+
+The `NullableRelationship` type is a generic type used to handle relationships in JSON API payloads that is not set, set to null or set to a valid relationship in the request. This type provides an API for sending and receiving significant `null` values for relationship values of any type.
+
+In the example below, a payload is presented for a fictitious API that makes use of significant `null` values. Once enabled, the `NullableComment` relationship can only be disabled by updating it to a `null` value.
+
+The payload struct below makes use of a `NullableRelationship` with an inner `*Comment` to allow this behavior:
+
+```go
+type WithNullableAttrs struct {
+    RFC3339Time     jsonapi.NullableAttr[time.Time]        `jsonapi:"attr,rfc3339_time,rfc3339,omitempty"`
+    ISO8601Time     jsonapi.NullableAttr[time.Time]        `jsonapi:"attr,iso8601_time,iso8601,omitempty"`
+    Bool            jsonapi.NullableAttr[bool]             `jsonapi:"attr,bool,omitempty"`
+    NullableComment jsonapi.NullableRelationship[*Comment] `jsonapi:"relation,nullable_comment,omitempty"`
+}
+```
+
+To enable the relationship as described above, a non-null `*Comment` value is sent to the API. This is done by using the exported `NewNullableRelationshipWithValue[T]()` method:
+
+```go
+comment := &Comment{
+    ID:   5,
+    Body: "Hello World",
+}
+
+s := WithNullableAttrs{
+    NullableComment: jsonapi.NewNullableRelationshipWithValue[*Comment](comment),
+}
+```
+
+To disable the relationship, a `null` value needs to be sent to the API. This is done by using the exported `NewNullNullableRelationship[T]()` method:
+
+```go
+s := WithNullableAttrs{
+    NullableComment: jsonapi.NewNullNullableRelationship[*Comment](),
+}
+```
+
+Once a payload has been marshaled, the relationship value is flattened to a reference value:
+
+```json
+"nullable_comment": {"data": {"type": "comments", "id": "5"}}
+```
+
+Significant nulls are also included and flattened, even when specifying `omitempty`:
+
+```json
+"nullable_comment": {"data": null}
+```
+
+Once a payload is unmarshaled, the target relationship field is hydrated with the value in the payload and can be retrieved with the `Get()` method:
+
+```go
+nullableComment, err := s.NullableComment.Get()
+```
+
 ### Custom types
 
 Custom types are supported for primitive types, only, as attributes.  Examples,
@@ -419,7 +604,7 @@ if err := validate(&myStructToValidate); err != nil {
 MarshalOnePayloadEmbedded(w io.Writer, model interface{}) error
 ```
 
-Visit [godoc](http://godoc.org/github.com/google/jsonapi#MarshalOnePayloadEmbedded)
+Visit [godoc](http://godoc.org/github.com/hashicorp/jsonapi#MarshalOnePayloadEmbedded)
 
 This method is not strictly meant to for use in implementation code,
 although feel free.  It was mainly created for use in tests; in most cases,
@@ -459,13 +644,13 @@ I use git subtrees to manage dependencies rather than `go get` so that
 the src is committed to my repo.
 
 ```
-git subtree add --squash --prefix=src/github.com/google/jsonapi https://github.com/google/jsonapi.git master
+git subtree add --squash --prefix=src/github.com/hashicorp/jsonapi https://github.com/hashicorp/jsonapi.git main
 ```
 
 To update,
 
 ```
-git subtree pull --squash --prefix=src/github.com/google/jsonapi https://github.com/google/jsonapi.git master
+git subtree pull --squash --prefix=src/github.com/hashicorp/jsonapi https://github.com/hashicorp/jsonapi.git main
 ```
 
 This assumes that I have my repo structured with a `src` dir containing