# Fields

A **field** is what Vintage calls one of your columns once it is mapped: a column in your file becomes the field it was mapped to, either a **Standard field** (one Vintage understands, such as Current Balance or Loan Status) or a **Custom attribute** (a column Vintage keeps as-is so you can slice by it). For slicing and modeling to mean anything, a field has to mean the same thing every time it arrives. The **Fields** screen is where you see how each of your fields is stored and read, and where you change that deliberately.

Open it from **Fields** in the main navigation. It has two tabs: **Custom Fields**, which opens by default, and **Standard Fields**.

## Who can use the Fields screen

Admins and editors. Both tabs change what your data means, so the whole screen is closed to viewers: the Fields entry does not appear in their navigation, and going to the screen directly shows a page saying their role does not include access. See [Roles and permissions](/reference/roles-and-permissions/).

While the Vintage team is setting up a new organization's first portfolio, the Fields entry is hidden for everyone and opens when setup is done. See [Your first upload](/uploading/your-first-upload/).

## One field per name, across every upload

Vintage keeps a register of your organization's fields: **one field per name**, with **one value type** that holds across all your uploads. The first upload that brings a field sets its type. Later uploads merge into the same field rather than creating a new one, even when the spelling of a custom column drifts between exports: `FICO Score`, `fico score`, and `FICO Score` with a stray space before or after it are all the same field. Differences in capitalization and spacing do not make a new field. Your original spelling is kept as the field's display name.

### The four value types

| Type | What it holds | How you slice it |
|---|---|---|
| **Numeric** | Numbers: amounts, scores, rates, counts | A range |
| **Date** | Calendar dates and `YYYYMM`-style period codes, as points on a timeline | A date range |
| **Categorical** | A limited set of values: statuses, codes, yes/no flags | A value checklist |
| **Text** | Free text | Text operators (contains, starts with, and so on) |

There is **no yes/no (boolean) type**. A flag or Y/N column is categorical: you include or exclude its values like any other category.

A **numeric** field tolerates the occasional non-numeric value a core system emits in an otherwise numeric column (an `Unknown` or `Pending` among the numbers). The column still counts as numeric, and those cells are treated as having no value rather than disqualifying the field. A **date** field reads every cell by the date format declared for that column, so the same calendar date is read the same way however an export writes it. Date formats are covered on [Declaring formats](/uploading/declaring-formats/).

### Numeric formats

Every numeric field also has a **format**:

| Format | What it does |
|---|---|
| **Number** | Display only. |
| **Currency** | Display only: values show as `$1,234.56`. |
| **Percent points (8.25 means 8.25%)** | Reads the column's numerals as percent points. |
| **Decimal fraction (0.0825 means 8.25%)** | Reads the column's numerals as fractions. |

Number and currency change only how values look. The two percent formats are different in kind: each is an instruction for reading the whole column, applied to every cell. Whichever one a column uses, Vintage stores the value in percent points and shows it as `X%`:

$$
\text{stored rate} =
\begin{cases}
v & \text{when the column is Percent points} \\
100 \times v & \text{when the column is Decimal fraction}
\end{cases}
$$

where `v` is the number written in your file. In words: picking the wrong percent format multiplies or divides every value in that field by 100, which is why changing between them is treated like a type change. A file that writes `0.0825` in a column declared Decimal fraction stores 8.25 and shows 8.25%; the same column declared Percent points would store 0.0825 and show 0.0825%. The format menu marks the option your file's own numbers point to as **matches your data**. It is a recommendation; the choice is yours. The rules for choosing are on [Declaring formats](/uploading/declaring-formats/).

## When a new upload disagrees with a field's type

Because a field's type holds across uploads, a later upload whose column maps to an existing field but looks like a different type is caught when the file is analyzed, never quietly accepted. What happens depends on whether anything would be lost:

- **Nothing lost.** When every value still fits the field's established type (a column that reads as categorical where the field is text, for example), Column Mapping shows an informational note and you can continue.
- **Values lost.** When some non-empty values would not fit the established type and would become empty, Column Mapping shows a **blocking conflict** naming how many values are affected. You resolve it before continuing in one of three ways: change the field's type (below), exclude the column, or map the column to a Standard field instead.

A compatible upload keeps the field's type. You cannot keep the column as a separate field under a new name. [Mapping columns](/uploading/mapping-columns/) covers the rest of the mapping screen.

## Changing a field's type

You can change an established field's type on purpose. A type change is available for **custom fields that describe the loan**. Standard fields keep the type Vintage knows them by.

Before anything changes, Vintage shows a **consequence preview**: how many of the field's stored values would not fit the new type and would become empty, with examples. "412 of 8,412 values will not fit and will become empty," or "All 8,412 values fit the new type. Nothing will be emptied." If your portfolio is still updating from another change, the preview adds that the counts may still shift. On a very large field, the counts come from Vintage's most recent measurement of the field and say so ("Based on the last data refresh"). If the preview cannot be checked, saving is disabled until it can: you are never asked to confirm a change whose effect is unknown.

When you confirm, Vintage re-reads every value of that field you have ever uploaded, from the values as originally uploaded, and stores them under the new type. The change applies to your whole portfolio, not only to future uploads. Your Portfolio and Modeling screens then show that the portfolio is updating until every affected loan has been rebuilt. See [the Portfolio screen](/portfolio/the-portfolio-screen/#while-your-portfolio-is-updating).

| Change | What Vintage does |
|---|---|
| Number to Currency, or back | Changes how values look. Nothing is re-read; no confirmation is needed. |
| Into, out of, or between the percent formats | Re-reads the field from your uploaded values and updates modeling. Confirmed first. |
| One type to another | Re-reads the field from your uploaded values under the new type. Confirmed first, with the consequence preview. |

You can change an existing field's type from two places: the **Custom Fields** tab, and the **Change type** action on an existing field's row in Column Mapping during an upload.

## The Custom Fields tab

This tab lists the custom fields that describe your loans: the custom columns from your Origination and Snapshot files. Custom columns that arrive only on Transaction files describe events, not loans, and are not managed here today.

| Column | What it shows |
|---|---|
| **Field** | The field's display name, with the key Vintage stores it under beneath it. |
| **Type** | The stored type, and for numeric fields a **Format** menu. Both are editable. |
| **Coverage** | How many loans have a value for the field, and how many distinct values it has. |
| **Sample values** | A few of the field's stored values, or for a numeric or date field its range ("Range: 300 to 850"). |

The coverage and samples always describe what is stored now, not a change you have not saved yet.

**Editing.** Changing a Type or Format marks the row **Changed**, and a banner appears: **Unsaved changes**, with **Discard changes** and **Save changes**. Nothing is saved until you press Save. Setting a menu back to its original value un-marks the row.

**Saving.** If every pending change is display-only (Number to Currency, or back), it saves at once. If any change is a type change or crosses into, out of, or between the percent formats, a confirmation opens first, headed **Save type changes?** It shows each changed field with its consequence preview. **Save changes** applies them; **Keep editing** returns you to the tab with your edits intact.

## The Standard Fields tab

Standard fields keep Vintage's own type, but some facts about how your organization's data should be **read** can only come from you. This tab holds those answers, each editable in place, and below them the reference list of every standard field. Changing any of these answers re-reads your uploaded data, and the curves and slices update to match.

### Portfolio semantics

Facts about how your book behaves that no file can show. Vintage never guesses them; you declare them. Today there is one question:

> When a loan is charged off, does it leave your exports, or can it survive a partial write-down?

The answers are **It leaves our exports** (the suggested default, since most cores drop a loan at charge-off) and **It can survive a partial write-down**. Your choice is saved as soon as you make it, and a note beneath says whether the setting in force is your own answer or the suggested default. If your own classified status values already answer the question, the section says so, and the setting has no effect while that stays true.

The same question is asked on the Review screen when an upload contains loans that keep reporting a balance after they were charged off; this tab is its permanent home. In short, answering "survive" lets each charge-off amount book as a loss in its own month while the loan stays measured; a loan's lifetime loss is the same either way, and only the timing moves. The full rule is on [Charge-offs and recoveries](/concepts/charge-offs-and-recoveries/).

### How amounts are reported

Your core may export an amount column as **each month's own activity**, as a **running total** from the start of the loan, or as a **year-to-date total** that resets each January, and a single month looks the same either way. This section lists every amount column your organization has mapped (charge-off, net charge-off, recovery, actual principal paid, actual payment, scheduled principal, and the Transaction Amount of a **typed ledger**, meaning a Transaction file whose Transaction Type column says what each row is) with how each is read:

- **Amount for that month**
- **Running total (life-to-date)**
- **Year-to-date (resets in January)**

The note under each row says whose answer is in force: your own, Vintage's suggestion from your data that you have not confirmed, or **not set**, in which case the column is being read as each month's own amount until you choose. This is also where you can answer for a column mapped before Vintage asked about it. Reading a running total as monthly activity would count an event once for every month it lingers in the file, which is why the answer matters. [Declaring formats](/uploading/declaring-formats/) explains how Vintage suggests an answer.

### Rate format

How a rate column is written in your files. Today this covers **Interest Rate**, which defaults to **Percent points**: rates arrive as `8.36` and show as "8.36%". If your core exports rates as fractions (`0.0836`), choose **Decimal fraction**.

Because this rewrites every stored rate in your organization, it is **confirmed before it saves**. The confirmation, headed **Change the rate format?**, states that Vintage re-reads every file you have uploaded and rewrites the stored values for the whole organization, names the factor ("Every stored value is multiplied by 100"), and shows a real before and after built from your own highest stored value. It says how many loans carry a value for the field, and that switching back restores the original values exactly. Two honesty rules hold: when nothing is stored for the field yet, it says there is nothing to preview rather than inventing an example, and when the field's coverage has not been counted yet, it says so rather than claiming the change applies to no loans.

### What your values mean

For each classified field (Loan Status, Closure Reason, the Charge-Off, Payoff, and Prepayment Flags, and a typed ledger's Transaction Type), this section shows every value your organization has classified and what it means, as a **Value** and **Meaning** table:

| Field | Meanings you can choose |
|---|---|
| Loan Status, Closure Reason | Open (still active), Paid off, Charged off, Exited (other) |
| Charge-Off Flag | Marks a charge-off, or Does not |
| Payoff Flag | Marks a payoff, or Does not |
| Prepayment Flag | Marks a full prepayment, or Does not |
| Transaction Type | Charge-off, Recovery, Payoff, Partial prepayment, Regular payment, Not a modeled event |

Values are classified when you map the column during an upload; this is where you correct one later. Saving a change rebuilds the whole portfolio's modeling, so loans from every past upload reflect the corrected meaning, not only future ones. What each meaning does to the curves is on [Classifying values](/uploading/classifying-values/).

### Saving on this tab

Pending changes to amounts, rate format, or value meanings raise one banner: **Unsaved changes**, with **Discard** and **Save changes**, and a reminder that saving re-reads your uploaded data. A rate-format change shows its confirmation first.

### All standard fields

The tab ends with the reference list of every standard field: its name with its field id beneath, its type, the file groups it appears on, and a short description. The same list, with the column names Vintage also recognizes, is on [Standard fields](/reference/standard-fields/).

**Note:** Field types, formats, and value meanings belong to the organization: a change by one admin or editor applies for everyone. Segments do not: each person keeps their own. See [Segments](/portfolio/segments/).

## Related

- [Mapping columns](/uploading/mapping-columns/)
- [Declaring formats](/uploading/declaring-formats/)
- [Classifying values](/uploading/classifying-values/)
- [Segments](/portfolio/segments/)
- [Standard fields](/reference/standard-fields/)
- [File requirements and parsing rules](/reference/file-requirements-and-parsing-rules/)