# `Stevedore.Descriptor`
[🔗](https://github.com/oshlabs/stevedore/blob/v0.2.0/lib/stevedore/descriptor.ex#L1)

A typed, digest-addressed pointer to content (the OCI *descriptor*).

Descriptors are how a manifest references its config and layers, and how an index references
its per-platform manifests: each carries a `media_type`, the `digest` and `size` of the target
bytes, and optional metadata (`platform`, `annotations`, `urls`, `artifact_type`).

Spec: [OCI image-spec, descriptor](https://github.com/opencontainers/image-spec/blob/main/descriptor.md).

# `platform`

```elixir
@type platform() :: %{
  os: String.t(),
  architecture: String.t(),
  variant: String.t() | nil,
  os_version: String.t() | nil
}
```

# `t`

```elixir
@type t() :: %Stevedore.Descriptor{
  annotations: %{optional(String.t()) => String.t()} | nil,
  artifact_type: String.t() | nil,
  digest: Stevedore.Digest.t(),
  media_type: String.t(),
  platform: platform() | nil,
  size: non_neg_integer(),
  urls: [String.t()] | nil
}
```

# `from_json`

```elixir
@spec from_json(map()) :: {:ok, t()} | {:error, {:bad_input, term()}}
```

Builds a descriptor from a decoded JSON object (string keys, as on the wire).

## Examples

    iex> {:ok, d} = Stevedore.Descriptor.from_json(%{
    ...>   "mediaType" => "application/vnd.oci.image.layer.v1.tar+gzip",
    ...>   "digest" => "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    ...>   "size" => 32
    ...> })
    iex> {d.size, d.digest.algorithm}
    {32, :sha256}

# `from_json_full`

```elixir
@spec from_json_full(map()) :: {:ok, t()} | {:error, {:bad_input, term()}}
```

Builds a descriptor from JSON, attaching the optional fields (`platform`, `annotations`,
`urls`, `artifactType`) present in `json`.

# `to_json`

```elixir
@spec to_json(t()) :: map()
```

Renders a descriptor back to a JSON-ready map (string keys), omitting empty optional fields.

## Examples

    iex> d = %Stevedore.Descriptor{media_type: "application/vnd.oci.image.config.v1+json",
    ...>   digest: Stevedore.Digest.compute(""), size: 0}
    iex> Stevedore.Descriptor.to_json(d)["mediaType"]
    "application/vnd.oci.image.config.v1+json"

---

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