Skip to content

Update a field definition

PATCH
/fields/{id}

Changes the settings of a field definition. Requires the fields.admin or system.admin capability, granted globally. Send only what you want to change: anything left out, or sent as null, keeps its current value.

Some settings can’t be removed by sending null, so they have a matching clear flag: clear_default, clear_edit_tab, clear_regexp_filter and clear_display_condition. A clear flag only acts when it is true; false is ignored. Sending true together with a new value for the same setting is refused. options, applies_to and display_condition replace the stored value whole; nothing is merged. To remove read_capability or write_capability, send an empty string.

To have the server check for someone else’s edit, send the updated_at you last read as if_unchanged_since. If it no longer matches the field’s updated_at, to the microsecond, you get 409 and nothing is written; any other time counts as a mismatch, a later one included. The check is optional and runs just before the write, so two requests sent at the same moment can both pass it.

Changing searchable, or moving the field into or out of active, makes the server try to re-index every asset that has a value in this field before it responds. If that fails, the change is still saved and assets can keep their old searchable text. Search results are also cached for up to a minute, so recent searches can still show earlier results. Other changes don’t rewrite stored values.

The code, type, subject kind and mirrors_column can’t be changed. The extraction source has its own endpoint, PUT /fields/{id}/extraction.

id
required
string format: uuid

The field definition’s id.

The settings to change. Leave out anything you don’t want to change.

object
if_unchanged_since

The updated_at you last read. If it no longer matches the field’s updated_at, to the microsecond, the request is refused with 409 and nothing is written; a later time is a mismatch too. Leave it out to skip the check. It catches edits made since your last read, but two requests sent at the same moment can both pass it.

string format: date-time
label

New name shown to people. Unlike on create, it isn’t trimmed or checked for a blank value here, and the limits shown aren’t checked.

string
>= 1 characters <= 200 characters
description

New longer explanation. An empty string removes it.

string
options

The complete new options document. It replaces the stored one and nothing is merged, so include every term you want to keep. The format and checks are the same as for options in the response.

To retire a term, change its status instead of removing it. The server doesn’t stop you removing a term that stored values still use.

object
key
additional properties
any
open_vocabulary

Turn on or off adding new terms when values are saved. Only multi_select fields use it.

boolean
show_on_card

Show or hide the field on asset cards. Refused with 400 if the field would end up with both this and a read_capability.

boolean
show_in_advanced_search

Offer the field on the advanced search page, or stop offering it. Doesn’t change search results.

boolean
show_on_upload

Offer the field on upload and create forms, or stop offering it.

boolean
edit_tab

Move the field to this edit tab. Spaces around the name are trimmed and a blank name is refused; to remove the tab, use clear_edit_tab.

string
nullable
clear_edit_tab

Send true to remove the field’s edit tab; false is ignored. true can’t be combined with edit_tab.

boolean
display_condition

Replace the field’s display condition with this list of terms. The whole list is replaced. An empty list or a blank term is refused; use clear_display_condition to remove the condition. See display_condition in the response for how terms work.

The condition is checked when you save, and refused with 400 if:

  • a term doesn’t parse, or uses an operator the other field’s type doesn’t take;
  • a term names a field this server doesn’t have, a field of the other subject kind, an archived field, a mirrored field, or this field itself;
  • the terms would make fields depend on each other in a loop, directly or through other fields;
  • for an asset field, no asset type is shared by this field and every field the terms name (an empty applies_to counts as every type);
  • one single-value field would have to equal two different values.

A field with mirrors_column can’t have a condition. The checks run only when the condition is saved. Later changes to the other fields, such as archiving one, don’t revisit it.

Array<string>
clear_display_condition

Send true to remove the field’s display condition, so the field is always offered; false is ignored. true can’t be combined with display_condition. Always allowed, even on a field that couldn’t have a condition set now.

boolean
read_only

Turn the read-only rule on or off. A field with mirrors_column can’t be made read-only.

boolean
regexp_filter

Set the input pattern. See regexp_filter in the response for the syntax. Refused with 400 if the pattern is an empty string (use clear_regexp_filter instead), doesn’t compile, or the field isn’t text or longtext or has mirrors_column. A pattern of only spaces is valid and is kept as sent.

string
clear_regexp_filter

Send true to remove the input pattern; false is ignored. true can’t be combined with regexp_filter. Always allowed, on any field.

boolean
required

Turn the required rule on or off.

boolean
searchable

Include or exclude this field’s values from full-text search. The server tries to re-index the affected assets before it responds; the operation description gives the limits.

boolean
applies_to

The complete new list of asset type refs. It replaces the stored list; an empty list means every type.

Array<integer>
read_capability

New read capability. An empty string removes it. Refused if the field is shown on cards.

string
nullable
write_capability

New write capability. An empty string removes it.

string
nullable
display_order

New sort position within the display group.

integer
display_group

New display group name.

string
status

Change the field’s status. archived retires it, as DELETE /fields/{id} does, and active brings an archived or deprecated field back.

string
Allowed values: active deprecated archived
deprecated_replacement_id

