> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/business-data-repository/api-reference/custom-fields.md).
# Custom fields
Type definitions for custom field definitions, including field types, params, options, filter inputs, and the patch input used in asset and geo object mutations.
{% hint style="warning" %}
**Navixy GraphQL API is a work in progress.** This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
{% endhint %}
Custom field definitions allow extending entities with workspace-specific data fields.
## Queries
### customFieldTypes
Lists the custom-field types that may be defined on the given owner catalog item, together with what a `REFERENCE` field defined there may point at. Creating a definition with a type absent from this list fails with `VALIDATION_ERROR` on `input.fieldType`.
Returns an empty list for any catalog item whose instances cannot carry custom fields. The owners that can are the ones whose instances implement `Customizable` — `AssetType` and `GeoObjectType`.
```graphql
customFieldTypes(ownerTypeId: ID!): [FieldTypeAvailability!]!
```
**Arguments**
| Name | Type | Description |
| ------------- | ----- | ----------------------------------------------------------------- |
| `ownerTypeId` | `ID!` | The owner catalog item — the type the fields would be defined on. |
**Output types:**
FieldTypeAvailability
One custom-field type that may be defined on a given owner, and what it may point at.
| Field | Type | Description |
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fieldType` | [FieldType](#fieldtype)! | The field type. |
| `referenceableEntityTypes` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!]! | Entity type codes a `REFERENCE` field on this owner may point at, as accepted by `ReferenceFieldParamsInput.refEntityTypeCode`. Empty for every other field type. |
***
## Objects
### DeviceCustomFieldValue
DEVICE custom-field value (primary-capable).
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity. |
| `device` | [Device](/docs/navixy-graphql-api/business-data-repository/api-reference/devices.md#device)! | The linked device. |
| `isPrimary` | `Boolean!` | Whether this device is the entity's primary DEVICE. |
***
### FieldParamsDevice
Parameters for DEVICE field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `refSubtypes` | \[[CatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitem)]! | The device types a value may belong to. Empty means any device type is allowed. An element is null when the device type behind it no longer resolves — see `FieldParamsReference.refSubtypes`, which is resolved by the same loader. |
***
### FieldParamsReference
Parameters for REFERENCE field type.
**Implements:** [FieldParams](#fieldparams), [MultiValue](/docs/navixy-graphql-api/core-api-reference/common.md#multivalue)
| Field | Type | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `isMulti` | `Boolean!` | Whether multiple values can be selected for this field. |
| `refEntityTypeCode` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The entity type code that can be referenced. |
| `refSubtypes` | \[[CatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitem)]! | The subtypes a value may belong to (AssetType / GeoObjectType / catalog). Empty means the whole target type is allowed. An element is null when its subtype no longer resolves — the classifier item was deleted after the narrowing was validated on write. Nullable for the same reason as `defaultRefs` below: both are resolved while `FieldParams!` itself is built, so a non-null element type would let one dangling subtype blank an entire page of catalog types, even for a query that never selects this field. |
| `defaultRefs` | \[[Node](/docs/navixy-graphql-api/core-api-reference/common.md#node)]! | The default referenced entities. Empty when the field has no default. An element is null when its target no longer resolves — the entity was deleted after the default was validated on write. Nullable for the same reason as `ReferenceCustomFieldValue.refs`: `FieldParams!` is non-null on `CustomFieldDefinition!` inside a non-null `customFieldDefinitions` list, so a non-null element type would let one dangling default blank an entire page of catalog types. |
***
### StringCustomFieldValue
STRING / TEXT custom-field value.
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `value` | `String!` | |
***
### DecimalCustomFieldValue
DECIMAL custom-field value (arbitrary precision, string-encoded).
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `value` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal)! | |
***
### IntegerCustomFieldValue
INTEGER custom-field value (signed 64-bit).
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `value` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | |
***
### BooleanCustomFieldValue
BOOLEAN custom-field value.
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `value` | `Boolean!` | |
***
### DateCustomFieldValue
DATE custom-field value.
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `value` | [Date](/docs/navixy-graphql-api/core-api-reference/common.md#date)! | |
***
### DateTimeCustomFieldValue
DATETIME custom-field value.
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `value` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | |
***
### GeoJsonCustomFieldValue
GEOJSON custom-field value.
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `value` | [GeoJSON](/docs/navixy-graphql-api/core-api-reference/common.md#geojson)! | |
***
### OptionsCustomFieldValue
OPTIONS custom-field value (one or more option codes).
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
| `values` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!]! | |
***
### ReferenceCustomFieldValue
REFERENCE custom-field value (one or more referenced entities; primary-capable).
**Implements:** [CustomFieldValue](#customfieldvalue)
| Field | Type | Description |
| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity. |
| `refs` | \[[Node](/docs/navixy-graphql-api/core-api-reference/common.md#node)]! | The referenced entities, in stored order. Select concrete fields with inline fragments. A single-value field returns a one-element list. An element is null when its target no longer resolves — the referenced entity was deleted while the reference stayed behind. The slot is kept so stored order still lines up with the other elements. Nullable on purpose: with a non-null element type one deleted target would null the whole holder, and inside a connection the whole page of results with it. |
| `isPrimary` | `Boolean!` | Whether this reference is the entity's primary REFERENCE. |
***
### CustomFieldDefinition
A custom field definition that specifies the metadata for a custom field.
{% hint style="warning" %}
The `fieldType` property is immutable after creation. To change the field type, delete the definition and create a new one.
{% endhint %}
Titled but not a `Node`: a definition is embedded in its owning catalog item and addressed through it, never by an id of its own. Within its owner it is identified by `code`.
**Implements:** [Titled](/docs/navixy-graphql-api/core-api-reference/common.md#titled)
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title` | `String!` | The human-readable display name. |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The machine-readable code, unique per owner and workspace. Always starts with `cf_`. |
| `description` | `String` | A description of the field for UI hints. |
| `order` | `Int!` | The display order within the owner context. |
| `fieldType` | [FieldType](#fieldtype)! | The data type determining validation rules and UI rendering. This property is immutable and cannot be changed after creation. |
| `params` | [FieldParams](#fieldparams)! | The type-specific parameters for validation, defaults, and options. |
| `isDefault` | `Boolean!` | Whether the field is on by default for every entity of the owning type. An individual entity can override it on its value. |
| `isArchived` | `Boolean!` | Whether this field definition is archived. Archived fields preserve existing values but no longer appear in forms and accept no new input. Use the `archive` / `restore` actions in the parent catalog item's `customFieldDefinitions` input to toggle this state. |
***
### FieldTypeAvailability
One custom-field type that may be defined on a given owner, and what it may point at.
| Field | Type | Description |
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fieldType` | [FieldType](#fieldtype)! | The field type. |
| `referenceableEntityTypes` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!]! | Entity type codes a `REFERENCE` field on this owner may point at, as accepted by `ReferenceFieldParamsInput.refEntityTypeCode`. Empty for every other field type. |
***
### FieldParamsString
Parameters for STRING field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| --------------- | ---------- | ------------------------------------------------ |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `minLength` | `Int` | The minimum character length. |
| `maxLength` | `Int` | The maximum character length. |
| `defaultString` | `String` | The default value. |
| `trim` | `Boolean!` | Whether to trim leading and trailing whitespace. |
***
### FieldParamsText
Parameters for TEXT field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| ------------- | ---------- | ------------------------------------------------ |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `maxLength` | `Int` | The maximum character length. |
| `defaultText` | `String` | The default value. |
| `trim` | `Boolean!` | Whether to trim leading and trailing whitespace. |
***
### FieldParamsDecimal
Parameters for DECIMAL field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `minDecimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | The minimum allowed value. |
| `maxDecimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | The maximum allowed value. |
| `scale` | `Int!` | Digits after the decimal point. Must be >= 0. Values sent with more fractional digits than `scale` are rounded using HALF\_UP before storage. |
| `defaultDecimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | The default value. |
***
### FieldParamsInteger
Parameters for INTEGER field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------ | ------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `minInteger` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | The minimum allowed value. |
| `maxInteger` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | The maximum allowed value. |
| `defaultInteger` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | The default value. |
***
### FieldParamsBoolean
Parameters for BOOLEAN field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| ---------------- | ---------- | ------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `defaultBoolean` | `Boolean` | The default value. |
***
### FieldParamsDate
Parameters for DATE field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------ | ------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `defaultDate` | [Date](/docs/navixy-graphql-api/core-api-reference/common.md#date) | The default value. |
***
### FieldParamsDatetime
Parameters for DATETIME field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| ----------------- | -------------------------------------------------------------------------- | ------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `defaultDatetime` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | The default value. |
***
### FieldParamsGeojson
Parameters for GEOJSON field type.
**Implements:** [FieldParams](#fieldparams)
| Field | Type | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `allowedTypes` | \[[GeoJsonGeometryType](/docs/navixy-graphql-api/business-data-repository/api-reference/geo-objects.md#geojsongeometrytype)!] | The allowed geometry types. Null means all types are allowed. |
***
### FieldParamsOptions
Parameters for OPTIONS field type.
**Implements:** [FieldParams](#fieldparams), [MultiValue](/docs/navixy-graphql-api/core-api-reference/common.md#multivalue)
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
| `isMulti` | `Boolean!` | Whether multiple values can be selected for this field. |
| `options` | \[[FieldOption](#fieldoption)!]! | The available options to choose from. |
| `defaultOptions` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | The default option code. |
***
### FieldOption
A single option in an OPTIONS field.
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The unique code for this option within the field. |
| `label` | `String!` | The display label. |
| `description` | `String` | A description of the option. |
| `isArchived` | `Boolean!` | Whether this option is archived and should not be shown for new selections. |
***
## Inputs
### CustomFieldFilterValue
Typed filter value for custom fields. Exactly one field must be set (`@oneOf`). Choose the variant that matches the custom field's data type:
| FieldType | Variant | Example |
| ----------------- | ------------ | -------------------------------------- |
| STRING, TEXT | `string` | `{ string: "hello" }` |
| DECIMAL | `decimal` | `{ decimal: "42.50" }` |
| INTEGER | `integer` | `{ integer: 42 }` |
| BOOLEAN | `boolean` | `{ boolean: true }` |
| DATE | `date` | `{ date: "2024-01-15" }` |
| DATETIME | `datetime` | `{ datetime: "2024-01-15T10:30:00Z" }` |
| OPTIONS | `string` | `{ string: "option_code" }` |
| DEVICE, REFERENCE | `id` | `{ id: "019a6a3f-..." }` |
| (IN operator) | `stringList` | `{ stringList: ["a", "b"] }` |
| (IN operator) | `idList` | `{ idList: ["uuid1", "uuid2"] }` |
*This input type uses `@oneOf` - exactly one field must be provided.*
| Field | Type | Description |
| ------------ | -------------------------------------------------------------------------- | --------------------------------------------------------- |
| `string` | `String` | String value — for STRING, TEXT, OPTIONS fields. |
| `decimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | Arbitrary-precision decimal value — for DECIMAL fields. |
| `integer` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | Signed 64-bit integer value — for INTEGER fields. |
| `boolean` | `Boolean` | Boolean value — for BOOLEAN fields. |
| `date` | [Date](/docs/navixy-graphql-api/core-api-reference/common.md#date) | Date value — for DATE fields. |
| `datetime` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | Date-time value — for DATETIME fields. |
| `id` | `ID` | ID value — for DEVICE, REFERENCE fields. |
| `stringList` | `[String!]` | List of strings — for IN operator on string-based fields. |
| `idList` | `[ID!]` | List of IDs — for IN operator on reference fields. |
***
### CustomFieldFilter
A filter condition for a custom field value.
One condition is one code compared one way. Where a filter input takes a LIST of these (`AssetFilter.customFields`, `GeoObjectFilter.customFields`), the entries combine with AND — an entity must satisfy every one of them, and repeating a code narrows rather than widens.
Inside a single condition:
* `IN` matches when the stored value equals ANY member of the list — the list itself is an OR.
* On a multi-value field (`isMulti` OPTIONS / REFERENCE), a positive operator matches when ANY stored value satisfies it: `["red","blue"]` matches `{operator: EQ, value: {string: "red"}}`. `NE` and `IS_NULL` are the inversions of that, so they match only when NO stored value qualifies — `NE "red"` does not match `["red","blue"]`.
* A code with no field definition behind it is treated as SQL NULL: `IS_NULL` and `NE` match every entity, every other operator matches none.
| Field | Type | Description |
| ---------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code to filter by. |
| `operator` | [FieldOperator](#fieldoperator)! | The comparison operator. |
| `value` | [CustomFieldFilterValue](#customfieldfiltervalue) | The value to compare against. Null for `IS_NULL` and `IS_NOT_NULL` operators. |
***
### CustomFieldsPatchInput
Input for updating custom field values using a patch model.
`set` provides typed values (create/overwrite); `unset` removes fields by code. Primary status travels with the value on the primary-capable variants (DEVICE/REFERENCE) via their required `isPrimary` flag — there is no separate setPrimary/unsetPrimary list.
| Field | Type | Description |
| ------- | ---------------------------------------------------------------------- | --------------------------------- |
| `set` | \[[CustomFieldValueInput](#customfieldvalueinput)!] | Field values to set or overwrite. |
| `unset` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!] | Field codes to remove entirely. |
***
### CustomFieldValueInput
A single custom-field value to set, addressed by code.
Omitting `value` is the same as passing null, so an entry clears the field unless it carries one. An `isDefault` override cannot be changed on its own: send the current value alongside it.
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `value` | [CustomFieldValueDataInput](#customfieldvaluedatainput) | The typed value. Null clears the field but keeps the key (distinct from `unset`). |
| `isDefault` | `Boolean` | Overrides the definition's `isDefault` for this entity, in either direction. Omit to leave any existing override untouched; the override is dropped when the field is `unset` or its value is cleared. |
***
### CustomFieldValueDataInput
Typed custom-field value. Exactly one variant must be set (`@oneOf`), matching the custom field's declared FieldType:
| FieldType | Variant |
| ------------------ | ------------ |
| STRING, TEXT | `string` |
| DECIMAL | `decimal` |
| INTEGER | `integer` |
| BOOLEAN | `boolean` |
| DATE | `date` |
| DATETIME | `datetime` |
| GEOJSON | `geojson` |
| DEVICE | `device` |
| REFERENCE (single) | `reference` |
| REFERENCE (multi) | `references` |
| OPTIONS (single) | `option` |
| OPTIONS (multi) | `options` |
*This input type uses `@oneOf` - exactly one field must be provided.*
| Field | Type | Description |
| ------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `string` | `String` | STRING / TEXT value. |
| `decimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | DECIMAL value (arbitrary precision, string-encoded). |
| `integer` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | INTEGER value (signed 64-bit). |
| `boolean` | `Boolean` | BOOLEAN value. |
| `date` | [Date](/docs/navixy-graphql-api/core-api-reference/common.md#date) | DATE value. |
| `datetime` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | DATETIME value. |
| `geojson` | [GeoJSON](/docs/navixy-graphql-api/core-api-reference/common.md#geojson) | GEOJSON value. |
| `device` | [DeviceValueInput](#devicevalueinput) | DEVICE value (primary-capable). |
| `reference` | [ReferenceValueInput](#referencevalueinput) | REFERENCE value for a single-value field (primary-capable). |
| `references` | [ReferenceListValueInput](#referencelistvalueinput) | REFERENCE value for an isMulti field (primary-capable). |
| `option` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | OPTIONS value for a single-value field. |
| `options` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!] | OPTIONS value for an isMulti field. |
***
### DeviceValueInput
DEVICE custom-field value.
| Field | Type | Description |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `ID!` | The device to assign. |
| `isPrimary` | `Boolean!` | Whether this device is the entity's primary DEVICE. Required — prevents silent demotion. |
| `reassign` | `Boolean` | If the device is already assigned to another asset, detach it there and reassign it here, atomically, instead of failing with VALIDATION\_ERROR. Asset holders only. A DEVICE field may only be defined on an AssetType since v0.7.0, but definitions written before it stay live, and on such a field `reassign: true` is rejected with VALIDATION\_ERROR naming it: only an asset holds a device exclusively, so there is nothing to detach it from. |
***
### ReferenceValueInput
REFERENCE custom-field value for a single-value field.
| Field | Type | Description |
| ----------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The referenced entity ID. |
| `isPrimary` | `Boolean!` | Whether this reference is the entity's primary REFERENCE. Required — prevents silent demotion. |
***
### ReferenceListValueInput
REFERENCE custom-field value for an isMulti field.
| Field | Type | Description |
| ----------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `ids` | `[ID!]!` | The referenced entity IDs, in the order they are stored. |
| `isPrimary` | `Boolean!` | Whether this reference is the entity's primary REFERENCE. Required — prevents silent demotion. |
***
### CustomFieldDefinitionInput
A single operation on a custom field definition within the parent catalog item. Exactly one action must be provided.
*This input type uses `@oneOf` - exactly one field must be provided.*
| Field | Type | Description |
| --------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `create` | [CustomFieldDefinitionCreateData](#customfielddefinitioncreatedata) | Create a new custom field definition. |
| `update` | [CustomFieldDefinitionUpdateData](#customfielddefinitionupdatedata) | Update an existing custom field definition. |
| `delete` | [CustomFieldDefinitionDeleteData](#customfielddefinitiondeletedata) | Delete a custom field definition. |
| `archive` | [CustomFieldDefinitionArchiveData](#customfielddefinitionarchivedata) | Archive a custom field definition (non-destructive deactivation). |
| `restore` | [CustomFieldDefinitionRestoreData](#customfielddefinitionrestoredata) | Restore a previously archived custom field definition. |
***
### CustomFieldDefinitionCreateData
Data for creating a custom field definition within its parent catalog item.
A type carries at most **50 active** definitions, and at most **100 in total** — active and archived together. Archiving a field frees an active slot but not a total one: an archived definition accepts no new values, so it cannot grow, but it keeps its row and the values already stored under it, and only `delete` releases that. System-level fields owned by the entity type rather than by the type, such as the platform's own `geojson_data`, sit in a separate scope and never reduce either allowance. A type belongs to exactly one workspace, so the allowances are per type.
Neither bound is expressible in the schema and both are enforced by the server: a `create` past either is rejected with `VALIDATION_ERROR`, naming the total bound when both are reached, since that is the one archiving cannot resolve. Since the commands in one `customFieldDefinitions` list share a transaction, a batch that crosses a bound is rejected whole — it does not fill the type to the limit and stop.
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | The machine-readable code. Must start with `cf_`, so a custom-field code can never be confused with an entity's own field name. Auto-generated from the title if omitted, prefix included. The prefix also keeps this input clear of the platform's own reserved code `geojson_data`. |
| `title` | `String!` | The display name. |
| `description` | `String` | The description. |
| `fieldType` | [FieldType](#fieldtype)! | The data type. Immutable after creation. |
| `order` | `Int` | The display order. Auto-calculated as last position if omitted. |
| `params` | [FieldParamsInput](#fieldparamsinput)! | The type-specific parameters. Exactly one variant must be provided. |
| `isDefault` | `Boolean` | Whether the field is on by default for entities of this type. Defaults to false. |
***
### CustomFieldDefinitionUpdateData
Data for updating an existing custom field definition. Note: `fieldType` cannot be changed.
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The code of the field definition to update. |
| `title` | `String` | The new display name. |
| `description` | `String` | The new description. |
| `order` | `Int` | The new display order. |
| `params` | [FieldParamsInput](#fieldparamsinput) | The updated parameters. Only `isRequired` and type-specific fields can be changed. |
| `isDefault` | `Boolean` | The new type-level default. Omit to leave unchanged. |
***
### CustomFieldDefinitionDeleteData
Data for permanently deleting a custom field definition.
If entities have values for this field, the default behavior is to reject the deletion. Use `onValues: CASCADE` to explicitly allow deletion with all associated values.
Prefer archiving for non-destructive deactivation.
| Field | Type | Description |
| ---------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The code of the field definition to delete. |
| `onValues` | [CustomFieldDefinitionDeleteBehavior](#customfielddefinitiondeletebehavior) | What to do when existing entities have values for this field. Defaults to `REJECT` to prevent accidental data loss. |
***
### CustomFieldDefinitionArchiveData
Data for archiving or restoring a custom field definition.
Archiving deactivates the field without data loss:
* The field definition and all its values are preserved.
* The field no longer appears in forms and accepts no new values.
* Existing values remain readable and visible in history/exports.
| Field | Type | Description |
| ------ | ------------------------------------------------------------------- | -------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The code of the field definition to archive. |
***
### CustomFieldDefinitionRestoreData
Data for restoring a previously archived custom field definition.
Restoring makes the field active again, so it is refused with `VALIDATION_ERROR` when the type is already at the **active** limit stated on `CustomFieldDefinitionCreateData` — otherwise archiving would be a way around that limit. The total limit never refuses a restore: the row already exists and is already counted, so restoring moves it between the two buckets without adding to the total. Restoring a definition that is already active is never refused either, since it adds no field to the type; it still bumps the definition's `version`.
| Field | Type | Description |
| ------ | ------------------------------------------------------------------- | -------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The code of the field definition to restore. |
***
### FieldParamsInput
Field parameters input. Exactly one field must be provided.
{% hint style="warning" %}
This input type uses `@oneOf` - exactly one field must be provided.
{% endhint %}
| Field | Type | Description |
| ----------- | ------------------------------------------------------- | ------------------------------------ |
| `string` | [StringFieldParamsInput](#stringfieldparamsinput) | Parameters for STRING field type. |
| `text` | [TextFieldParamsInput](#textfieldparamsinput) | Parameters for TEXT field type. |
| `decimal` | [DecimalFieldParamsInput](#decimalfieldparamsinput) | Parameters for DECIMAL field type. |
| `integer` | [IntegerFieldParamsInput](#integerfieldparamsinput) | Parameters for INTEGER field type. |
| `boolean` | [BooleanFieldParamsInput](#booleanfieldparamsinput) | Parameters for BOOLEAN field type. |
| `date` | [DateFieldParamsInput](#datefieldparamsinput) | Parameters for DATE field type. |
| `datetime` | [DateTimeFieldParamsInput](#datetimefieldparamsinput) | Parameters for DATETIME field type. |
| `geojson` | [GeoJsonFieldParamsInput](#geojsonfieldparamsinput) | Parameters for GEOJSON field type. |
| `options` | [OptionsFieldParamsInput](#optionsfieldparamsinput) | Parameters for OPTIONS field type. |
| `device` | [DeviceFieldParamsInput](#devicefieldparamsinput) | Parameters for DEVICE field type. |
| `reference` | [ReferenceFieldParamsInput](#referencefieldparamsinput) | Parameters for REFERENCE field type. |
***
### StringFieldParamsInput
Parameters for STRING field type.
| Field | Type | Description |
| --------------- | ---------- | --------------------------------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `minLength` | `Int` | The minimum character length. |
| `maxLength` | `Int` | The maximum character length. Narrows the `FieldType.STRING` limit; it cannot raise it. |
| `defaultString` | `String` | The default value. |
| `trim` | `Boolean` | Whether to trim whitespace. |
***
### TextFieldParamsInput
Parameters for TEXT field type.
| Field | Type | Description |
| ------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `maxLength` | `Int` | The maximum character length. Narrows the `FieldType.TEXT` limit of 65,535; it cannot raise it. |
| `defaultText` | `String` | The default value. |
| `trim` | `Boolean` | Whether to trim whitespace. |
***
### DecimalFieldParamsInput
Parameters for DECIMAL field type.
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `minDecimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | The minimum allowed value. |
| `maxDecimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | The maximum allowed value. |
| `scale` | `Int!` | Digits after the decimal point. Must be >= 0. Values sent with more fractional digits than `scale` are rounded using HALF\_UP before storage. |
| `defaultDecimal` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal) | The default value. |
***
### IntegerFieldParamsInput
Parameters for INTEGER field type.
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------ | ---------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `minInteger` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | The minimum allowed value. |
| `maxInteger` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | The maximum allowed value. |
| `defaultInteger` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | The default value. |
***
### BooleanFieldParamsInput
Parameters for BOOLEAN field type.
| Field | Type | Description |
| ---------------- | ---------- | ---------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `defaultBoolean` | `Boolean` | The default value. |
***
### DateFieldParamsInput
Parameters for DATE field type.
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------ | ---------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `defaultDate` | [Date](/docs/navixy-graphql-api/core-api-reference/common.md#date) | The default value. |
***
### DateTimeFieldParamsInput
Parameters for DATETIME field type.
| Field | Type | Description |
| ----------------- | -------------------------------------------------------------------------- | ---------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `defaultDatetime` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | The default value. |
***
### GeoJsonFieldParamsInput
Parameters for GEOJSON field type.
| Field | Type | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `allowedTypes` | \[[GeoJsonGeometryType](/docs/navixy-graphql-api/business-data-repository/api-reference/geo-objects.md#geojsongeometrytype)!] | The allowed geometry types. Null means all types are allowed. |
***
### OptionsFieldParamsInput
Parameters for OPTIONS field type.
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------ | ----------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `isMulti` | `Boolean` | Whether multiple options can be selected. |
| `options` | \[[FieldOptionInput](#fieldoptioninput)!]! | The available options. |
| `defaultOptions` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | The default option code. |
***
### FieldOptionInput
Input for an option definition. When updating options: if an entry without `code` is provided, a new option is created. If the label already exists within this field, an error is returned.
| Field | Type | Description |
| ------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | The unique code. Auto-generated from label if omitted. |
| `label` | `String!` | The display label. Must be unique within the custom field. |
| `description` | `String` | The description. |
| `isArchived` | `Boolean` | Whether this option is archived. |
***
### DeviceFieldParamsInput
Parameters for DEVICE field type.
| Field | Type | Description |
| --------------- | ---------- | ---------------------------------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `refSubtypeIds` | `[ID!]` | The device type IDs a value may belong to. Omit or leave empty to allow any device type. |
***
### ReferenceFieldParamsInput
Parameters for REFERENCE field type.
| Field | Type | Description |
| ------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required. |
| `isMulti` | `Boolean` | Whether multiple entities can be referenced. |
| `refEntityTypeCode` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The target entity type code, e.g. `asset`, `geo_object`, `schedule`, `tag`, `user_catalog_item`. The `customFieldTypes` query lists the accepted values for a given owner. |
| `refSubtypeIds` | `[ID!]` | The subtype IDs a value may belong to (AssetType / GeoObjectType / catalog). Required for `user_catalog_item`, which needs exactly one catalog; rejected for target types that nothing narrows further. Omit or leave empty to allow the whole target type. |
| `defaultRefIds` | `[ID!]` | The default referenced entity IDs. |
***
## Enums
### FieldType
The data type of a custom field, determining validation rules and UI rendering.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STRING` | Single-line text input. At most 255 characters. |
| `TEXT` | Multi-line text input. At most 65,535 characters, counted as UTF-16 code units: every Basic Multilingual Plane character costs one, while an astral character (most emoji, rarer CJK extensions) costs two, so text made entirely of those tops out at 32,767. Unlike STRING it is not orderable: TEXT cannot be used with `AssetOrder`/`GeoObjectOrder`'s `customFieldCode`, nor with the `GT`, `GTE`, `LT` and `LTE` operators. `EQ`, `NE`, `IN`, `CONTAINS`, `IS_NULL` and `IS_NOT_NULL` all work. |
| `DECIMAL` | Arbitrary-precision decimal value (encoded as Decimal string). |
| `INTEGER` | Signed 64-bit integer value (encoded as Long). |
| `BOOLEAN` | Boolean true/false value. |
| `DATE` | Calendar date without time component (YYYY-MM-DD). |
| `DATETIME` | Date and time with timezone information. |
| `GEOJSON` | GeoJSON geometry object (Point, Polygon, LineString, etc.). |
| `OPTIONS` | Selection from a predefined list of options. |
| `DEVICE` | Reference to a Device entity. Definable on an `AssetType` only — see the `customFieldTypes` query. May be narrowed to specific device types via `DeviceFieldParamsInput.refSubtypeIds`. |
| `REFERENCE` | Reference to any entity by its type and ID, including catalog items and tags. The target type is fixed per definition by `ReferenceFieldParamsInput.refEntityTypeCode` and may be narrowed further by `refSubtypeIds`; `customFieldTypes` lists the accepted target types. Devices are not among them — they have their own `DEVICE` field type. |
***
### CustomFieldDefinitionDeleteBehavior
Controls the behavior when deleting a custom field definition that has existing values.
Prefer archiving for non-destructive deactivation. Use `CASCADE` only when permanent data removal is explicitly intended.
| Value | Description |
| --------- | ------------------------------------------------------------------------------------ |
| `REJECT` | Reject the deletion with an error if any entity has a value for this field. Default. |
| `CASCADE` | Delete the field definition and permanently remove all associated values. |
***
### FieldOperator
Comparison operators for filtering by custom field values.
| Value | Description |
| ------------- | ----------------------------------------------------------------- |
| `EQ` | Value equals the specified value. |
| `NE` | Value does not equal the specified value. |
| `GT` | Value is greater than the specified value. |
| `GTE` | Value is greater than or equal to the specified value. |
| `LT` | Value is less than the specified value. |
| `LTE` | Value is less than or equal to the specified value. |
| `CONTAINS` | String value contains the specified substring (case-insensitive). |
| `IN` | Value is one of the specified values in the array. |
| `IS_NULL` | Value is null. |
| `IS_NOT_NULL` | Value is not null. |
***
## Interfaces
### CustomFieldValue
A typed custom-field value on an entity. The concrete type matches the custom field's declared `FieldType`. `isPrimary` is present only on the primary-capable types (DEVICE / REFERENCE).
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | The custom field code. |
| `isDefault` | `Boolean!` | Whether this field is on by default for this entity: the definition's `isDefault`, unless the entity overrides it on the value. |
***
### FieldParams
The base interface for field parameters.
| Field | Type | Description |
| ------------ | ---------- | ------------------------------------------- |
| `isRequired` | `Boolean!` | Whether a value is required for this field. |
***
## See also
* [Pagination](/docs/navixy-graphql-api/pagination.md)
* [Filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting.md)
* [Error handling](/docs/navixy-graphql-api/error-handling.md)
* [Optimistic locking](/docs/navixy-graphql-api/optimistic-locking.md)
* [Limits](/docs/navixy-graphql-api/limits.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://navixy.com/docs/navixy-graphql-api/business-data-repository/api-reference/custom-fields.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.