# uip ixp taxonomy — fields, groups, data-types

> Syntax and options for `uip ixp fields`, `uip ixp groups`, and `uip ixp data-types`, which edit a project's extraction taxonomy one piece at a time.

Three command groups edit a project's taxonomy incrementally: `uip ixp data-types` (`entity_defs` — reusable type definitions), `uip ixp groups` (`label_defs` — field-group containers), and `uip ixp fields` (the individual named values inside a group). See [Concepts](./uip-ixp.md#concepts) on the parent page for how these three relate, and [`projects get-taxonomy`/`import-taxonomy`](./uip-ixp-projects.md#uip-ixp-projects-get-taxonomy) for moving the whole taxonomy as one artifact instead.

Every verb's `Data` is the IXP API response forwarded verbatim, preserving its native key casing.

## Synopsis

```text
uip ixp data-types add <project-name> --name <name> --kind <kind> --instructions <text> [--input-value <mode>] [--choices <json>]
uip ixp data-types update-instructions <project-name> --name <name> --instructions <text>
uip ixp data-types rename <project-name> --name <name> --new-name <name>
uip ixp data-types delete <project-name> --name <name> -y

uip ixp groups add <project-name> --name <name> --instructions <text> --fields <json>
uip ixp groups delete <project-name> --name <name> -y
uip ixp groups rename <project-name> --name <name> --new-name <name>
uip ixp groups update-prompts <project-name> --updates <json>

uip ixp fields add <project-name> --group <name> --field <name> --type <type> --instructions <text>
uip ixp fields delete <project-name> --group <name> --field <name> -y
uip ixp fields rename <project-name> --group <name> --field <name> --new-name <name>
uip ixp fields change-type <project-name> --group <name> --field <name> --type <type> -y
uip ixp fields update-prompts <project-name> --updates <json>
```

## uip ixp data-types

Manage data types (`entity_defs`) — the reusable type definitions fields reference by name.

### uip ixp data-types add

