Implementing custom fields

Define and use custom fields to attach domain-specific data to entities.

Navixy Repository 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.

In Navixy Repository API, devices, assets, geo objects, and schedules each come with a set of built-in fields such as title, organization, and type. Custom fields let you extend these entities with additional data specific to your operation, such as a VIN number, a fuel type, an inspection date, or access level, without any changes to the platform schema.

How custom fields work

Custom fields can be user-defined or predefined. User-defined fields are created by you and scoped to a specific entity type — for example, a vin field that only appears in vehicles. Predefined fields are built into the platform for certain entity types, such as geojson in geo objects.

This guide covers user-defined fields. Avoid using predefined field codes (geojson, device, and schedule_data) for creating your own fields.

Every custom field has a FieldType that determines what kind of data it stores and what validation options are available. You can add any number of fields with different types to a given entity type.

Field type reference

Field type	Use for	Key params	Example value
STRING	Short text, codes, identifiers	isRequired, minLength, maxLength, defaultValue, trim	"1HGBH41JXMN109186"
TEXT	Long descriptions, notes	isRequired, maxLength, defaultValue, trim	"Installed under dashboard, driver side"
NUMBER	Quantities, measurements	isRequired, min, max, precision, defaultValue	42, 3.14
BOOLEAN	Flags, yes/no attributes	isRequired, defaultValue	true
DATE	Calendar dates	isRequired, defaultValue	"2025-06-01"
DATETIME	Timestamps	isRequired, defaultValue	"2025-06-01T09:00:00Z"
OPTIONS	Predefined choices (single or multi)	isRequired, isMulti, options[], defaultValue	"diesel"
GEOJSON	Geometry data	isRequired, allowedTypes (GeoJsonGeometryType)	{"type":"Point","coordinates":[...]}
SCHEDULE	References to schedule definitions	isRequired	Schedule object
DEVICE	Links to device records	isRequired, isMulti	"019a6a3f-..."
REFERENCE	Links to other entity records	isRequired, isMulti, refEntityTypeCode	"019a6a3f-..."
CATALOG	Links to catalog items	isRequired, isMulti, refCatalogCode	"ITEM_CODE"
TAG	Tags from a tag catalog	isRequired, isMulti	"TAG_CODE"

Each field is described by CustomFieldDefinition — a metadata record that specifies the field's code, display title, type, and validation rules. When you create or update an entity, you supply field values through the customFields field in the mutation input, and the API validates each value against the corresponding definition.

Writing custom field values

customFields in any create or update mutation accepts a CustomFieldsPatchInput with two sub-fields:

Field	Type	Description
set	JSON	Key-value map of fields to create or overwrite.
unset	[Code!]	List of field codes to remove entirely.

This is the patch model: fields you don't mention are left unchanged. You can set and unset in the same mutation. For example, to update a license plate and remove an assigned driver in one call, add this code:

customFields: {
  set:   { license_plate: "HH-TL 4421" }
  unset: ["assigned_driver"]
}

Omitting customFields altogether leaves all existing values untouched.

Scenario: Enriching fleet records with metadata

A logistics company needs to store operational metadata on their vehicle assets: a VIN number for compliance, a fuel type for route planning, and a next service date for maintenance management. All examples in this guide use these three fields.

Adding this metadata requires the following steps:

1

Choose a field type

Before creating a definition, pick the fieldType that best matches your data. See the field type reference above.

fieldType is immutable after creation. If you need to change a field's type, delete the definition and create a new one. Values already stored under that code in entity records remain in the JSON but will no longer have a backing definition.

2

Create field definitions

To create a definition, you need three IDs:

• organizationId : the organization that owns the definition

• ownerCatalogItemId: the specific type the field belongs to (e.g., AssetType for "vehicle")

• targetEntityTypeId : the broader entity type category (e.g., EntityType for "asset")

2.1 Check the existing definitions

Before adding new fields, check what's already defined in a type by querying customFieldDefinitions on the type object:

query GetVehicleTypeFields {
  assetType(id: "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11") {
    title
    customFieldDefinitions {
      code
      title
      fieldType
    }
  }
}

Response (if the fields already exist):

