# `JSON.LD`
[🔗](https://github.com/rdf-elixir/jsonld-ex/blob/v1.0.1/lib/json_ld.ex#L1)

An implementation of JSON-LD 1.1.

It includes an implementation of the `RDF.Serialization.Format` behaviour of RDF.ex.

See <https://json-ld.org/>

# `context_convertible`

```elixir
@type context_convertible() ::
  map() | String.t() | nil | RDF.PropertyMap.t() | [context_convertible()]
```

# `input`

```elixir
@type input() ::
  map()
  | [map()]
  | String.t()
  | RDF.IRI.t()
  | JSON.LD.DocumentLoader.RemoteDocument.t()
```

# `compact`

```elixir
@spec compact(input(), context_convertible(), JSON.LD.Options.convertible()) :: map()
```

Compacts the given input according to the steps in the JSON-LD Compaction Algorithm.

> Compaction is the process of applying a developer-supplied context to shorten
> IRIs to terms or compact IRIs and JSON-LD values expressed in expanded form
> to simple values such as strings or numbers. Often this makes it simpler to
> work with document as the data is expressed in application-specific terms.
> Compacted documents are also typically easier to read for humans.

-- <https://www.w3.org/TR/json-ld/#compacted-document-form>

Details at <https://www.w3.org/TR/json-ld-api/#compaction-algorithms>

This is the `compact()` API function of the `JsonLdProcessor` interface as specified in
<https://www.w3.org/TR/json-ld11-api/#the-application-programming-interface>

# `context`

```elixir
@spec context(context_convertible(), JSON.LD.Options.t()) :: JSON.LD.Context.t()
```

Generator function for `JSON.LD.Context`s.

You can either pass a map with a `"@context"` key having the JSON-LD context
object its value, or the JSON-LD context object directly.

This function can be used also to create `JSON.LD.Context` from a `RDF.PropertyMap`.

# `expand`

```elixir
@spec expand(input(), JSON.LD.Options.convertible()) :: map() | [map()] | nil
```

Expands the given input according to the steps in the JSON-LD Expansion Algorithm.

> Expansion is the process of taking a JSON-LD document and applying a `@context`
> such that all IRIs, types, and values are expanded so that the `@context` is
> no longer necessary.

-- <https://www.w3.org/TR/json-ld/#expanded-document-form>

Details at <http://json-ld.org/spec/latest/json-ld-api/#expansion-algorithm>

This is the `expand()` API function of the `JsonLdProcessor` interface as specified in
<https://www.w3.org/TR/json-ld11-api/#the-application-programming-interface>

# `flatten`

```elixir
@spec flatten(input(), context_convertible(), JSON.LD.Options.convertible()) :: [
  map()
]
```

Flattens the given input according to the steps in the JSON-LD Flattening Algorithm.

> Flattening collects all properties of a node in a single JSON object and labels
> all blank nodes with blank node identifiers. This ensures a shape of the data
> and consequently may drastically simplify the code required to process JSON-LD
> in certain applications.

-- <https://www.w3.org/TR/json-ld/#flattened-document-form>

Details at <https://www.w3.org/TR/json-ld-api/#flattening-algorithms>

This is the `flatten()` API function of the `JsonLdProcessor` interface as specified in
<https://www.w3.org/TR/json-ld11-api/#the-application-programming-interface>

# `from_rdf`

Transforms the given `RDF.Dataset` into a JSON-LD document in expanded form.

Details at <https://www.w3.org/TR/json-ld-api/#serialize-rdf-as-json-ld-algorithm>

This is the `toRdf()` API function of the `JsonLdProcessor` interface as specified in
<https://www.w3.org/TR/json-ld11-api/#the-application-programming-interface>

# `keyword?`

```elixir
@spec keyword?(String.t() | any()) :: boolean()
```

Returns if the given value is a JSON-LD keyword.

# `keywords`

```elixir
@spec keywords() :: [String.t()]
```

The set of all JSON-LD keywords.

see <https://www.w3.org/TR/json-ld/#syntax-tokens-and-keywords>

# `node_map`

Generator function for JSON-LD node maps.

# `options`

```elixir
@spec options() :: JSON.LD.Options.t()
```

# `read_file`

```elixir
@spec read_file(
  Path.t(),
  keyword()
) :: {:ok, RDF.Graph.t() | RDF.Dataset.t()} | {:error, any()}
```

Deserializes a graph or dataset from a file.

It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
dataset, or `{:error, reason}` if an error occurs.

## Options

General serialization-independent options:

- `:stream`: Allows to enable reading the data from a file directly via a
stream (default: `false` on this function, `true` on the bang version)
- `:gzip`: Allows to read directly from a gzipped file (default: `false`)
- `:file_mode`: A list with the Elixir `File.open` modes to be used for reading
  (default: `[:read, :utf8]`)

See the [module documentation of the decoder](`Elixir.JSON.LD.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `read_file!`

```elixir
@spec read_file!(
  Path.t(),
  keyword()
) :: RDF.Graph.t() | RDF.Dataset.t()
```

Deserializes a graph or dataset from a file.

As opposed to `read_file/2`, it raises an exception if an error occurs and
defaults to `stream: true`.

See `read_file/3` for the available format-independent options.

See the [module documentation of the decoder](`Elixir.JSON.LD.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `read_stream`

```elixir
@spec read_stream(
  Enumerable.t(),
  keyword()
) :: {:ok, RDF.Graph.t() | RDF.Dataset.t()} | {:error, any()}
```

Deserializes a graph or dataset from a stream.

It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
dataset, or `{:error, reason}` if an error occurs.

See the [module documentation of the decoder](`Elixir.JSON.LD.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `read_stream!`

```elixir
@spec read_stream!(
  Enumerable.t(),
  keyword()
) :: RDF.Graph.t() | RDF.Dataset.t()
```

Deserializes a graph or dataset from a stream.

As opposed to `read_stream/2`, it raises an exception if an error occurs.

See the [module documentation of the decoder](`Elixir.JSON.LD.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `read_string`

```elixir
@spec read_string(
  String.t(),
  keyword()
) :: {:ok, RDF.Graph.t() | RDF.Dataset.t()} | {:error, any()}
```

Deserializes a graph or dataset from a string.

It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
dataset, or `{:error, reason}` if an error occurs.

See the [module documentation of the decoder](`Elixir.JSON.LD.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `read_string!`

```elixir
@spec read_string!(
  String.t(),
  keyword()
) :: RDF.Graph.t() | RDF.Dataset.t()
```

Deserializes a graph or dataset from a string.

As opposed to `read_string/2`, it raises an exception if an error occurs.

See the [module documentation of the decoder](`Elixir.JSON.LD.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `to_rdf`

Transforms the given JSON-LD document into an `RDF.Dataset`.

Details at <https://www.w3.org/TR/json-ld-api/#deserialize-json-ld-to-rdf-algorithm>

This is the `fromRdf()` API function of the `JsonLdProcessor` interface as specified in
<https://www.w3.org/TR/json-ld11-api/#the-application-programming-interface>

# `write_file`

```elixir
@spec write_file(RDF.Data.Source.t(), Path.t(), keyword()) :: :ok | {:error, any()}
```

Serializes an RDF data structure to a file.

It returns `:ok` if successful or `{:error, reason}` if an error occurs.

## Options

General serialization-independent options:

- `:stream`: Allows to enable writing the serialized data to the file directly
  via a stream. Possible values: `:string` or `:iodata` for writing to the file
  with a stream of strings respective IO lists, `true` if you want to use streams,
  but don't care for the exact method or `false` for not writing with
  a stream (default: `false` on this function, `:iodata` on the bang version)
- `:gzip`: Allows to write directly to a gzipped file (default: `false`)
- `:force`: If not set to `true`, an error is raised when the given file
  already exists (default: `false`)
- `:file_mode`: A list with the Elixir `File.open` modes to be used for writing
  (default: `[:write, :exclusive]`)

See the [module documentation of the encoder](`Elixir.JSON.LD.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

# `write_file!`

```elixir
@spec write_file!(RDF.Data.Source.t(), Path.t(), keyword()) :: :ok
```

Serializes an RDF data structure to a file.

As opposed to `write_file/3`, it raises an exception if an error occurs.

See `write_file/3` for the available format-independent options.

See the [module documentation of the encoder](`Elixir.JSON.LD.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

# `write_string`

```elixir
@spec write_string(
  RDF.Data.Source.t(),
  keyword()
) :: {:ok, String.t()} | {:error, any()}
```

Serializes an RDF data structure to a string.

It returns an `{:ok, string}` tuple, with `string` being the serialized graph or
dataset, or `{:error, reason}` if an error occurs.

See the [module documentation of the encoder](`Elixir.JSON.LD.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

# `write_string!`

```elixir
@spec write_string!(
  RDF.Data.Source.t(),
  keyword()
) :: String.t()
```

Serializes an RDF data structure to a string.

As opposed to `write_string/2`, it raises an exception if an error occurs.

See the [module documentation of the encoder](`Elixir.JSON.LD.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

---

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