Create a new data type in the project.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | Data type name. |
| `--kind <kind>` | `text`\|`date`\|`money`\|`number`\|`boolean`\|`choice` | **yes** | Underlying data type kind. |
| `--instructions <text>` | string | **yes** | What this type represents and where its values appear. |
| `--input-value <mode>` | `exact-match`\|`inferred` | conditionally | **Required** when `--kind` is `text` or `choice`; **forbidden** for `date`/`money`/`number`/`boolean` (those kinds have no such property, matching the IXP UI's radio visibility). Whether the value appears verbatim in the document, or is inferred/computed. |
| `--choices <json>` | JSON array | conditionally | **Required** when `--kind choice`: `[{"value":"<canonical>","alternates":["<alt1>",...]}]`. `value` is the canonical display name (model output); `alternates` (optional) are other spellings the model maps to `value`. |

#### Examples

```bash
uip ixp data-types add my-invoices --name "Email Address" --kind text \
  --instructions "An email address in the form local@domain." --input-value exact-match
```

```bash
# boolean kinds don't take --input-value
uip ixp data-types add my-invoices --name "Has Signature" --kind boolean \
  --instructions "True if the document has a handwritten signature."
```

```bash
# choice kind — alternates are optional per entry
uip ixp data-types add my-invoices --name "Citizenship" --kind choice \
  --instructions "Borrower citizenship status." --input-value exact-match \
  --choices '[{"value":"us","alternates":["U.S. Citizen","United States","USA"]},{"value":"permanent alien","alternates":["lawful permanent resident"]},{"value":"non-permanent alien"}]'
```

#### Data shape (--output json)

```json
{
  "Code": "IxpDataTypesAdd",
  "Data": { "ProjectName": "my-invoices", "Name": "Email Address", "Kind": "text", "InputValue": "exact-match" }
}
```

### uip ixp data-types update-instructions

Replace the instructions on an existing data type.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | Data type name. |
| `--instructions <text>` | string | **yes** | New instructions (replaces the existing value). |

#### Example

```bash
uip ixp data-types update-instructions my-invoices --name "Email Address" \
  --instructions "A valid email address in the form local@domain. Reject malformed addresses."
```

#### Data shape (--output json)

```json
{ "Code": "IxpDataTypesUpdateInstructions", "Data": { "ProjectName": "my-invoices", "Name": "Email Address" } }
```

### uip ixp data-types rename

Rename a data type. Existing field references stay intact.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | Current data type name. |
| `--new-name <name>` | string | **yes** | New data type name. |

#### Example

```bash
uip ixp data-types rename my-invoices --name "Email Address" --new-name "Email"
```

#### Data shape (--output json)

```json
{ "Code": "IxpDataTypesRename", "Data": { "ProjectName": "my-invoices", "OldName": "Email Address", "NewName": "Email" } }
```

### uip ixp data-types delete

Delete a data type. **Irreversible**: any field referencing it via `field_type_id` will break.

#### Options

| Short | Long | Value | Required | Description |
|---|---|---|---|---|
| — | `--name <name>` | string | **yes** | Data type name to delete. |
| `-y` | `--yes` | flag | **yes** | Confirm this irreversible operation. |

#### Example

```bash
uip ixp data-types delete my-invoices --name "Email Address" --yes
```

#### Data shape (--output json)

```json
{ "Code": "IxpDataTypesDelete", "Data": { "ProjectName": "my-invoices", "Name": "Email Address" } }
```

## uip ixp groups

Manage field groups (`label_defs`) — the document-type containers for fields.

### uip ixp groups add

Create a new field group with instructions and at least one field.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | New field group name. |
| `--instructions <text>` | string | **yes** | What kind of document/section the group covers. |
| `--fields <json>` | JSON array | **yes** | At least one field: `[{"name":"...","type":"<data-type-name>","instructions":"..."}]`. `type` is the name of a data type (`entity_def`) in the project's taxonomy — resolved and validated server-side. |

#### Example

```bash
uip ixp groups add my-invoices --name Invoice --instructions "Header fields" \
  --fields '[{"name":"Invoice Number","type":"Text","instructions":"Unique invoice identifier near the top-right."},{"name":"Date","type":"Date","instructions":"Date the invoice was issued."},{"name":"Total","type":"Money","instructions":"Grand total at the bottom."}]'
```

#### Data shape (--output json)

```json
{ "Code": "IxpGroupsAdd", "Data": { "ProjectName": "my-invoices", "Group": "Invoice", "FieldsCreated": 3 } }
```

### uip ixp groups delete

Delete a field group. **Irreversible**: all annotations on all fields in the group are deleted.

#### Options

| Short | Long | Value | Required | Description |
|---|---|---|---|---|
| — | `--name <name>` | string | **yes** | Field group name to delete. |
| `-y` | `--yes` | flag | **yes** | Confirm this irreversible operation. |

#### Example

```bash
uip ixp groups delete my-invoices --name Invoice --yes
```

#### Data shape (--output json)

```json
{ "Code": "IxpGroupsDelete", "Data": { "ProjectName": "my-invoices", "Group": "Invoice" } }
```

### uip ixp groups rename

Rename a field group. Preserves all fields and annotations.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | Current field group name. |
| `--new-name <name>` | string | **yes** | New field group name. |

#### Example

```bash
uip ixp groups rename my-invoices --name Invoice --new-name InvoiceHeader
```

#### Data shape (--output json)

```json
{ "Code": "IxpGroupsRename", "Data": { "ProjectName": "my-invoices", "OldName": "Invoice", "NewName": "InvoiceHeader" } }
```

### uip ixp groups update-prompts

Bulk-update field group extraction instructions, matched by group name. Existing fields are preserved.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--updates <json>` | JSON array | **yes** | `[{"name":"<group>","instructions":"..."}]`. Matched by `label_def` name — unmatched names are reported, not errored. |

#### Example

```bash
uip ixp groups update-prompts my-invoices --updates '[{"name":"Invoice","instructions":"Header fields at the top of the document"}]'
```

#### Data shape (--output json)

```json
{
  "Code": "IxpGroupsUpdatePrompts",
  "Data": { "ProjectName": "my-invoices", "GroupsUpdated": 1, "Unmatched": [] }
}
```

## uip ixp fields

Edit fields within a project's field groups (`label_defs`).

### uip ixp fields add

Add a new field to a field group.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--group <name>` | string | **yes** | Field group (`label_def`) name. |
| `--field <name>` | string | **yes** | New field name. |
| `--type <type-name>` | string | **yes** | Field type — name of a data type (`entity_def`) in the project's taxonomy. |
| `--instructions <text>` | string | **yes** | What to extract and where to find it. |

#### Example

```bash
uip ixp fields add my-invoices --group Invoice --field "Due Date" --type Date \
  --instructions "Date payment is due."
```

#### Data shape (--output json)

```json
{
  "Code": "IxpFieldsAdd",
  "Data": { "ProjectName": "my-invoices", "FieldGroup": "Invoice", "Field": "Due Date", "FieldTypeId": "c3f08a1b6d2e4f97" }
}
```

### uip ixp fields delete

Delete a field from a field group.

#### Options

| Short | Long | Value | Required | Description |
|---|---|---|---|---|
| — | `--group <name>` | string | **yes** | Field group name. |
| — | `--field <name>` | string | **yes** | Field name to delete. |
| `-y` | `--yes` | flag | **yes** | Confirm this irreversible operation. |

#### Example

```bash
uip ixp fields delete my-invoices --group Invoice --field 'Due Date' --yes
```

#### Data shape (--output json)

```json
{ "Code": "IxpFieldsDelete", "Data": { "ProjectName": "my-invoices", "FieldGroup": "Invoice", "Field": "Due Date" } }
```

### uip ixp fields rename

Rename a field within a field group.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--group <name>` | string | **yes** | Field group name. |
| `--field <name>` | string | **yes** | Current field name. |
| `--new-name <name>` | string | **yes** | New field name. |

#### Example

```bash
uip ixp fields rename my-invoices --group Invoice --field 'Due Date' --new-name 'Payment Due'
```

#### Data shape (--output json)

```json
{
  "Code": "IxpFieldsRename",
  "Data": { "ProjectName": "my-invoices", "FieldGroup": "Invoice", "OldName": "Due Date", "NewName": "Payment Due" }
}
```

### uip ixp fields change-type

Change a field's type. **Irreversible**: existing annotations for this field are deleted.

#### Options

| Short | Long | Value | Required | Description |
|---|---|---|---|---|
| — | `--group <name>` | string | **yes** | Field group name. |
| — | `--field <name>` | string | **yes** | Field name. |
| — | `--type <type-name>` | string | **yes** | New field type — name of a data type in the project's taxonomy. |
| `-y` | `--yes` | flag | **yes** | Confirm this irreversible operation (deletes the field's annotations). |

#### Example

```bash
uip ixp fields change-type my-invoices --group Invoice --field 'Total' --type Money --yes
```

#### Data shape (--output json)

```json
{
  "Code": "IxpFieldsChangeType",
  "Data": { "ProjectName": "my-invoices", "FieldGroup": "Invoice", "Field": "Total", "NewFieldTypeId": "d9b1740e3a6c2f85" }
}
```

### uip ixp fields update-prompts

Bulk-update per-field extraction instructions, matched by field name across all field groups. Existing field definitions are preserved.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--updates <json>` | JSON array | **yes** | `[{"name":"<field>","instructions":"..."}]`. Matched by field name. |

#### Example

```bash
uip ixp fields update-prompts my-invoices --updates '[{"name":"Invoice Number","instructions":"7-digit numeric ID at top-right"},{"name":"Total","instructions":"Grand total at the bottom"}]'
```

#### Data shape (--output json)

```json
{
  "Code": "IxpFieldsUpdatePrompts",
  "Data": { "ProjectName": "my-invoices", "FieldsUpdated": 2, "Unmatched": [] }
}
```

## Related

- [uip ixp](./uip-ixp.md) — concepts and the full resource directory.
- [uip ixp projects](./uip-ixp-projects.md) — `get-taxonomy`/`import-taxonomy` for moving the whole taxonomy as one artifact.
- [uip ixp documents & labellings](./uip-ixp-documents.md) — the fields/groups defined here get predicted and confirmed there.

## See also

- [IXP tool overview](./uip-ixp.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)