{
  "data": {
    "assetType": {
      "title": "Vehicle",
      "customFieldDefinitions": [
        {
          "code": "vin",
          "title": "VIN Number",
          "fieldType": "STRING"
        },
        {
          "code": "fuel_type",
          "title": "Fuel Type",
          "fieldType": "OPTIONS"
        }
      ]
    }
  }
}

If no custom fields have been created yet, customFieldDefinitions is an empty array. The query works the same way for deviceType, geoObjectType, and scheduleType.

2.2 Choose codes for your fields

Choose a code for each field before creating its definition. The code becomes the key used to read and write values in all entity mutations and queries, so treat it as stable once records carry values under it — changing it later means recreating the definition and losing existing data.

Codes can contain ASCII letters, digits, underscores, dots, and hyphens, and must start with a letter or digit (max 64 characters). Predefined system items use UPPER_SNAKE_CASE, but user-defined fields accept any valid format.

2.3 Create a STRING field (VIN)

Run the following mutation:

mutation CreateVinField {
  customFieldDefinitionCreate(input: {
    organizationId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ownerCatalogItemId: "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
    targetEntityTypeId: "b2ffca99-1c0b-4ef8-bb6d-6bb9bd380a33"
    code: "vin"
    title: "VIN Number"
    description: "17-character Vehicle Identification Number"
    fieldType: STRING
    order: 1
    params: {
      string: {
        isRequired: true
        minLength: 17
        maxLength: 17
        trim: true
      }
    }
  }) {
    customFieldDefinition {
      id
      code
      fieldType
    }
  }
}

The response confirms creation and returns the definition's ID:

{
  "data": {
    "customFieldDefinitionCreate": {
      "customFieldDefinition": {
        "id": "019b1c3d-905f-827b-8003-777567741d66",
        "code": "vin",
        "fieldType": "STRING"
      }
    }
  }
}

The params input uses the @oneOf directive — you must provide exactly one variant matching your fieldType.

Each field type has its own named params block that you must use. The mutations in this step demonstrate this: the VIN field uses params: { string: { ... } }, the fuel type field uses params: { options: { ... } }, and the service date field uses params: { date: { ... } }. Providing the wrong variant returns a validation error.

2.4 Create an OPTIONS field (fuel type)

Run the following mutation:

mutation CreateFuelTypeField {
  customFieldDefinitionCreate(input: {
    organizationId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ownerCatalogItemId: "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
    targetEntityTypeId: "b2ffca99-1c0b-4ef8-bb6d-6bb9bd380a33"
    code: "fuel_type"
    title: "Fuel Type"
    fieldType: OPTIONS
    order: 2
    params: {
      options: {
        isRequired: true
        isMulti: false
        options: [
          { code: "diesel",   label: "Diesel" }
          { code: "electric", label: "Electric" }
          { code: "hybrid",   label: "Hybrid" }
        ]
        defaultValue: "diesel"
      }
    }
  }) {
    customFieldDefinition {
      id
      code
    }
  }
}

On success, the response returns the new definition's id and code.

Set isMulti: true if an entity can support more than one option. See multi-value fields and filtering for how this affects queries.

2.5 Create a DATE field (next service date)

Run the following mutation:

mutation CreateServiceDateField {
  customFieldDefinitionCreate(input: {
    organizationId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ownerCatalogItemId: "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
    targetEntityTypeId: "b2ffca99-1c0b-4ef8-bb6d-6bb9bd380a33"
    code: "next_service_date"
    title: "Next Service Date"
    fieldType: DATE
    order: 3
    params: {
      date: {
        isRequired: false
      }
    }
  }) {
    customFieldDefinition {
      id
      code
    }
  }
}

On success, the response returns the new definition's id and code.

The same mutation (customFieldDefinitionCreate) works for devices, geo objects, and schedules — only ownerCatalogItemId, targetEntityTypeId, and the params variant change.

3

Set and update values

Pass customFields in the create mutation with the initial values under set. The following example creates a vehicle asset with all three fields populated:

mutation CreateVehicleAsset {
  assetCreate(input: {
    organizationId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    typeId: "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
    title: "Truck 12"
    customFields: {
      set: {
        "vin":               "1HGBH41JXMN109186"
        "fuel_type":         "diesel"
        "next_service_date": "2025-09-01"
      }
    }
  }) {
    asset {
      id
      version
      customFields
    }
  }
}

