Skip to content

Custom Fields

albert.resources.custom_fields

Attributes:

Name Type Description
Default

Default 

Default = Annotated[
    StringDefault
    | NumberDefault
    | ListDefault
    | DateDefault
    | TimestampDefault,
    Field(discriminator="type"),
]

FieldType

Bases: str, Enum

The value type stored by a custom field.

Attributes:

Name Type Description
LIST str

A value (or values) chosen from a predefined list. A list field defines its own list; the selectable options are ListItem records (see ListsCollection).
STRING str

A free-text string value.
NUMBER str

A numeric value.
DATE str

A calendar date value stored as YYYY-MM-DD.
TIMESTAMP str

A date-and-time value in ISO 8601 format with a UTC offset (e.g. 2026-05-21T14:32:00+02:00).

LIST 

LIST = 'list'

STRING 

STRING = 'string'

NUMBER 

NUMBER = 'number'

DATE 

DATE = 'date'

TIMESTAMP 

TIMESTAMP = 'timestamp'

ServiceType

Bases: str, Enum

The Albert entity a custom field is attached to.

Attributes:

Name Type Description
INVENTORIES str

Field applies to Inventory Items.
LOTS str

Field applies to Lots.
PROJECTS str

Field applies to Projects.
TASKS str

Field applies to Tasks.
USERS str

Field applies to Users.
PARAMETERS str

Field applies to Parameters.
DATA_COLUMNS str

Field applies to Data Columns.
DATA_TEMPLATES str

Field applies to Data Templates.
PARAMETER_GROUPS str

Field applies to Parameter Groups.
CAS str

Field applies to CAS records.
SUBSTANCES str

Field applies to Substances.

INVENTORIES 

INVENTORIES = 'inventories'

LOTS 

LOTS = 'lots'

PROJECTS 

PROJECTS = 'projects'

TASKS 

TASKS = 'tasks'

USERS 

USERS = 'users'

PARAMETERS 

PARAMETERS = 'parameters'

DATA_COLUMNS 

DATA_COLUMNS = 'datacolumns'

DATA_TEMPLATES 

DATA_TEMPLATES = 'datatemplates'

PARAMETER_GROUPS 

PARAMETER_GROUPS = 'parametergroups'

CAS 

CAS = 'cas'

SUBSTANCES 

SUBSTANCES = 'substances'

FieldCategory

Bases: str, Enum

Who is allowed to add new items to a list custom field.

Attributes:

Name Type Description
BUSINESS_DEFINED str

Only admins can add new allowed items to the list.
USER_DEFINED str

General users can add new allowed items to the list.

BUSINESS_DEFINED 

BUSINESS_DEFINED = 'businessDefined'

USER_DEFINED 

USER_DEFINED = 'userDefined'

EntityCategory

Bases: str, Enum

An entity category a custom field can apply to.

Only some categories are valid for a given service.

Attributes:

Name Type Description
FORMULAS str

Formulas inventory category.
RAW_MATERIALS str

Raw materials inventory category.
CONSUMABLES str

Consumables inventory category.
EQUIPMENT str

Equipment inventory category.
PROPERTY str

Property (measurement) category.
BATCH str

Batch (formulation) category.
GENERAL str

General category.

FORMULAS 

FORMULAS = 'Formulas'

RAW_MATERIALS 

RAW_MATERIALS = 'RawMaterials'

CONSUMABLES 

CONSUMABLES = 'Consumables'

EQUIPMENT 

EQUIPMENT = 'Equipment'

PROPERTY 

PROPERTY = 'Property'

BATCH 

BATCH = 'Batch'

GENERAL 

GENERAL = 'General'

UIComponent

Bases: str, Enum

Where in the UI a custom field is surfaced.

Attributes:

Name Type Description
CREATE str

Shown on the entity's creation form.
DETAILS str

Shown on the entity's details view.

CREATE 

CREATE = 'create'

DETAILS 

DETAILS = 'details'

CustomFieldApiMethod

Bases: str, Enum

HTTP method used to fetch values for an API-backed custom field.

Attributes:

Name Type Description
GET str

Values are fetched with an HTTP GET request.

GET 

GET = 'GET'

CustomFieldAPI

Bases: BaseAlbertModel

Configuration for a custom field whose values come from a remote API.

