Custom Object Type Field Attributes

The following attributes are available when creating or editing a Custom Object Type Field. The deprecation attributes at the end of the table are the exception: they can only be set through the REST API or a portable schema document.

Available Field Types

Common Attributes

Text Fields

Field types: text, longtext (URL fields also take a validation regex)

Numeric Fields

Field types: integer, decimal

A decimal value has up to 16 digits in total, 4 of them after the decimal point, as for a NetBox decimal custom field.

Choice Fields

Field types: select, multiselect

A choice value may be up to 100 characters long, for select and multiselect alike.

Object Reference Fields

Field types: object, multiobject

Coordinates Fields

Field type: coordinates

A single coordinates field stores a geographic latitude/longitude pair, mirroring NetBox's native Site/Device coordinates (plain decimal columns - PostGIS is not required). Adding one coordinates field named location creates two backing columns and two form inputs:

• location_latitude - decimal, range −90 to 90, up to 6 decimal places
• location_longitude - decimal, range −180 to 180, up to 6 decimal places

Behavior:

• Both-or-neither. Latitude and longitude must either both be set or both be empty; setting only one is rejected in forms and via the REST API.
• REST API and CSV import. The pair is exposed as two flat fields, <name>_latitude and <name>_longitude (matching NetBox core's serializers), not as a nested object.
• GraphQL. Coordinates can be filtered on, but aren't returned as fields.
• Map link. Detail views render the coordinates with a Map button that opens the location using NetBox's MAPS_URL configuration parameter (Google Maps by default).
• Must be unique and Default are not supported for coordinates fields, and their search weight is always 0.

Array Fields

Field type: array

An array field stores a list of values of one type in a single PostgreSQL array column. Set Tuple size to store a list of fixed-size tuples instead, such as (x, y, z) points.

For example, an array field with element type Integer, tuple size 3 and minimum length 2 accepts [[0, 0, 0], [10, 0, 5]], and rejects [[0, 0]] (a tuple of the wrong size) and [[0, 0, 0]] (too few items).

Behavior:

• Forms and CSV import. Enter the value as JSON, e.g. [1, 2, 3] or [[0, 0, 0], [10, 0, 5]]; dates and times as strings, e.g. ["2026-01-01"]. In a CSV file, quote the JSON as usual.
• REST API and GraphQL. The value is a JSON list (of lists, for tuples).
• Values. Each value must be of the element type: an integer array rejects 1.5 and true rather than storing 1. An empty list [] is stored as no value (null), so a required field rejects it, and the minimum length applies only to a non-empty list.
• Display. Lists show as 1, 2, 3, and tuples as (0, 0, 0), (10, 0, 5).
• Filtering. ?<name>=1,3 matches objects whose array contains all of the comma-separated values (for tuples, anywhere in any tuple), and ?<name>__len=2 matches by the number of items. Quick search matches objects whose array contains the searched value.
• A field's type cannot be changed to or from array, and arrays can't be included in constraints.

Color Fields

Field type: color

A color field stores an RGB color as six lowercase hexadecimal digits without a leading # (e.g. 00ff00), the same format as NetBox's own color fields such as a tag's color.

• Forms. The edit form offers NetBox's named colors. A value set through the REST API or CSV import that isn't one of them stays selectable when the object is edited.
• Default. The field's default is picked from the same named colors, and the field list shows it the same way.
• Display. Detail views and tables show a color swatch, like NetBox's own color fields; CSV export writes #rrggbb, which CSV import accepts along with uppercase digits.
• Filtering. Filters match whole values, e.g. ?color=00ff00&color=ff0000.

MAC Address Fields

Field type: mac_address

A mac_address field stores an EUI-48 MAC address in a PostgreSQL macaddr column, using NetBox's own MACAddressField, as an interface's MAC address does.

• Input. Forms, CSV import and the REST API accept any common format (00:1a:2b:3c:4d:5e, 00-1A-2B-3C-4D-5E, 001a.2b3c.4d5e, 001a2b3c4d5e) and store the address itself, so every format of the same address is equal for uniqueness, constraints and filters.
• Display. Values are shown and returned as uppercase, colon-separated hex (00:1A:2B:3C:4D:5E). The field's default is typed as plain text and shown the same way.
• Filtering. ?mac=00:1a:2b:3c:4d:5e&mac=... matches whole addresses in any format, and the usual suffixes such as __ic match part of one. Quick search matches part of an address.

URL Fields

Field type: url

A url field stores the URL value plus an optional human-readable link title. Adding one url field named website creates two backing columns:

• website - the URL itself
• website_title - optional display text shown in place of the raw URL

Behavior:

• Detail page and list view. The title, when set, is used as the visible link text both on the object's detail page and in its column in list/table views — the two backing columns are never shown as separate table columns. Falls back to the raw URL as link text when no title is set.
• Optional independently. The title has no relationship to the URL value — setting one without the other is allowed and harmless.
• REST API and CSV import. The pair is exposed as two flat fields, <name> and <name>_title.
• Validation regex. As for text fields, a regular expression the URL must match.
• Must be unique and Default continue to apply to the URL value itself, exactly as for any other url field.
• GraphQL. Only the URL is returned; the title isn't available in GraphQL.