Alembic v1.0.0 Alembic.Relationships

The value of the relationships key MUST be an object (a “relationships object”). Members of the relationships object (“relationships”) represent references from the resource object in which it’s defined to other resource objects.

Relationships may be to-one or to-many.

JSON API - Document Structure - Resource Objects - Relationships

Summary

Types

t()

Maps String.t name to relationship

Functions

Validates that the given json follows the spec for ”relationship”

Types

t :: %{String.t => relationship}

Maps String.t name to relationship

Functions

from_json(json, error_template)

Specs

from_json(Alembic.json_object, Alembic.Error.t) ::
  {:ok, map} |
  Alembic.FromJson.error
from_json(nil, Alembic.Error.t) :: {:ok, nil}
from_json(true | false | list | float | integer | String.t, Alembic.Error.t) :: Alembic.FromJson.error

Validates that the given json follows the spec for ”relationship”.

"relationships" is optional, so it can be nil.

iex> Alembic.Relationships.from_json(
...>   nil,
...>   %Alembic.Error{
...>     source: %Alembic.Source{
...>       pointer: "/data/relationships"
...>     }
...>   }
...> )
{:ok, nil}

Relationships

Members of the relationships object (“relationships”) represent references from the resource object in which it’s defined to other resource objects.

JSON API - Document Structure - Resource Objects - Relationships

iex> Alembic.Relationships.from_json(
...>   %{"shirt" => []},
...>   %Alembic.Error{
...>     source: %Alembic.Source{
...>       pointer: "/data/relationships"
...>     }
...>   }
...> )
{
  :error,
  %Alembic.Document{
    errors: [
      %Alembic.Error{
        detail: "`/data/relationships/shirt` type is not relationship",
        meta: %{
          "type" => "relationship"
        },
        source: %Alembic.Source{
          pointer: "/data/relationships/shirt"
        },
        status: "422",
        title: "Type is wrong"
      }
    ]
  }
}

Data

Resource linkage in a compound document allows a client to link together all of the included resource objects without having to GET any URLs via links.

Resource linkage MUST be represented as one of the following:

  • null for empty to-one relationships.
  • an empty array ([]) for empty to-many relationships.
  • a single resource identifier object for non-empty to-one relationships.
  • an array of resource identifier objects for non-empty to-many relationships.

JSON API - Document Structure - Resource Objects - Resource Linkage

To-one

A to-one relationship, when present, will be a single Alembic.ResourceIdentifier.t

iex> Alembic.Relationships.from_json(
...>   %{
...>     "author" => %{
...>       "data" => %{
...>         "id" => "1",
...>         "type" => "author"
...>       }
...>     }
...>   },
...>   %Alembic.Error{
...>     source: %Alembic.Source{
...>       pointer: "/data/relationships"
...>     }
...>   }
...> )
{
  :ok,
  %{
    "author" => %Alembic.Relationship{
      data: %Alembic.ResourceIdentifier{
        id: "1",
        type: "author"
      }
    }
  }
}

An empty to-one relationship can be signified with nil, which would have been null in the original JSON.

iex> Alembic.Relationships.from_json(
...>   %{
...>     "author" => %{
...>       "data" => nil
...>     }
...>   },
...>   %Alembic.Error{
...>     source: %Alembic.Source{
...>       pointer: "/data/relationships"
...>     }
...>   }
...> )
{
  :ok,
  %{
    "author" => %Alembic.Relationship{
      data: nil
    }
  }
}

To-many

A to-many relationship, when preent, will be a list of Alembic.ResourceIdentifier.t

iex> Alembic.Relationships.from_json(
...>   %{
...>     "comments" => %{
...>       "data" => [
...>         %{
...>           "id" => "1",
...>           "type" => "comment"
...>         }
...>       ]
...>     }
...>   },
...>   %Alembic.Error{
...>     source: %Alembic.Source{
...>       pointer: "/data/relationships"
...>     }
...>   }
...> )
{
  :ok,
  %{
    "comments" => %Alembic.Relationship{
      data: [
        %Alembic.ResourceIdentifier{
          id: "1",
          type: "comment"
        }
      ]
    }
  }
}

An empty to-many resource linkage can be signified with [].

iex> Alembic.Relationships.from_json(
...>   %{
...>     "comments" => %{
...>       "data" => []
...>     }
...>   },
...>   %Alembic.Error{
...>     source: %Alembic.Source{
...>       pointer: "/data/relationships"
...>     }
...>   }
...> )
{
  :ok,
  %{
    "comments" => %Alembic.Relationship{
      data: []
    }
  }
}