Show JSON schema: 
{
  "$defs": {
    "CustomFieldApiMethod": {
      "description": "HTTP method used to fetch values for an API-backed custom field.\n\nAttributes\n----------\nGET : str\n    Values are fetched with an HTTP GET request.",
      "enum": [
        "GET"
      ],
      "title": "CustomFieldApiMethod",
      "type": "string"
    }
  },
  "description": "Configuration for a custom field whose values come from a remote API.",
  "properties": {
    "endpoint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The URL the field's values are fetched from.",
      "title": "Endpoint"
    },
    "method": {
      "anyOf": [
        {
          "$ref": "#/$defs/CustomFieldApiMethod"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The HTTP method used to fetch values."
    },
    "queryParamsField": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Names of other fields whose values are passed as query parameters.",
      "title": "Queryparamsfield"
    }
  },
  "title": "CustomFieldAPI",
  "type": "object"
}

Fields:

endpoint 

endpoint: str | None = None

The URL the field's values are fetched from.

method 

method: CustomFieldApiMethod | None = None

The HTTP method used to fetch values.

query_params_field 

query_params_field: list[str] | None = None

Names of other fields whose values are passed as query parameters.

ListDefaultValue

Bases: BaseAlbertModel

A single allowed item used as a default for a list custom field.

Show JSON schema: 
{
  "description": "A single allowed item used as a default for a list custom field.",
  "properties": {
    "albertId": {
      "description": "The ID of the list item.",
      "title": "Albertid",
      "type": "string"
    },
    "name": {
      "description": "The display name of the list item.",
      "title": "Name",
      "type": "string"
    }
  },
  "required": [
    "albertId",
    "name"
  ],
  "title": "ListDefaultValue",
  "type": "object"
}

Fields:

id 

id: str

The ID of the list item.

name 

name: str

The display name of the list item.

StringDefault

Bases: BaseAlbertModel

The default value for a string custom field.

Show JSON schema: 
{
  "description": "The default value for a string custom field.",
  "properties": {
    "type": {
      "const": "string",
      "default": "string",
      "description": "Always ``FieldType.STRING``.",
      "title": "Type",
      "type": "string"
    },
    "value": {
      "description": "The default string value.",
      "title": "Value",
      "type": "string"
    }
  },
  "required": [
    "value"
  ],
  "title": "StringDefault",
  "type": "object"
}

Fields:

type 

type: Literal[STRING] = FieldType.STRING

Always FieldType.STRING.

value 

value: str

The default string value.

NumberDefault

Bases: BaseAlbertModel

The default value for a number custom field.

Show JSON schema: 
{
  "description": "The default value for a number custom field.",
  "properties": {
    "type": {
      "const": "number",
      "default": "number",
      "description": "Always ``FieldType.NUMBER``.",
      "title": "Type",
      "type": "string"
    },
    "value": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "number"
        }
      ],
      "description": "The default numeric value.",
      "title": "Value"
    }
  },
  "required": [
    "value"
  ],
  "title": "NumberDefault",
  "type": "object"
}

Fields:

type 

type: Literal[NUMBER] = FieldType.NUMBER

Always FieldType.NUMBER.

value 

value: int | float

The default numeric value.

DateDefault

Bases: BaseAlbertModel

The default value for a date custom field.

Show JSON schema: 
{
  "description": "The default value for a date custom field.",
  "properties": {
    "type": {
      "const": "date",
      "default": "date",
      "description": "Always ``FieldType.DATE``.",
      "title": "Type",
      "type": "string"
    },
    "value": {
      "description": "The default date in ``YYYY-MM-DD`` format.",
      "title": "Value",
      "type": "string"
    }
  },
  "required": [
    "value"
  ],
  "title": "DateDefault",
  "type": "object"
}

Fields:

type 

type: Literal[DATE] = FieldType.DATE

Always FieldType.DATE.

value 

value: str

The default date in YYYY-MM-DD format.

TimestampDefault

Bases: BaseAlbertModel

The default value for a timestamp custom field.

Show JSON schema: 
{
  "description": "The default value for a timestamp custom field.",
  "properties": {
    "type": {
      "const": "timestamp",
      "default": "timestamp",
      "description": "Always ``FieldType.TIMESTAMP``.",
      "title": "Type",
      "type": "string"
    },
    "value": {
      "description": "The default timestamp in ISO 8601 format with a UTC offset (e.g. ``2026-05-21T14:32:00+02:00``).",
      "title": "Value",
      "type": "string"
    }
  },
  "required": [
    "value"
  ],
  "title": "TimestampDefault",
  "type": "object"
}

