# `Spark.Builder.Field`
[🔗](https://github.com/ash-project/spark/blob/v2.7.0/lib/spark/builder/field.ex#L5)

Builder for individual schema field specifications.

This module provides an option-based API for constructing field definitions
used in `Spark.Options` schemas. Each field can have type, validation,
documentation, and DSL-specific attributes.

## Examples

    iex> alias Spark.Builder.Field
    iex> Field.new(:name, :atom, required: true, doc: "The field name")
    ...> |> Field.to_spec()
    {:name, [type: :atom, required: true, doc: "The field name"]}

    iex> alias Spark.Builder.Field
    iex> Field.new(:status, {:one_of, [:pending, :active]}, default: :pending)
    ...> |> Field.to_spec()
    {:status, [type: {:one_of, [:pending, :active]}, default: :pending]}

## Nested Keys

The `:keys` option accepts raw keyword lists, `Field` structs, or a
zero-arity function returning a schema, allowing composable nested schemas:

    alias Spark.Builder.Field

    Field.new(:config, :keyword_list,
      keys: [
        Field.new(:host, :string, required: true, doc: "Server hostname"),
        Field.new(:port, :integer, default: 4000, doc: "Server port"),
        Field.new(:ssl, :boolean, default: false, doc: "Enable SSL")
      ],
      doc: "Server configuration"
    )

Lazy schemas are supported:

    Field.new(:config, :keyword_list,
      keys: &__MODULE__.options_schema/0
    )

# `t`
*since 2.5.0* 

```elixir
@type t() :: %Spark.Builder.Field{
  as: atom() | nil,
  default: any(),
  deprecated: String.t() | nil,
  doc: String.t() | false | nil,
  has_default: boolean(),
  hide: [atom()],
  keys: Spark.Options.schema() | (-> Spark.Options.schema()) | nil,
  links: keyword() | nil,
  name: atom() | nil,
  private?: boolean(),
  required: boolean(),
  snippet: String.t() | nil,
  subsection: String.t() | nil,
  type: Spark.Options.type(),
  type_doc: String.t() | false | nil,
  type_spec: Macro.t() | nil
}
```

# `new`
*since 2.5.0* 

```elixir
@spec new(atom(), Spark.Options.type(), keyword()) :: t()
```

Creates a new field builder with the given name and type.

Options can set common attributes like `:required` and `:default`.

`:keys` accepts a raw schema keyword list, a list of `Field` structs, or a
zero-arity function that returns a schema.

## Options

  - `:required`, `:default`, `:keys`, `:doc`, `:type_doc`,
    `:subsection`, `:as`, `:snippet`, `:links`, `:deprecated`,
    `:private?`, `:hide`, `:type_spec`

## Examples

    iex> Spark.Builder.Field.new(:my_field, :any)
    %Spark.Builder.Field{name: :my_field, type: :any}

    iex> Spark.Builder.Field.new(:type, :atom, required: true)
    ...> |> Spark.Builder.Field.to_spec()
    {:type, [type: :atom, required: true]}

# `to_schema`
*since 2.5.0* 

```elixir
@spec to_schema([t() | {atom(), keyword()}] | t()) :: Spark.Options.schema()
```

Builds a complete schema from a list of field builders or raw schema tuples.

## Examples

    iex> [
    ...>   Field.new(:name, :atom, required: true),
    ...>   Field.new(:count, :integer, default: 0)
    ...> ]
    ...> |> Field.to_schema()
    [name: [type: :atom, required: true], count: [type: :integer, default: 0]]

    iex> Field.to_schema([name: [type: :atom, required: true]])
    [name: [type: :atom, required: true]]

# `to_spec`
*since 2.5.0* 

```elixir
@spec to_spec(t()) :: {atom(), keyword()}
```

Converts the field builder to a schema specification tuple.

Returns `{name, opts}` suitable for use in a `Spark.Options` schema.

## Examples

    iex> Field.new(:name, :atom, required: true)
    ...> |> Field.to_spec()
    {:name, [type: :atom, required: true]}

---

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