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.
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.
customFieldTypes(ownerTypeId: ID!): [FieldTypeAvailability!]!Arguments
ownerTypeId
ID!
The owner catalog item — the type the fields would be defined on.
Output types:
Objects
DeviceCustomFieldValue
DEVICE custom-field value (primary-capable).
Implements: CustomFieldValue
FieldParamsDevice
Parameters for DEVICE field type.
Implements: FieldParams
isRequired
Boolean!
Whether a value is required for this field.
refSubtypes
[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, MultiValue
isRequired
Boolean!
Whether a value is required for this field.
isMulti
Boolean!
Whether multiple values can be selected for this field.
refSubtypes
[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]!
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
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!
The text value.
DecimalCustomFieldValue
DECIMAL custom-field value (arbitrary precision, string-encoded).
Implements: CustomFieldValue
IntegerCustomFieldValue
INTEGER custom-field value (signed 64-bit).
Implements: CustomFieldValue
BooleanCustomFieldValue
BOOLEAN custom-field value.
Implements: CustomFieldValue
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!
The boolean value.
DateCustomFieldValue
DATE custom-field value.
Implements: CustomFieldValue
DateTimeCustomFieldValue
DATETIME custom-field value.
Implements: CustomFieldValue
GeoJsonCustomFieldValue
GEOJSON custom-field value.
Implements: CustomFieldValue
OptionsCustomFieldValue
OPTIONS custom-field value (one or more option codes).
Implements: CustomFieldValue
ReferenceCustomFieldValue
REFERENCE custom-field value (one or more referenced entities; primary-capable).
Implements: CustomFieldValue
isDefault
Boolean!
Whether this field is on by default for this entity.
refs
[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.
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
title
String!
The human-readable display name.
description
String
A description of the field for UI hints.
order
Int!
The display order within the owner context.
fieldType
The data type determining validation rules and UI rendering. This property is immutable and cannot be changed after creation.
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.
FieldParamsString
Parameters for STRING field type.
Implements: FieldParams
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
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
isRequired
Boolean!
Whether a value is required for this field.
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.
FieldParamsInteger
Parameters for INTEGER field type.
Implements: FieldParams
FieldParamsBoolean
Parameters for BOOLEAN field type.
Implements: FieldParams
isRequired
Boolean!
Whether a value is required for this field.
defaultBoolean
Boolean
The default value.
FieldParamsDate
Parameters for DATE field type.
Implements: FieldParams
isRequired
Boolean!
Whether a value is required for this field.
FieldParamsDatetime
Parameters for DATETIME field type.
Implements: FieldParams
isRequired
Boolean!
Whether a value is required for this field.
FieldParamsGeojson
Parameters for GEOJSON field type.
Implements: FieldParams
isRequired
Boolean!
Whether a value is required for this field.
FieldParamsOptions
Parameters for OPTIONS field type.
Implements: FieldParams, MultiValue
isRequired
Boolean!
Whether a value is required for this field.
isMulti
Boolean!
Whether multiple values can be selected for this field.
FieldOption
A single option in an OPTIONS 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:
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.
string
String
String value — for STRING, TEXT, OPTIONS fields.
boolean
Boolean
Boolean value — for BOOLEAN 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:
INmatches when the stored value equals ANY member of the list — the list itself is an OR.On a multi-value field (
isMultiOPTIONS / REFERENCE), a positive operator matches when ANY stored value satisfies it:["red","blue"]matches{operator: EQ, value: {string: "red"}}.NEandIS_NULLare 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_NULLandNEmatch every entity, every other operator matches none.
value
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.
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.
value
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:
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.
string
String
STRING / TEXT value.
boolean
Boolean
BOOLEAN value.
DeviceValueInput
DEVICE custom-field value.
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.
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.
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.
archive
Archive a custom field definition (non-destructive deactivation).
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.
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.
order
Int
The display order. Auto-calculated as last position if omitted.
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.
title
String
The new display name.
description
String
The new description.
order
Int
The new display order.
params
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.
onValues
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.
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.
FieldParamsInput
Field parameters input. Exactly one field must be provided.
StringFieldParamsInput
Parameters for STRING field type.
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.
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.
isRequired
Boolean!
Whether a value is required.
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.
IntegerFieldParamsInput
Parameters for INTEGER field type.
BooleanFieldParamsInput
Parameters for BOOLEAN field type.
isRequired
Boolean!
Whether a value is required.
defaultBoolean
Boolean
The default value.
DateFieldParamsInput
Parameters for DATE field type.
isRequired
Boolean!
Whether a value is required.
DateTimeFieldParamsInput
Parameters for DATETIME field type.
isRequired
Boolean!
Whether a value is required.
GeoJsonFieldParamsInput
Parameters for GEOJSON field type.
isRequired
Boolean!
Whether a value is required.
OptionsFieldParamsInput
Parameters for OPTIONS field type.
isRequired
Boolean!
Whether a value is required.
isMulti
Boolean
Whether multiple options can be selected.
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.
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.
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.
isRequired
Boolean!
Whether a value is required.
isMulti
Boolean
Whether multiple entities can be referenced.
refEntityTypeCode
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.
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.
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.
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).
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.
isRequired
Boolean!
Whether a value is required for this field.
See also
Last updated
Was this helpful?