# `Tune.Field`
[🔗](https://github.com/mikehostetler/tune/blob/v0.5.0/lib/tune/field.ex#L1)

One named, typed signature field.

Names are trusted identifiers stored as strings. They must be valid XML
element names made of ASCII letters, digits, and underscores, must not start
with `xml`, and must not be `completed`, which the Chat format reserves.

Schemas are Zoi schemas restricted to JSON-representable values: strings,
integers, floats, numbers, booleans, null, string enums, scalar literals,
arrays, string-keyed objects, string-keyed records, and unions of those,
including nullable fields. Transforms, defaults, and optional top-level fields
are rejected so a reply cannot pass validation by omission or rewriting.

# `spec`

```elixir
@type spec() ::
  t()
  | {atom() | String.t(), Zoi.schema()}
  | {atom() | String.t(), Zoi.schema(), keyword()}
```

# `t`

```elixir
@type t() :: %Tune.Field{
  description: String.t() | nil,
  name: String.t(),
  schema: Zoi.schema()
}
```

# `check_schema`

```elixir
@spec check_schema(term(), String.t()) :: :ok | {:error, Exception.t()}
```

Checks that a schema is a supported JSON-compatible contract.

Used for parameter schemas, which follow the same rules as top-level fields.

# `json_schema`

```elixir
@spec json_schema(t() | Zoi.schema()) :: map()
```

Returns the field's JSON Schema without the top-level `$schema` keyword.

# `new`

```elixir
@spec new(spec()) :: {:ok, t()} | {:error, Exception.t()}
```

Normalizes one field specification.

# `nullable?`

```elixir
@spec nullable?(Zoi.schema()) :: boolean()
```

Returns `true` when the schema accepts `nil`.

# `text_valued?`

```elixir
@spec text_valued?(Zoi.schema()) :: boolean()
```

Returns `true` when the schema's reply text is used verbatim by text formats.

String, string enum, and string literal schemas, optionally nullable, read the
raw field text. Every other schema is decoded as JSON.

---

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