ExParamsSchema.Definition.Field (ex_params_schema v0.1.0)

正規化済みのフィールド定義を表す内部構造体です。

入力キー、任意性、エラー理由のようなフィールド単位の共通規則を提供します。

Summary

Types

normalized_array_type()

normalized_custom_type()

normalized_enum_type()

normalized_object_type()

normalized_type()

t()

Functions

error_reason(field, inherited_reason \\ nil)

フィールド固有、継承、既定値の優先順でエラー理由を返します。

fetch_value(params, field)

入力 map からフィールドの値を取得します。

input_key(field)

入力 map から値を取得するためのキーを返します。

missing_value(field)

入力に値がないフィールドの扱いを返します。

omit_from_validation?(field, arg2)

JSON Schema 検証用データからフィールド値を省略するかを返します。

optional?(field)

フィールドが省略可能かを返します。

optional_empty?(field, value)

省略可能なフィールドに対して、入力値を未指定相当として扱うかを返します。

unknown_input_key(params, fields)

フィールド定義に含まれない最初の入力キーを返します。

Types

normalized_array_type()

@type normalized_array_type() ::
  {kind :: :array, item_type :: normalized_type(),
   item_options :: ExParamsSchema.field_options()}

normalized_custom_type()

@type normalized_custom_type() ::
  {kind :: :custom, module :: module(), options :: keyword()}

normalized_enum_type()

@type normalized_enum_type() :: {kind :: :enum, allowed_values :: [atom()]}

normalized_object_type()

@type normalized_object_type() :: {kind :: :object, fields :: [t()]}

normalized_type()

@type normalized_type() ::
  ExParamsSchema.scalar_field_type()
  | normalized_enum_type()
  | normalized_custom_type()
  | normalized_array_type()
  | normalized_object_type()

t()

@type t() :: %ExParamsSchema.Definition.Field{
  name: atom(),
  options: ExParamsSchema.field_options(),
  type: normalized_type()
}

Functions

error_reason(field, inherited_reason \\ nil)

@spec error_reason(t(), ExParamsSchema.error_reason() | nil) ::
  ExParamsSchema.error_reason()

フィールド固有、継承、既定値の優先順でエラー理由を返します。

iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer, options: [error: :invalid_count]}
iex> ExParamsSchema.Definition.Field.error_reason(field, :invalid_params)
:invalid_count
iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer}
iex> ExParamsSchema.Definition.Field.error_reason(field, :invalid_params)
:invalid_params
iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer}
iex> ExParamsSchema.Definition.Field.error_reason(field)
{:invalid_param, :count}

fetch_value(params, field)

@spec fetch_value(map(), t()) :: {:ok, ExParamsSchema.value()} | :error

入力 map からフィールドの値を取得します。

source: で指定したキーを優先し、存在しない場合はフィールド名の atom key を参照します。

iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer, options: [source: "input-count"]}
iex> ExParamsSchema.Definition.Field.fetch_value(%{"input-count" => "1", count: "2"}, field)
{:ok, "1"}
iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer}
iex> ExParamsSchema.Definition.Field.fetch_value(%{"count" => "2"}, field)
{:ok, "2"}
iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer}
iex> ExParamsSchema.Definition.Field.fetch_value(%{"input-count" => "1"}, field)
:error

input_key(field)

@spec input_key(t()) :: String.t() | atom()

入力 map から値を取得するためのキーを返します。

iex> ExParamsSchema.Definition.Field.input_key(%ExParamsSchema.Definition.Field{name: :display_name, type: :string})
"display_name"
iex> ExParamsSchema.Definition.Field.input_key(%ExParamsSchema.Definition.Field{name: :display_name, type: :string, options: [source: "displayName"]})
"displayName"

missing_value(field)

@spec missing_value(t()) :: {:default, ExParamsSchema.value()} | :optional | :required

入力に値がないフィールドの扱いを返します。

default: があればその値を優先し、なければ optional: の設定に従います。

iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer, options: [default: 0]}
iex> ExParamsSchema.Definition.Field.missing_value(field)
{:default, 0}
iex> field = %ExParamsSchema.Definition.Field{name: :label, type: :string, options: [optional: true]}
iex> ExParamsSchema.Definition.Field.missing_value(field)
:optional
iex> field = %ExParamsSchema.Definition.Field{name: :count, type: :integer}
iex> ExParamsSchema.Definition.Field.missing_value(field)
:required

omit_from_validation?(field, arg2)

@spec omit_from_validation?(t(), ExParamsSchema.value()) :: boolean()

JSON Schema 検証用データからフィールド値を省略するかを返します。

optional: true の nil だけを省略し、nullable: true の nil は検証対象として残します。

iex> optional = %ExParamsSchema.Definition.Field{name: :label, type: :string, options: [optional: true]}
iex> ExParamsSchema.Definition.Field.omit_from_validation?(optional, nil)
true

iex> nullable = %ExParamsSchema.Definition.Field{name: :label, type: :string, options: [nullable: true]}
iex> ExParamsSchema.Definition.Field.omit_from_validation?(nullable, nil)
false

optional?(field)

@spec optional?(t()) :: boolean()

フィールドが省略可能かを返します。

iex> ExParamsSchema.Definition.Field.optional?(%ExParamsSchema.Definition.Field{name: :label, type: :string, options: [optional: true]})
true
iex> ExParamsSchema.Definition.Field.optional?(%ExParamsSchema.Definition.Field{name: :label, type: :string})
false

optional_empty?(field, value)

@spec optional_empty?(t(), ExParamsSchema.value()) :: boolean()

省略可能なフィールドに対して、入力値を未指定相当として扱うかを返します。

文字列では空文字に加えて空白だけの値も未指定相当です。

iex> field = %ExParamsSchema.Definition.Field{name: :label, type: :string, options: [optional: true]}
iex> ExParamsSchema.Definition.Field.optional_empty?(field, "  ")
true
iex> field = %ExParamsSchema.Definition.Field{name: :label, type: :string}
iex> ExParamsSchema.Definition.Field.optional_empty?(field, "  ")
false

unknown_input_key(params, fields)

@spec unknown_input_key(map(), [t()]) :: term() | nil

フィールド定義に含まれない最初の入力キーを返します。

各フィールドでは source: のキーとフィールド名の atom key の両方を許可します。

iex> fields = [%ExParamsSchema.Definition.Field{name: :count, type: :integer}]
iex> ExParamsSchema.Definition.Field.unknown_input_key(%{"count" => "1"}, fields)
nil
iex> ExParamsSchema.Definition.Field.unknown_input_key(%{"count" => "1", "extra" => "value", "extra2" => "value"}, fields)
"extra"
iex> fields = [%ExParamsSchema.Definition.Field{name: :count, type: :integer, options: [source: "input-count"]}]
iex> ExParamsSchema.Definition.Field.unknown_input_key(%{"input-count" => "1"}, fields)
nil