Fields:

type 

type: Literal[TIMESTAMP] = FieldType.TIMESTAMP

Always FieldType.TIMESTAMP.

value 

value: str

The default timestamp in ISO 8601 format with a UTC offset (e.g. 2026-05-21T14:32:00+02:00).

ListDefault

Bases: BaseAlbertModel

The default value for a list custom field.

Notes

For multi-select custom fields, value must be a list[ListDefaultValue].

Show JSON schema: 
{
  "$defs": {
    "ListDefaultValue": {
      "description": "A single allowed item used as a default for a list custom field.",
      "properties": {
        "albertId": {
          "description": "The ID of the list item.",
          "title": "Albertid",
          "type": "string"
        },
        "name": {
          "description": "The display name of the list item.",
          "title": "Name",
          "type": "string"
        }
      },
      "required": [
        "albertId",
        "name"
      ],
      "title": "ListDefaultValue",
      "type": "object"
    }
  },
  "description": "The default value for a list custom field.\nNotes\n-----\nFor multi-select custom fields, ``value`` must be a ``list[ListDefaultValue]``.",
  "properties": {
    "type": {
      "const": "list",
      "default": "list",
      "description": "Always ``FieldType.LIST``.",
      "title": "Type",
      "type": "string"
    },
    "value": {
      "anyOf": [
        {
          "$ref": "#/$defs/ListDefaultValue"
        },
        {
          "items": {
            "$ref": "#/$defs/ListDefaultValue"
          },
          "type": "array"
        }
      ],
      "description": "The default list item(s). Notes ----- For multi-select custom fields, ``value`` must be a ``list[ListDefaultValue]``.",
      "title": "Value"
    }
  },
  "required": [
    "value"
  ],
  "title": "ListDefault",
  "type": "object"
}

Fields:

type 

type: Literal[LIST] = FieldType.LIST

Always FieldType.LIST.

value 

value: ListDefaultValue | list[ListDefaultValue]

The default list item(s). Notes ----- For multi-select custom fields, value must be a list[ListDefaultValue].

CustomField

Bases: BaseResource

A custom field definition in Albert.

A custom field defines an allowed metadata field on an Albert entity. Once defined, its name may be used as a key in the metadata dict of the matching entity (Project, Inventory Item, User, Task, Lot, etc.), and its type and validation rules constrain the stored value. Create and manage custom fields through CustomFieldCollection.

