# `JSONAPIPlug.Document`
[🔗](https://github.com/lucacorti/jsonapi_plug/blob/main/lib/jsonapi_plug/document.ex#L1)

JSON:API Document

This module defines the structure of a `JSON:API` document and functions that handle
serialization and deserialization. This also handles validation of `JSON:API` documents.

https://jsonapi.org/format/#document-structure

# `data`

```elixir
@type data() ::
  JSONAPIPlug.Document.ResourceObject.t()
  | [JSONAPIPlug.Document.ResourceObject.t()]
```

JSON:API Primary Data

https://jsonapi.org/format/#document-top-level

# `errors`

```elixir
@type errors() :: [JSONAPIPlug.Document.ErrorObject.t()]
```

JSON:API Errors

https://jsonapi.org/format/#errors

# `included`

```elixir
@type included() :: [JSONAPIPlug.Document.ResourceObject.t()]
```

JSON:API Included Resources

https://jsonapi.org/format/#document-compound-documents

# `jsonapi`

```elixir
@type jsonapi() :: JSONAPIPlug.Document.JSONAPIObject.t()
```

JSON:API Object

https://jsonapi.org/format/#document-jsonapi-object

# `links`

```elixir
@type links() :: %{required(atom()) => JSONAPIPlug.Document.LinkObject.t()}
```

JSON:API Links

https://jsonapi.org/format/#document-links

# `meta`

```elixir
@type meta() :: payload()
```

JSON:API Meta Information

https://jsonapi.org/format/#document-meta

# `payload`

```elixir
@type payload() :: %{required(String.t()) => value()}
```

# `t`

```elixir
@type t() :: %JSONAPIPlug.Document{
  data: JSONAPIPlug.Resource.t() | [JSONAPIPlug.Resource.t()] | nil,
  errors: errors() | nil,
  included: included() | nil,
  jsonapi: jsonapi() | nil,
  links: links() | nil,
  meta: meta() | nil
}
```

JSON:API Document

https://jsonapi.org/format/#document-structure

# `value`

```elixir
@type value() ::
  String.t()
  | integer()
  | float()
  | [value()]
  | %{required(String.t()) => value()}
  | nil
```

# `deserialize`

```elixir
@spec deserialize(payload()) :: t() | no_return()
```

Deserialize JSON:API Document

Takes a map representing a JSON:API Document as input, validates it
and parses it into a `t:t/0` struct.

# `serialize`

```elixir
@spec serialize(t()) :: t() | no_return()
```

Serialize a Document struct representing a JSON:API Document

Takes a `t:t/0` struct representing a JSON:API Document as input, validates
it and returns the struct if valid.

---

*Consult [api-reference.md](api-reference.md) for complete listing*