# `Macaw.Data.Source.Description`
[🔗](https://github.com/dcoai/macaw_data/blob/v0.5.3/lib/macaw/data/source/description.ex#L1)

What a source is (spec/01 §2.1): its schema, its parameters, the capabilities it
honors, and whether it answers every viewer the same.

- `schema`: a `Macaw.Data.Schema`;
- `params`: the parameters it takes, by name (strings), each a `Macaw.Data.Parameter`;
- `supports`: the capabilities it honors, distinct, among
  `:window | :box | :region | :latest | :budget | :push | :as_of`. Every one is optional:
  Macaw finishes what a source does not honor (spec/01 §2.4);
- `viewer_independent`: `true` declares the source answers every viewer the same, which
  only allows pooling across viewers, fetched with the anonymous viewer (spec/01 §6).
  `false` by default.

`new/1` builds one and reports every fault at once.

# `capability`

```elixir
@type capability() :: :window | :box | :region | :latest | :budget | :push | :as_of
```

A capability a source may honor.

# `t`

```elixir
@type t() :: %Macaw.Data.Source.Description{
  params: %{required(String.t()) => Macaw.Data.Parameter.t()},
  schema: Macaw.Data.Schema.t(),
  supports: [capability()],
  viewer_independent: boolean()
}
```

# `capabilities`

```elixir
@spec capabilities() :: [capability(), ...]
```

The capabilities, in the order spec/01 §2.1 lists them.

# `new`

```elixir
@spec new(keyword() | map()) :: {:ok, t()} | {:error, [{list(), term()}, ...]}
```

A description of the given fields, `schema` required: `{:ok, description}` or every
fault, `{path, reason}`, ordered by path.

    iex> alias Macaw.Data.{Schema, Source.Description}
    iex> {:ok, d} = Description.new(schema: Schema.new!(%{v: %{type: :number}}), supports: [:budget])
    iex> {d.supports, d.viewer_independent}
    {[:budget], false}
    iex> Description.new(schema: :nope, supports: [:region, :teleport, :region])
    {:error, [{[:schema], {:type, :schema}}, {[:supports, 1], {:enum, Description.capabilities()}}, {[:supports, 2], :duplicate}]}

# `new!`

```elixir
@spec new!(keyword() | map()) :: t()
```

As `new/1`, raising `ArgumentError` naming every fault.

---

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