When field_type is LIST, the field defines a new list (identified by a list_type, typically the field's name). The selectable options are ListItem records with a matching list_type, managed through ListsCollection (client.lists).

For date and timestamp fields, stored values and defaults use the wire formats documented on FieldType.

Example

from albert.resources.custom_fields import (
    CustomField,
    FieldCategory,
    FieldType,
    ServiceType,
)
stage_gate_field = CustomField(
    name="stage_gate_status",
    display_name="Stage Gate",
    field_type=FieldType.LIST,
    service=ServiceType.PROJECTS,
    min=1,
    max=1,
    category=FieldCategory.BUSINESS_DEFINED,
)
Show JSON schema: 
{
  "$defs": {
    "AuditFields": {
      "description": "The audit fields for a resource",
      "properties": {
        "by": {
          "default": null,
          "title": "By",
          "type": "string"
        },
        "byName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Byname"
        },
        "at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "At"
        }
      },
      "title": "AuditFields",
      "type": "object"
    },
    "CustomFieldAPI": {
      "description": "Configuration for a custom field whose values come from a remote API.",
      "properties": {
        "endpoint": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The URL the field's values are fetched from.",
          "title": "Endpoint"
        },
        "method": {
          "anyOf": [
            {
              "$ref": "#/$defs/CustomFieldApiMethod"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The HTTP method used to fetch values."
        },
        "queryParamsField": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Names of other fields whose values are passed as query parameters.",
          "title": "Queryparamsfield"
        }
      },
      "title": "CustomFieldAPI",
      "type": "object"
    },
    "CustomFieldApiMethod": {
      "description": "HTTP method used to fetch values for an API-backed custom field.\n\nAttributes\n----------\nGET : str\n    Values are fetched with an HTTP GET request.",
      "enum": [
        "GET"
      ],
      "title": "CustomFieldApiMethod",
      "type": "string"
    },
    "DateDefault": {
      "description": "The default value for a date custom field.",
      "properties": {
        "type": {
          "const": "date",
          "default": "date",
          "description": "Always ``FieldType.DATE``.",
          "title": "Type",
          "type": "string"
        },
        "value": {
          "description": "The default date in ``YYYY-MM-DD`` format.",
          "title": "Value",
          "type": "string"
        }
      },
      "required": [
        "value"
      ],
      "title": "DateDefault",
      "type": "object"
    },
    "EntityCategory": {
      "description": "An entity category a custom field can apply to.\n\nOnly some categories are valid for a given service.\n\nAttributes\n----------\nFORMULAS : str\n    Formulas inventory category.\nRAW_MATERIALS : str\n    Raw materials inventory category.\nCONSUMABLES : str\n    Consumables inventory category.\nEQUIPMENT : str\n    Equipment inventory category.\nPROPERTY : str\n    Property (measurement) category.\nBATCH : str\n    Batch (formulation) category.\nGENERAL : str\n    General category.",
      "enum": [
        "Formulas",
        "RawMaterials",
        "Consumables",
        "Equipment",
        "Property",
        "Batch",
        "General"
      ],
      "title": "EntityCategory",
      "type": "string"
    },
    "FieldCategory": {
      "description": "Who is allowed to add new items to a list custom field.\n\nAttributes\n----------\nBUSINESS_DEFINED : str\n    Only admins can add new allowed items to the list.\nUSER_DEFINED : str\n    General users can add new allowed items to the list.",
      "enum": [
        "businessDefined",
        "userDefined"
      ],
      "title": "FieldCategory",
      "type": "string"
    },
    "FieldType": {
      "description": "The value type stored by a custom field.\n\nAttributes\n----------\nLIST : str\n    A value (or values) chosen from a predefined list. A ``list`` field\n    defines its own list; the selectable options are\n    [`ListItem`][albert.resources.lists.ListItem] records (see\n    [`ListsCollection`][albert.collections.lists.ListsCollection]).\nSTRING : str\n    A free-text string value.\nNUMBER : str\n    A numeric value.\nDATE : str\n    A calendar date value stored as ``YYYY-MM-DD``.\nTIMESTAMP : str\n    A date-and-time value in ISO 8601 format with a UTC offset\n    (e.g. ``2026-05-21T14:32:00+02:00``).",
      "enum": [
        "list",
        "string",
        "number",
        "date",
        "timestamp"
      ],
      "title": "FieldType",
      "type": "string"
    },
    "ListDefault": {
      "description": "The default value for a list custom field.\nNotes\n-----\nFor multi-select custom fields, ``value`` must be a ``list[ListDefaultValue]``.",
      "properties": {
        "type": {
          "const": "list",
          "default": "list",
          "description": "Always ``FieldType.LIST``.",
          "title": "Type",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "$ref": "#/$defs/ListDefaultValue"
            },
            {
              "items": {
                "$ref": "#/$defs/ListDefaultValue"
              },
              "type": "array"
            }
          ],
          "description": "The default list item(s). Notes ----- For multi-select custom fields, ``value`` must be a ``list[ListDefaultValue]``.",
          "title": "Value"
        }
      },
      "required": [
        "value"
      ],
      "title": "ListDefault",
      "type": "object"
    },
    "ListDefaultValue": {
      "description": "A single allowed item used as a default for a list custom field.",
      "properties": {
        "albertId": {
          "description": "The ID of the list item.",
          "title": "Albertid",
          "type": "string"
        },
        "name": {
          "description": "The display name of the list item.",
          "title": "Name",
          "type": "string"
        }
      },
      "required": [
        "albertId",
        "name"
      ],
      "title": "ListDefaultValue",
      "type": "object"
    },
    "NumberDefault": {
      "description": "The default value for a number custom field.",
      "properties": {
        "type": {
          "const": "number",
          "default": "number",
          "description": "Always ``FieldType.NUMBER``.",
          "title": "Type",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "number"
            }
          ],
          "description": "The default numeric value.",
          "title": "Value"
        }
      },
      "required": [
        "value"
      ],
      "title": "NumberDefault",
      "type": "object"
    },
    "ServiceType": {
      "description": "The Albert entity a custom field is attached to.\n\nAttributes\n----------\nINVENTORIES : str\n    Field applies to Inventory Items.\nLOTS : str\n    Field applies to Lots.\nPROJECTS : str\n    Field applies to Projects.\nTASKS : str\n    Field applies to Tasks.\nUSERS : str\n    Field applies to Users.\nPARAMETERS : str\n    Field applies to Parameters.\nDATA_COLUMNS : str\n    Field applies to Data Columns.\nDATA_TEMPLATES : str\n    Field applies to Data Templates.\nPARAMETER_GROUPS : str\n    Field applies to Parameter Groups.\nCAS : str\n    Field applies to CAS records.\nSUBSTANCES : str\n    Field applies to Substances.",
      "enum": [
        "inventories",
        "lots",
        "projects",
        "tasks",
        "users",
        "parameters",
        "datacolumns",
        "datatemplates",
        "parametergroups",
        "cas",
        "substances"
      ],
      "title": "ServiceType",
      "type": "string"
    },
    "Status": {
      "description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n    The resource is fully operational and visible in normal operations.\nINACTIVE : str\n    The resource is hidden from normal operations and disabled from use.",
      "enum": [
        "active",
        "inactive"
      ],
      "title": "Status",
      "type": "string"
    },
    "StringDefault": {
      "description": "The default value for a string custom field.",
      "properties": {
        "type": {
          "const": "string",
          "default": "string",
          "description": "Always ``FieldType.STRING``.",
          "title": "Type",
          "type": "string"
        },
        "value": {
          "description": "The default string value.",
          "title": "Value",
          "type": "string"
        }
      },
      "required": [
        "value"
      ],
      "title": "StringDefault",
      "type": "object"
    },
    "TimestampDefault": {
      "description": "The default value for a timestamp custom field.",
      "properties": {
        "type": {
          "const": "timestamp",
          "default": "timestamp",
          "description": "Always ``FieldType.TIMESTAMP``.",
          "title": "Type",
          "type": "string"
        },
        "value": {
          "description": "The default timestamp in ISO 8601 format with a UTC offset (e.g. ``2026-05-21T14:32:00+02:00``).",
          "title": "Value",
          "type": "string"
        }
      },
      "required": [
        "value"
      ],
      "title": "TimestampDefault",
      "type": "object"
    },
    "UIComponent": {
      "description": "Where in the UI a custom field is surfaced.\n\nAttributes\n----------\nCREATE : str\n    Shown on the entity's creation form.\nDETAILS : str\n    Shown on the entity's details view.",
      "enum": [
        "create",
        "details"
      ],
      "title": "UIComponent",
      "type": "string"
    }
  },
  "description": "A custom field definition in Albert.\n\nA custom field defines an allowed metadata field on an Albert entity. Once\ndefined, its ``name`` may be used as a key in the ``metadata`` dict of the\nmatching entity (Project, Inventory Item, User, Task, Lot, etc.), and its\ntype and validation rules constrain the stored value. Create and manage\ncustom fields through\n[`CustomFieldCollection`][albert.collections.custom_fields.CustomFieldCollection].\n\nWhen ``field_type`` is [`LIST`][albert.resources.custom_fields.FieldType.LIST], the field defines a new list\n(identified by a ``list_type``, typically the field's ``name``). The\nselectable options are [`ListItem`][albert.resources.lists.ListItem] records with\na matching ``list_type``, managed through\n[`ListsCollection`][albert.collections.lists.ListsCollection] (``client.lists``).\n\nFor ``date`` and ``timestamp`` fields, stored values and defaults use the\nwire formats documented on [`FieldType`][albert.resources.custom_fields.FieldType].\n\n!!! example\n    ```python\n    from albert.resources.custom_fields import (\n        CustomField,\n        FieldCategory,\n        FieldType,\n        ServiceType,\n    )\n    stage_gate_field = CustomField(\n        name=\"stage_gate_status\",\n        display_name=\"Stage Gate\",\n        field_type=FieldType.LIST,\n        service=ServiceType.PROJECTS,\n        min=1,\n        max=1,\n        category=FieldCategory.BUSINESS_DEFINED,\n    )\n    ```",
  "properties": {
    "status": {
      "anyOf": [
        {
          "$ref": "#/$defs/Status"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The status of the resource, optional."
    },
    "Created": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the creation of the resource, optional."
    },
    "Updated": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the update of the resource, optional."
    },
    "name": {
      "description": "The field name (used as the metadata key). Cannot contain spaces.",
      "title": "Name",
      "type": "string"
    },
    "albertId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The Custom Field ID (format ``CTF...``). Assigned by Albert on creation.",
      "title": "Albertid"
    },
    "type": {
      "$ref": "#/$defs/FieldType",
      "description": "The value type of the field (e.g. ``list``, ``string``, ``number``, ``date``, ``timestamp``). ``string`` and ``list`` fields can be searchable; ``number``, ``date``, and ``timestamp`` fields cannot."
    },
    "labelName": {
      "description": "The human-readable label for the field. Can contain spaces. Limited to 40 characters.",
      "maxLength": 40,
      "title": "Labelname",
      "type": "string"
    },
    "search": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether the field is searchable. Defaults to False. Supported for ``list`` and ``string`` fields only.",
      "title": "Search"
    },
    "service": {
      "$ref": "#/$defs/ServiceType",
      "description": "The Albert entity the field is attached to."
    },
    "hidden": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether the field is hidden. Defaults to False.",
      "title": "Hidden"
    },
    "lkpColumn": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether the field is a lookup column. Defaults to False. Only allowed for inventories.",
      "title": "Lkpcolumn"
    },
    "lkpRow": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether the field is a lookup row. Defaults to False. Only allowed for formulas in inventories.",
      "title": "Lkprow"
    },
    "category": {
      "anyOf": [
        {
          "$ref": "#/$defs/FieldCategory"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Who may add new items to a list field. Required for ``list`` fields."
    },
    "min": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The minimum count allowed for the field: the fewest items selectable in a multiselect list, or the fewest characters allowed in a string.",
      "title": "Min"
    },
    "max": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The maximum count allowed for the field: the most items selectable in a multiselect list, or the most characters allowed in a string.",
      "title": "Max"
    },
    "entityCategory": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/EntityCategory"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The entity categories the field applies to. Required for lookup row fields.",
      "title": "Entitycategory"
    },
    "customEntityCategory": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Custom entity categories that define where the field is valid.",
      "title": "Customentitycategory"
    },
    "ui_components": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/UIComponent"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Where the field is surfaced in the UI (``create`` and/or ``details``).",
      "title": "Ui Components"
    },
    "required": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether a value for the field is required.",
      "title": "Required"
    },
    "multiselect": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "For list fields, whether multiple values may be selected.",
      "title": "Multiselect"
    },
    "editable": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether the field can be edited in the UI.",
      "title": "Editable"
    },
    "pattern": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A validation pattern the field's value must match.",
      "title": "Pattern"
    },
    "default": {
      "anyOf": [
        {
          "discriminator": {
            "mapping": {
              "date": "#/$defs/DateDefault",
              "list": "#/$defs/ListDefault",
              "number": "#/$defs/NumberDefault",
              "string": "#/$defs/StringDefault",
              "timestamp": "#/$defs/TimestampDefault"
            },
            "propertyName": "type"
          },
          "oneOf": [
            {
              "$ref": "#/$defs/StringDefault"
            },
            {
              "$ref": "#/$defs/NumberDefault"
            },
            {
              "$ref": "#/$defs/ListDefault"
            },
            {
              "$ref": "#/$defs/DateDefault"
            },
            {
              "$ref": "#/$defs/TimestampDefault"
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The default value applied to the field. For ``date`` and ``timestamp`` fields, use [`DateDefault`][albert.resources.custom_fields.DateDefault] or [`TimestampDefault`][albert.resources.custom_fields.TimestampDefault] with the wire format documented on [`FieldType`][albert.resources.custom_fields.FieldType].",
      "title": "Default"
    },
    "api": {
      "anyOf": [
        {
          "$ref": "#/$defs/CustomFieldAPI"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Configuration for fields whose values are backed by a remote API."
    }
  },
  "required": [
    "name",
    "type",
    "labelName",
    "service"
  ],
  "title": "CustomField",
  "type": "object"
}

Fields:

Validators:

name 

name: str

The field name (used as the metadata key). Cannot contain spaces.

id 

id: str | None = None

The Custom Field ID (format CTF...). Assigned by Albert on creation.

field_type 

field_type: FieldType

The value type of the field (e.g. list, string, number, date, timestamp). string and list fields can be searchable; number, date, and timestamp fields cannot.

display_name 

display_name: str

The human-readable label for the field. Can contain spaces. Limited to 40 characters.

searchable 

searchable: bool | None = None

Whether the field is searchable. Defaults to False. Supported for list and string fields only.

service 

service: ServiceType

The Albert entity the field is attached to.

hidden 

hidden: bool | None = None

Whether the field is hidden. Defaults to False.

lookup_column 

lookup_column: bool | None = None

Whether the field is a lookup column. Defaults to False. Only allowed for inventories.

lookup_row 

lookup_row: bool | None = None

Whether the field is a lookup row. Defaults to False. Only allowed for formulas in inventories.

category 

category: FieldCategory | None = None

Who may add new items to a list field. Required for list fields.

min 

min: int | float | None = None

The minimum count allowed for the field: the fewest items selectable in a multiselect list, or the fewest characters allowed in a string.

max 

max: int | float | None = None

The maximum count allowed for the field: the most items selectable in a multiselect list, or the most characters allowed in a string.

entity_categories 

entity_categories: list[EntityCategory] | None = None

The entity categories the field applies to. Required for lookup row fields.

custom_entity_categories 

custom_entity_categories: list[str] | None = None

Custom entity categories that define where the field is valid.

ui_components 

ui_components: list[UIComponent] | None = None

Where the field is surfaced in the UI (create and/or details).

required 

required: bool | None = None

Whether a value for the field is required.

multiselect 

multiselect: bool | None = None

For list fields, whether multiple values may be selected.

editable 

editable: bool | None = None

Whether the field can be edited in the UI.

pattern 

pattern: str | None = None

A validation pattern the field's value must match.

default 

default: Default | None = None

The default value applied to the field. For date and timestamp fields, use DateDefault or TimestampDefault with the wire format documented on FieldType.

api 

api: CustomFieldAPI | None = None

Configuration for fields whose values are backed by a remote API.

confirm_field_compatability 

confirm_field_compatability() -> CustomField
Source code in src/albert/resources/custom_fields.py 
340
341
342
343
344
@model_validator(mode="after")
def confirm_field_compatability(self) -> CustomField:
    if self.field_type == FieldType.LIST and self.category is None:
        raise ValueError("Category must be set for list fields")
    return self

ensure_default_has_type 

ensure_default_has_type(v: Any) -> Any
Source code in src/albert/resources/custom_fields.py 
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
@field_validator("default", mode="before")
@classmethod
def ensure_default_has_type(cls, v: Any) -> Any:
    if v is None:
        return v

    if isinstance(v, dict) and "type" in v:
        return v

    if isinstance(v, dict) and "value" in v:
        raw_val = v["value"]

        if isinstance(raw_val, str):
            inferred_type = FieldType.STRING
        elif isinstance(raw_val, (int | float)):
            inferred_type = FieldType.NUMBER
        elif isinstance(raw_val, dict) and "albertId" in raw_val or isinstance(raw_val, list):
            inferred_type = FieldType.LIST
        else:
            raise ValueError(f"Cannot infer default type from value: {raw_val!r}")

        return {"type": inferred_type, "value": raw_val}

    return v

SearchableCustomField

Bases: BaseAlbertModel

A descriptor for a custom field that is exposed to search.

Returned by get_searchable_fields to describe how a field can be queried and sorted in search.

Show JSON schema: 
{
  "description": "A descriptor for a custom field that is exposed to search.\n\nReturned by\n[`get_searchable_fields`][albert.collections.custom_fields.CustomFieldCollection.get_searchable_fields]\nto describe how a field can be queried and sorted in search.",
  "properties": {
    "label": {
      "description": "The field's display label.",
      "title": "Label",
      "type": "string"
    },
    "type": {
      "description": "The field's value type.",
      "title": "Type",
      "type": "string"
    },
    "isSortable": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether search results can be sorted by this field.",
      "title": "Issortable"
    },
    "sortByParam": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The parameter name to use when sorting by this field.",
      "title": "Sortbyparam"
    },
    "isCustom": {
      "description": "Whether the field is a custom field (as opposed to a standard field).",
      "title": "Iscustom",
      "type": "boolean"
    }
  },
  "required": [
    "label",
    "type",
    "isCustom"
  ],
  "title": "SearchableCustomField",
  "type": "object"
}

Fields:

label 

label: str

The field's display label.

type 

type: str

The field's value type.

is_sortable 

is_sortable: bool | None = None

Whether search results can be sorted by this field.

sort_by_param 

sort_by_param: str | None = None

The parameter name to use when sorting by this field.

is_custom 

is_custom: bool

Whether the field is a custom field (as opposed to a standard field).