The response returns the created asset's id, version, and customFields:

{
  "data": {
    "assetCreate": {
      "asset": {
        "id": "019a6b2f-793e-807b-8001-555345529b44",
        "version": 1,
        "customFields": {
          "vin": "1HGBH41JXMN109186",
          "fuel_type": "diesel",
          "next_service_date": "2025-09-01"
        }
      }
    }
  }
}

If any custom field value fails validation, the entire mutation is rejected with a VALIDATION_ERROR. Common causes include a value that violates the field's params constraints (for example, a VIN shorter than 17 characters), an unrecognized field code, or a value of the wrong type. The error response includes a field path and a detail message identifying the problem. See Error handling for the full error format.

The same pattern applies to deviceCreate, geoObjectCreate, and scheduleCreate fields.

4

Update custom field values

Use set to overwrite specific fields and unset to remove them. Fields omitted from both are left unchanged.

The following mutation updates the SIM card number on a device and removes its installation notes:

mutation UpdateTrackerFields {
  deviceUpdate(input: {
    id: "019a6c3f-894e-817b-8002-666456630c55"
    version: 3
    customFields: {
      set:   { "sim_card": "8931010000000000001" }
      unset: ["installation_notes"]
    }
  }) {
    device {
      id
      version
      customFields
    }
  }
}

The response returns the updated device's id, version, and customFields. Fields that were unset no longer appear in the JSON:

{
  "data": {
    "deviceUpdate": {
      "device": {
        "id": "019a6c3f-894e-817b-8002-666456630c55",
        "version": 4,
        "customFields": {
          "sim_card": "8931010000000000001"
        }
      }
    }
  }
}

All entity update mutations require the current version for optimistic locking. Fetch the entity first if you don't have the latest version.

5

Read custom field values

customFields on any entity returns a JSON object keyed by field code. By default, all fields are returned. Run the following query:

query GetAssetFields {
  asset(id: "019a6b2f-793e-807b-8001-555345529b44") {
    title
    customFields
  }
}

Response:

{
  "data": {
    "asset": {
      "title": "Truck 12",
      "customFields": {
        "vin": "1HGBH41JXMN109186",
        "fuel_type": "diesel",
        "next_service_date": "2025-09-01"
      }
    }
  }
}

To retrieve only specific fields, pass the codes argument. This keeps response payloads smaller when an entity type has many fields:

query GetVehicleKeyFields {
  asset(id: "019a6b2f-793e-807b-8001-555345529b44") {
    title
    customFields(codes: ["vin", "fuel_type"])
  }
}

The response contains only the requested fields:

{
  "data": {
    "asset": {
      "title": "Truck 12",
      "customFields": {
        "vin": "1HGBH41JXMN109186",
        "fuel_type": "diesel"
      }
    }
  }
}

6

Filter entities by custom field value

All entity list queries support filtering by custom field values through CustomFieldFilter. Add one or more conditions to the customFields filter array. Multiple conditions are applied as AND.

For the full operator list and value formats by field type, see Filtering and sorting.

How to filter by an OPTIONS value

Find all electric vehicle assets:

query FindElectricVehicles {
  assets(
    organizationId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    filter: {
      typeIds: ["a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"]
      customFields: [
        { code: "fuel_type", operator: EQ, value: "electric" }
      ]
    }
  ) {
    nodes {
      id
      title
      customFields(codes: ["fuel_type", "next_service_date"])
    }
  }
}

Response:

{
  "data": {
    "assets": {
      "nodes": [
        {
          "id": "019a6b2f-793e-807b-8001-555345529b44",
          "title": "Truck 12",
          "customFields": {
            "fuel_type": "electric",
            "next_service_date": "2025-09-01"
          }
        }
      ]
    }
  }
}

How to filter by a DATE value

Find vehicles with a service date before a deadline:

query FindOverdueVehicles {
  assets(
    organizationId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    filter: {
      typeIds: ["a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"]
      customFields: [
        { code: "next_service_date", operator: LT, value: "2025-07-01" }
      ]
    }
  ) {
    nodes {
      id
      title
      customFields(codes: ["next_service_date"])
    }
  }
}