Id of the field that replaces this one. It must be an existing field. Once set, it can be changed but not removed.

string format: uuid
nullable
default_value

Set the upload default. Asset fields only. It is checked against the field’s type and, for vocabulary fields, against the options this request saves, or the stored options if the request doesn’t change them. Use clear_default to remove the default.

object
kind
required

literal for a fixed value, context for one the server fills in when the asset is created.

string
Allowed values: literal context
value_text

The literal value for text, longtext, rich_text, select and tree fields. For select and tree, an active slug.

string
nullable
value_num

The literal value for number and boolean fields. A boolean is 1 or 0.

number
nullable
value_date

The literal value for date and datetime fields.

string format: date-time
nullable
value_options

The literal value for multi_select fields: active slugs.

Array<string>
nullable
value_ref

The literal value for reference fields: an asset id.

string format: uuid
nullable
context

Required when kind is context, and not allowed otherwise. The server fills in the value when the asset is created:

  • uploading_user: the uploader’s full name from their account, or their username if no full name is set. Use it on text fields.
  • uploading_team: the name of the uploader’s team. Use it on text fields. Skipped when the uploader belongs to no team or to more than one.
  • current_date: the creation time, for date and datetime fields. A date field gets the day (UTC), a datetime field the exact time.

These three are the only choices.

string
Allowed values: uploading_user uploading_team current_date
clear_default

Send true to remove the upload default; false is ignored. true can’t be combined with default_value.

boolean

The field definition after the change.

object
id
required

The field’s id, used in the /fields/{id} routes.

string format: uuid
code
required

The field’s stable identifier, such as color_space. It is unique among all field definitions on this server, archived ones included, and can’t be changed after the field is created.

string
label
required

The name shown to people.

string
description

A longer explanation of the field. An empty string when none was given.

string
type
required

The kind of value the field holds. It can’t be changed after the field is created.

string
Allowed values: text longtext rich_text number boolean date datetime select multi_select tree reference
subject_kind
required

Whether the field describes individual assets or whole collections. A definition is one or the other; to have a field on both, create two definitions.

string
Allowed values: asset collection
options

Type-specific settings. For select, multi_select and tree fields this holds the vocabulary as {"values": [...]}, where each entry is either a slug string or an object {value, label?, status?, replaced_by?, aliases?, children?}:

  • value is the slug stored on records. Slugs are trimmed and must be unique across the whole document, including nested terms.
  • status is active (the default), deprecated or archived. Don’t offer deprecated or archived terms for new values. Deprecated terms still display on records that have them.
  • replaced_by names another slug in the same field. An archived term with replaced_by works as a merge: a value that names it is stored as the replacement.
  • aliases are other spellings that lead to the term when a value is written. They are stored in lowercase and must not clash with any slug, label or alias in the field. Adding or removing an alias doesn’t change stored values.
  • children nests terms. It is what makes a tree field hierarchical; a stored value is still a single slug.

Documents without values, and other keys, are stored as sent. To offer terms in a form, use GET /fields/{id}/values rather than reading this document, which can be large.

object
key
additional properties
any
open_vocabulary

When true, saving a value with a term the field doesn’t have yet adds the term: the text becomes its label and a slug is made from it. People need the fields.vocabulary.extend capability to add terms this way, and metadata extraction can add them too. When false, the default, an unknown term is refused with 422.

Terms are matched by slug or label, ignoring case and any spaces at either end, so Character and character name the same term. Only multi_select fields use this setting.

boolean
required
required

When true, people can’t save an empty value or remove the value once one is set. Uploading an asset doesn’t require it, but creating a collection does require a value for each required collection field. Upload defaults and metadata extraction aren’t affected.

boolean
searchable
required

Include this field’s values in full-text search. True by default. Only values of active asset fields are indexed.

Turning it off takes the field out of the search index only. A field: filter on the field still works, and whether the advanced search page offers the field as a filter is a separate setting, show_in_advanced_search.

boolean
applies_to
required

Asset type refs this field applies to. An empty list means every asset type. Collection fields don’t use it.

Array<integer>
read_capability

Capability someone needs to read this field’s current values. null or an empty string means no capability is needed. It doesn’t hide the definition itself, and the value-history routes, GET /assets/{id}/fields/{field_id}/history and GET /collections/{id}/fields/{field_id}/history, don’t check it, so earlier values stay readable there.

string
nullable
write_capability

Capability someone needs to change this field’s values. null or an empty string means no extra capability is needed.

string
nullable
display_order
required

Sort position within the display group. Lower numbers come first.

integer
display_group
required

Name of the group the field is shown in, such as general.

string
extraction_source

Name of the extracted value that fills this field, such as capture_datetime. An empty string means the field isn’t filled by extraction. Set it with PUT /fields/{id}/extraction.

string
extraction_mode

How extracted values are applied. skip_if_set fills the field only when it is empty or still holds its upload default; a value set any other way, by a person, an import or an earlier extraction, is left alone. replace overwrites the current value whenever the file has one. append and prepend are accepted but currently work the same as replace.

