# Fields

Every option of an extract field.

An extract maps a field name to a selector string, or to a field object with these options. [Validation and warnings](https://docs.kaab.ist/concepts/validation-and-warnings) explains types, parsing and what happens when a value does not validate.

| Option | Type | Description |
|---|---|---|
| [`allow_suffix`](https://docs.kaab.ist/reference/dsl/fields/allow-suffix) | `boolean` | `number` and `integer` fields: accept magnitude suffixes such as `1.2k` and `1,5M`. Defaults to `false`. |
| [`attr`](https://docs.kaab.ist/reference/dsl/fields/attr) | `string` | Reads an attribute instead of the text: an attribute name such as `href`, `@html` for the inner HTML or `@outer` for the outer HTML. Defaults to the normalized text content. |
| [`base_url`](https://docs.kaab.ist/reference/dsl/fields/base-url) | `string` | `url` fields: the base a relative URL is resolved against. |
| [`candidates`](https://docs.kaab.ist/reference/dsl/fields/candidates) | `object[]` | An ordered list of field locators, tried in order. A field with `candidates` carries no other locator key (lint `E005`). |
| [`case_insensitive`](https://docs.kaab.ist/reference/dsl/fields/case-insensitive) | `boolean` | `enum` fields: match `values` ignoring case and surrounding whitespace. Defaults to `true`. |
| [`country`](https://docs.kaab.ist/reference/dsl/fields/country) | `string` | `phone` fields: the two-letter country used for numbers printed without a country code. Defaults to the one implied by `locale`. |
| [`currency`](https://docs.kaab.ist/reference/dsl/fields/currency) | `string` | `money` fields: the three-letter ISO currency code used when the page prints none. |
| [`date_format`](https://docs.kaab.ist/reference/dsl/fields/date-format) | `string or string[]` | `date` and `datetime` fields: one ICU format pattern or a list of them. ISO-8601 is always accepted. |
| [`decimal`](https://docs.kaab.ist/reference/dsl/fields/decimal) | `string` | The single-character decimal separator for numbers, overriding `locale`. |
| [`false_values`](https://docs.kaab.ist/reference/dsl/fields/false-values) | `string[]` | `boolean` fields: strings read as `false`. The defaults include `false`, `no`, `off`, `0`, `hayır`, `nein`, `non` and `no`. |
| [`fields`](https://docs.kaab.ist/reference/dsl/fields/fields) | `fields` | Child fields, each scoped to the matched element. With `many: true` the field is a list of objects, one per match; without it, a single object read from the first match. |
| [`flags`](https://docs.kaab.ist/reference/dsl/fields/flags) | `string` | Flags for `regex`: any of `i`, `m`, `s` and `u`. |
| [`follow_redirects`](https://docs.kaab.ist/reference/dsl/fields/follow-redirects) | `boolean` | `url` fields on a browser tier: a link that answers with a redirect is replaced by where it points, such as a search engine's click-through link. The link is asked once, from the job's exit, without following it. Defaults to `false`. |
| [`frame`](https://docs.kaab.ist/reference/dsl/fields/frame) | `string[]` | The chain of `<iframe>` selectors from the top document to the frame the field is in. |
| [`json`](https://docs.kaab.ist/reference/dsl/fields/json) | `string` | A JSONPath evaluated over JSON embedded in the page, such as `__NEXT_DATA__`, `window.__INITIAL_STATE__` and JSON script tags, in document order; the first non-empty result wins. An invalid path is lint `E009`. |
| [`locale`](https://docs.kaab.ist/reference/dsl/fields/locale) | `string` | A BCP-47 locale such as `tr` that sets the decimal, thousands and date defaults for parsing. Kaabist does not guess it; lint warns `W005` when a numeric sample is ambiguous without it. |
| [`many`](https://docs.kaab.ist/reference/dsl/fields/many) | `boolean` | When `true`, the field is a list with one entry per matched element: scalars, or objects when `fields` is present. |
| [`max`](https://docs.kaab.ist/reference/dsl/fields/max) | `number or string` | The largest allowed value: a number, or an ISO-8601 string for `date` and `datetime`. A value above it warns `out_of_range`. |
| [`max_items`](https://docs.kaab.ist/reference/dsl/fields/max-items) | `integer` | `many` fields: the most items allowed. |
| [`max_length`](https://docs.kaab.ist/reference/dsl/fields/max-length) | `integer` | The longest allowed string, in characters. |
| [`min`](https://docs.kaab.ist/reference/dsl/fields/min) | `number or string` | The smallest allowed value: a number, or an ISO-8601 string for `date` and `datetime`. A value below it warns `out_of_range`. |
| [`min_items`](https://docs.kaab.ist/reference/dsl/fields/min-items) | `integer` | `many` fields: the fewest items required. |
| [`min_length`](https://docs.kaab.ist/reference/dsl/fields/min-length) | `integer` | The shortest allowed string, in characters. |
| [`name`](https://docs.kaab.ist/reference/dsl/fields/name) | `string` | The accessible name that qualifies a `role` locator. |
| [`network`](https://docs.kaab.ist/reference/dsl/fields/network) | `object` | Reads the value from a captured JSON network response instead of the page. |
| [`null_markers`](https://docs.kaab.ist/reference/dsl/fields/null-markers) | `string[]` | Strings read as null. Defaults to `""`, `-`, the en and em dash characters, `N/A`, `n/a`, `null` and `None`. |
| [`nullable`](https://docs.kaab.ist/reference/dsl/fields/nullable) | `boolean` | Whether the value may be null. Defaults to `true`. |
| [`on_invalid`](https://docs.kaab.ist/reference/dsl/fields/on-invalid) | `"null" \| "raw" \| "fail" \| "drop"` | What happens to a value that cannot be parsed or breaks a constraint: `null` (the default), `raw` keeps the unparsed string, `fail` fails the job with `validation_failed`, `drop` removes the item from its list (only inside a `many` field). |
| [`pattern`](https://docs.kaab.ist/reference/dsl/fields/pattern) | `string` | A regular expression the parsed string must match. |
| [`presence`](https://docs.kaab.ist/reference/dsl/fields/presence) | `boolean` | `boolean` fields: true when the element exists, whatever it prints. Defaults to `false`. |
| [`regex`](https://docs.kaab.ist/reference/dsl/fields/regex) | `string` | A regular expression applied to the located element's text (or HTML, with `source`), or to the whole document when the field has no other locator. The first capture group is the value, or the whole match without one. |
| [`required`](https://docs.kaab.ist/reference/dsl/fields/required) | `boolean` | Whether a missing value warns `required_missing`. Defaults to `false`. |
| [`role`](https://docs.kaab.ist/reference/dsl/fields/role) | `string` | An ARIA role locator, usually with `name`. |
| [`sample`](https://docs.kaab.ist/reference/dsl/fields/sample) | `object` | A sample value recorded by the picker, kept as a permanent test of the field's parsing. |
| [`selector`](https://docs.kaab.ist/reference/dsl/fields/selector) | `string` | A CSS selector. Inside an item of a list, `:scope` is the item itself. |
| [`source`](https://docs.kaab.ist/reference/dsl/fields/source) | `"text" \| "html"` | What `regex` is applied to: `text` (the default) or `html`. |
| [`strip_fragment`](https://docs.kaab.ist/reference/dsl/fields/strip-fragment) | `boolean` | `url` fields: drop the `#fragment` while normalizing. Defaults to `false`. |
| [`testid`](https://docs.kaab.ist/reference/dsl/fields/testid) | `string` | The value of the element's test id attribute. |
| [`text`](https://docs.kaab.ist/reference/dsl/fields/text) | `string` | Locates the element by the text it shows. |
| [`thousands`](https://docs.kaab.ist/reference/dsl/fields/thousands) | `string` | The thousands separator for numbers, at most one character (empty for none), overriding `locale`. |
| [`timezone`](https://docs.kaab.ist/reference/dsl/fields/timezone) | `string` | `datetime` fields: the IANA time zone of times printed without an offset. |
| [`transforms`](https://docs.kaab.ist/reference/dsl/fields/transforms) | `"trim" \| "lowercase" \| "uppercase" \| "strip_html" \| "first" \| "last" or object[]` | Transforms applied in order to the raw string before it is parsed. |
| [`true_values`](https://docs.kaab.ist/reference/dsl/fields/true-values) | `string[]` | `boolean` fields: strings read as `true`. The defaults include `true`, `yes`, `on`, `1`, `evet`, `ja`, `oui` and `sí`. |
| [`type`](https://docs.kaab.ist/reference/dsl/fields/type) | `"string" \| "text" \| "number" \| "integer" \| "money" \| "boolean" \| "date" \| "datetime" \| "url" \| "email" \| "phone" \| "enum" \| "list" \| "object"` | The value's type: `string` (the default), `text`, `number`, `integer`, `money`, `boolean`, `date`, `datetime`, `url`, `email`, `phone`, `enum`, `list` or `object`. `list` and `object` are implied by `many` and `fields`. A `number`, `integer` or `money` reads the first number the text holds: a leading sign counts, a dash or plus further in ends the number, so the range `10-20` reads 10 and `1.299-1.499 TL` (`tr`) reads 1299. |
| [`unique`](https://docs.kaab.ist/reference/dsl/fields/unique) | `boolean or string` | Lists only: `true` requires the items to be distinct; a field name requires that field to be distinct across a list of objects. |
| [`values`](https://docs.kaab.ist/reference/dsl/fields/values) | `string[]` | `enum` fields: the allowed values, at least one. |
| [`xpath`](https://docs.kaab.ist/reference/dsl/fields/xpath) | `string` | An XPath expression locator. |