Response:

{
  "data": {
    "assets": {
      "nodes": [
        {
          "id": "019a6b2f-793e-807b-8001-555345529b44",
          "title": "Truck 12",
          "customFields": {
            "next_service_date": "2025-06-15"
          }
        }
      ]
    }
  }
}

How to combine multiple conditions

Find devices with a specific SIM card prefix that don't yet have installation notes:

query FindUndocumentedTrackers {
  devices(
    organizationId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    filter: {
      typeIds: ["c3eebc99-9c0b-4ef8-bb6d-6bb9bd380a44"]
      customFields: [
        { code: "sim_card",           operator: CONTAINS, value: "8931" }
        { code: "installation_notes", operator: IS_NULL               }
      ]
    }
  ) {
    nodes {
      id
      title
    }
  }
}

Response:

{
  "data": {
    "devices": {
      "nodes": [
        {
          "id": "019a6c3f-894e-817b-8002-666456630c55",
          "title": "Tracker 04"
        }
      ]
    }
  }
}

Omit value (or set it to null) when using the IS_NULL and IS_NOT_NULL operators.

Managing definitions

How to update a custom field definition

You can update the title, description, order, and params. The code and fieldType cannot be changed after creation. Updates use optimistic locking and require the current version:

mutation UpdateVinField {
  customFieldDefinitionUpdate(input: {
    id: "019b1c3d-905f-827b-8003-777567741d66"
    version: 1
    title: "VIN"
    description: "Vehicle Identification Number (17 characters, no I/O/Q)"
    params: {
      string: {
        isRequired: true
        minLength: 17
        maxLength: 17
        trim: true
      }
    }
  }) {
    customFieldDefinition {
      id
      version
      title
    }
  }
}

The response returns the updated definition's id, incremented version, and new title.

For OPTIONS fields, you can add new options or archive existing ones. Archiving an option (isArchived: true) hides it from new selections without affecting records that already carry it:

params: {
  options: {
    isRequired: true
    isMulti: false
    options: [
      { code: "diesel",   label: "Diesel",   isArchived: false }
      { code: "electric", label: "Electric", isArchived: false }
      { code: "hybrid",   label: "Hybrid",   isArchived: false }
      { code: "hydrogen", label: "Hydrogen", isArchived: false }
      { code: "lpg",      label: "LPG",      isArchived: true  }
    ]
  }
}

How to delete a custom field definition

Run this mutation:

mutation DeleteDefinition {
  customFieldDefinitionDelete(input: {
    id: "019b1c3d-905f-827b-8003-777567741d66"
    version: 2
  }) {
    deletedId
  }
}

The response returns the ID of the deleted definition:

{
  "data": {
    "customFieldDefinitionDelete": {
      "deletedId": "019b1c3d-905f-827b-8003-777567741d66"
    }
  }
}

Deleting a definition removes its key from the customFields JSON on all entity records. If you create a new definition with the same code later, existing records will not retain any value for it — the data is not preserved.

Constraints and considerations

Keep in mind the following:

• Validation errors reject the entire mutation: Mutations that include invalid custom field values are rejected in full. See Error handling for the error format.

• fieldType is immutable: To change a field's type, delete its definition and create a new one. Deleting the definition removes its values from all entity records.

• code is stable once in use: code must be unique within the owner type and organization. As this is the key used to read and write values across all entity mutations and queries, avoid recreating it under a different name if records contain values paired with it.

• params requires exactly one variant: FieldParamsInput uses the @oneOf directive, so you must provide exactly the variant that matches your fieldType. Providing string: { ... } when fieldType is NUMBER returns a validation error.

• Multi-value fields and filtering: For fields with isMulti: true, a filter matches if any value in the array satisfies the condition. For example, if an asset has fuel_type: ["diesel", "hybrid"], filtering with EQ: "diesel" will match it.

• Predefined fields: Predefined definitions (like geojson and schedule_data) are platform-managed and appear in customFields responses alongside your definitions. Do not use codes that conflict with predefined field codes.

See also

• Custom fields types and operations: A complete list of all operations and types related to custom fields

• Filtering and sorting: Full operator reference and value formats for custom field filters

• Optimistic locking: How version works in update and delete mutations