@spec cast(schema_or_reference() | nil, term(), map(), [cast_opt()]) ::
  {:ok, term()} | {:error, [OpenApiSpex.Cast.Error.t()]}

Cast and validate a value against the given schema.

Recognizes all the types defined in Open API (itself a superset of JSON Schema).

JSON Schema types: https://json-schema.org/latest/json-schema-core.html#rfc.section.4.2.1

Open API primitive types: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#data-types

For an :object schema type, the cast operation returns a map with atom keys.

examples

Examples

iex> alias OpenApiSpex.{Cast, Schema}
iex> schema = %Schema{type: :string}
iex> Cast.cast(schema, "a string")
{:ok, "a string"}
iex> Cast.cast(schema, 1..100)
{
  :error,
  [
    %OpenApiSpex.Cast.Error{
      reason: :invalid_type,
      type: :string,
      value: 1..100
    }
  ]
}
iex> schema = %Schema{
...>    type: :object,
...>    properties: %{
...>      name: nil
...>    },
...>    additionalProperties: false
...> }
iex> Cast.cast(schema, %{"name" => "spex"})
{:ok, %{name: "spex"}}
iex> Cast.cast(schema, %{"bad" => "spex"})
{
  :error,
  [
    %OpenApiSpex.Cast.Error{
      name: "bad",
      path: ["bad"],
      reason: :unexpected_field,
      value: %{"bad" => "spex"}
    }
  ]
}