string
Allowed values: "" skip_if_set replace append prepend
show_on_card

Show this field’s value on asset cards in browse views. It is a display hint only and controls no access, filtering or search.

A field with a read_capability can’t be shown on cards, because cards are drawn without checking per-field capabilities. A request that would leave a field with both is refused with 400.

boolean
show_in_advanced_search

Offer this field as a filter on the advanced search page. True by default. It only decides whether the page shows a control: it doesn’t change search results, and a field: filter on the field works either way. People who can’t read the field’s values can’t filter on it whatever this says.

boolean
show_on_upload

Offer this field on upload and create forms. True by default. It is a hint for forms, not an access rule: hiding a field from a form doesn’t stop its values being set through PUT /assets/{id}/fields/{field_id}.

boolean
edit_tab

The edit-form tab this field belongs to, or null for none. Tabs group fields more coarsely than display_group. A blank tab name is refused; to remove the tab, use clear_edit_tab on PATCH /fields/{id}.

string
nullable
read_only

When true, people can’t set or clear this field’s values through the API, whatever capabilities they hold. Values already stored are kept.

The server’s own writers still fill the field: upload defaults and metadata extraction. For a collection field, a value given when the collection is created is also accepted. A field with mirrors_column can’t be made read-only.

boolean
regexp_filter

A pattern that values people enter must match, or null for none. It uses Go RE2 syntax and always matches the whole value, so don’t add ^ or $: a|b means the whole value is a or b. The pattern is stored exactly as sent, spaces included.

Only text and longtext fields can have one, and not fields with mirrors_column. It checks new input only: stored values aren’t rechecked when the pattern changes, and upload defaults and metadata extraction aren’t held to it.

string
nullable
mirrors_column

When set, this field has no storage of its own: it reads and writes that column of the asset, title or description. null means an ordinary field.

Writing a mirrored field changes the asset, so it needs the same permission as editing the asset. Forms that already show the title or description should skip the mirrored field. This setting can’t be changed through the API.

string
nullable
display_condition

When to offer this field in forms: a list of terms that must all be true, or null to always offer it. Each term is <code><operator><value> and names another field of the same subject kind, such as work_type=commission.

  • = compares the stored value exactly, including case. On a multi_select field it checks whether the term is one of the selected values.
  • ~ checks whether the stored value contains the text, ignoring case.
  • text and longtext fields take = and ~; select, tree and multi_select fields take =. Other types can’t be used in a condition.

Spaces around the code and value in a term are ignored; the stored value is compared as it is.

This is a form hint, not access control. A hidden field keeps its values and can still be written through PUT /assets/{id}/fields/{field_id}, and hiding a field never clears it. If any term can’t be evaluated, for example because the other field is missing, archived or not readable by the person using the form, the whole condition is ignored and the field is shown. A readable field with no value counts as false.

Set it with display_condition on PATCH /fields/{id} and remove it with clear_display_condition. It can’t be set when a field is created.

Array<string>
nullable
status
required

active fields are offered for new values. deprecated fields still show and keep their values but shouldn’t be offered for new ones. archived fields are retired: left out of field lists and forms by default, but kept with their values. Only active fields count in full-text search and field: filters.

string
Allowed values: active deprecated archived
deprecated_replacement_id

The field that replaces this one, if any. For information only.

string format: uuid
nullable
default_value

Upload default: the value a new asset gets for this field when nothing else sets it, or null for none. Only active asset fields use it, and only on asset types the field applies to. A team can override it for its own uploads through /fields/{id}/default-overrides. Metadata extraction can replace a default value later.

object
kind
required

literal for a fixed value, context for one the server fills in when the asset is created.

string
Allowed values: literal context
value_text

The literal value for text, longtext, rich_text, select and tree fields. For select and tree, an active slug.

string
nullable
value_num

The literal value for number and boolean fields. A boolean is 1 or 0.

number
nullable
value_date

The literal value for date and datetime fields.

string format: date-time
nullable
value_options

The literal value for multi_select fields: active slugs.

Array<string>
nullable
value_ref

The literal value for reference fields: an asset id.

string format: uuid
nullable
context

Required when kind is context, and not allowed otherwise. The server fills in the value when the asset is created:

  • uploading_user: the uploader’s full name from their account, or their username if no full name is set. Use it on text fields.
  • uploading_team: the name of the uploader’s team. Use it on text fields. Skipped when the uploader belongs to no team or to more than one.
  • current_date: the creation time, for date and datetime fields. A date field gets the day (UTC), a datetime field the exact time.

These three are the only choices.

string
Allowed values: uploading_user uploading_team current_date
created_at
required

When the definition was created.

string format: date-time
updated_at
required

When the definition last changed. Send it as if_unchanged_since on PATCH /fields/{id} to have the update refused if the field has changed since; that check has limits, described there.

string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The if_unchanged_since time you sent doesn’t match the field’s updated_at. Nothing was written; updated_at in the body is the field’s current value.

Returned with 409 when the item changed after the version you sent.

object
error
required

A short explanation.

string
updated_at
required

The item’s current updated_at.

string format: date-time