---
sidebar:
  hidden: true
title: roboto.domain.custom_fields.record
---
## Module Contents

### CUSTOM_FIELD_NAME_PATTERN

```python
roboto.domain.custom_fields.record.CUSTOM_FIELD_NAME_PATTERN = '[a-z][a-z0-9_]{0,62}'
```

`from roboto.domain.custom_fields import CUSTOM_FIELD_NAME_PATTERN`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/custom_fields/record.py#L20-L20)

Regular expression describing the format of a valid custom-field name.

A custom-field name is at most 63 characters long, starts with a lowercase ASCII letter, and may otherwise contain lowercase ASCII letters, digits, and underscores.

Unanchored, for embedding in a larger pattern; wrap as `^{...}$` to match a whole field name.

### CustomFieldOptions

```python
type roboto.domain.custom_fields.record.CustomFieldOptions = Annotated[EnumFieldOptions, pydantic.Field(discriminator='field_type')]
```

`from roboto.domain.custom_fields import CustomFieldOptions`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/custom_fields/record.py#L170-L170)

Type-specific configuration carried alongside a custom field. Currently only [`EnumFieldOptions`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.EnumFieldOptions).

### CustomFieldRecord

```python
class roboto.domain.custom_fields.record.CustomFieldRecord(/, **data: Any)
```

`from roboto.domain.custom_fields import CustomFieldRecord`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/custom_fields/record.py#L175-L241)

Bases: `pydantic.BaseModel`

Wire-transmissible representation of a [`CustomField`](/reference/python-sdk/roboto/domain/custom_fields/custom_field#roboto.domain.custom_fields.custom_field.CustomField).

Returned by the custom-fields API and wrapped by [`CustomField`](/reference/python-sdk/roboto/domain/custom_fields/custom_field#roboto.domain.custom_fields.custom_field.CustomField) for ergonomic access. Callers normally interact with the wrapping class rather than this record directly.

**Parameters**

- **data** (`Any`)

**Attributes**

- **CustomFieldRecord.attempts** (`int`) = `0`: Number of attempts the platform has made for the field's current lifecycle phase.

  Diagnostic; not actionable for callers.

- **CustomFieldRecord.created** (`datetime.datetime`): UTC timestamp when the field was defined.

- **CustomFieldRecord.created_by** (`str`): User ID that defined the field.

- **CustomFieldRecord.description** (`str | None`) = `None`: Long-form description of the field's meaning, or `None` if unset.

- **CustomFieldRecord.display_name** (`str | None`) = `None`: Human-readable label for the field, or `None` if unset.

- **CustomFieldRecord.entity_type** (`TargetEntityType`): Roboto entity type the field extends.

- **CustomFieldRecord.field_id** (`str`): Opaque, globally unique identifier for the field.

- **CustomFieldRecord.field_name** (`str`): Name of the field. Unique within `(org_id, entity_type)` and fixed at creation time.

- **CustomFieldRecord.field_type** (`CustomFieldType`): Value type of the field. Fixed at creation time.

- **CustomFieldRecord.last_error** (`str | None`) = `None`: Human-readable summary of the most recent failure, if any.

  Populated when [`status`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldRecord.status) is [`CustomFieldStatus.Failed`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldStatus.Failed), and may stay set after a retry until the next failure or success.

- **CustomFieldRecord.metadata_path** (`str | None`) = `None`: Source metadata key the field was promoted from, if any. Reserved for future use.

- **CustomFieldRecord.modified** (`datetime.datetime`): Timestamp of the field's most recent status or metadata change.

- **CustomFieldRecord.modified_by** (`str`): User ID of the most recent modifier. May be a system identity for automatic status changes.

- **CustomFieldRecord.options** (`CustomFieldOptions | None`) = `None`: Type-specific configuration.

  Present for [`CustomFieldType.Enum`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldType.Enum) fields; `None` for types that take no options.

- **CustomFieldRecord.org_id** (`str`): Organization that owns the field.

- **CustomFieldRecord.status** (`CustomFieldStatus`): Current lifecycle status. See [`CustomFieldStatus`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldStatus).

### CustomFieldStatus

```python
class roboto.domain.custom_fields.record.CustomFieldStatus
```

`from roboto.domain.custom_fields import CustomFieldStatus`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/custom_fields/record.py#L31-L61)

Bases: `roboto.compat.StrEnum`

Lifecycle state of a [`CustomField`](/reference/python-sdk/roboto/domain/custom_fields/custom_field#roboto.domain.custom_fields.custom_field.CustomField).

The status tells a caller what they can do with the field right now. See the [`CustomField`](/reference/python-sdk/roboto/domain/custom_fields/custom_field#roboto.domain.custom_fields.custom_field.CustomField) class docstring for the full lifecycle narrative.

**Attributes**

- **CustomFieldStatus.Creating** = `'creating'`: The field is being set up.

  Values cannot yet be assigned to entities, and the field cannot be referenced in search or sort.

- **CustomFieldStatus.Deleting** = `'deleting'`: The field is on its way out. Callers should treat it as already gone.

- **CustomFieldStatus.Failed** = `'failed'`: The most recent create or delete attempt did not succeed.

  The field stays in this state until an operator intervenes. A field that failed during creation can normally be deleted, however.

- **CustomFieldStatus.Ready** = `'ready'`: The field is fully available.

  Values can be set on entities and the field can be used in search filters and as a sort key.

### CustomFieldType

```python
class roboto.domain.custom_fields.record.CustomFieldType
```

`from roboto.domain.custom_fields import CustomFieldType`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/custom_fields/record.py#L92-L129)

Bases: `roboto.compat.StrEnum`

Value type of a custom field.

A field's type is fixed at creation time and determines which operators are supported in search and sort, as well as which Python types can be assigned as values.

**Attributes**

- **CustomFieldType.Boolean** = `'boolean'`: A boolean value. Supports equality filtering.

- **CustomFieldType.Enum** = `'enum'`: A string value drawn from a fixed set of allowed values.

  The allowed values are declared at creation time via [`EnumFieldOptions`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.EnumFieldOptions). Supports equality and membership filtering, plus sort.

- **CustomFieldType.Number** = `'number'`: A numeric value. Supports equality, range filtering, and sort.

- **CustomFieldType.String** = `'string'`: A free-form string value. Supports equality, substring, and sort.

- **CustomFieldType.Timestamp** = `'timestamp'`: A point in time. Supports equality, range filtering, and sort.

  Values may be given as a `datetime`, an ISO 8601 string, an `int` of nanoseconds since the Unix epoch, or a `float`, `decimal.Decimal` or numeric string of seconds since it. A string is read as seconds whenever it parses as a number, so the all-digit date `20260101` names a moment in 1970 rather than a day in 2026.

  A value carrying no time zone, whether a naive `datetime` or an ISO 8601 string with no offset, is read as UTC; a date with no time, such as `2026-05-14`, resolves to midnight UTC. Sub-microsecond precision is not retained.

  Values are returned as ISO 8601 strings, which `datetime.datetime.fromisoformat` parses.

### EnumFieldOptions

```python
class roboto.domain.custom_fields.record.EnumFieldOptions(/, **data: Any)
```

`from roboto.domain.custom_fields import EnumFieldOptions`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/custom_fields/record.py#L150-L167)

Bases: `pydantic.BaseModel`

Configuration for an [`CustomFieldType.Enum`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldType.Enum) custom field.

Declares the set of values an enum field will accept. Required when creating an enum field; unused for other field types.

**Parameters**

- **data** (`Any`)

**Attributes**

- **EnumFieldOptions.enum_values** (`list[str]`) = `None`: Allowed values for the field. Must contain at least one value.
- **EnumFieldOptions.field_type** (`Literal[CustomFieldType]`): Discriminator that identifies this options payload as belonging to an enum field.

### TargetEntityType

```python
class roboto.domain.custom_fields.record.TargetEntityType
```

`from roboto.domain.custom_fields import TargetEntityType`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/custom_fields/record.py#L64-L89)

Bases: `roboto.compat.StrEnum`

Roboto entity type that a custom field extends.

Each custom field is scoped to exactly one entity type, and a given `field_name` is unique within an `(org_id, entity_type)` pair.

**Attributes**

- **TargetEntityType.Collection** = `'collection'`: Field applies to [`Collection`](/reference/python-sdk/roboto/domain/collections/collection#roboto.domain.collections.collection.Collection) entities.
- **TargetEntityType.Dataset** = `'dataset'`: Field applies to [`Dataset`](/reference/python-sdk/roboto/domain/datasets/dataset#roboto.domain.datasets.dataset.Dataset) entities.
- **TargetEntityType.Device** = `'device'`: Field applies to [`Device`](/reference/python-sdk/roboto/domain/devices/device#roboto.domain.devices.device.Device) entities.
- **TargetEntityType.Event** = `'event'`: Field applies to [`Event`](/reference/python-sdk/roboto/domain/events/event#roboto.domain.events.event.Event) entities.
- **TargetEntityType.Session** = `'session'`: Field applies to [`Session`](/reference/python-sdk/roboto/experimental/sessions/session#roboto.experimental.sessions.session.Session) entities.

**Properties**

- **TargetEntityType.url_safe_value** (`str`): URL-encoded form of this entity type's value, suitable for embedding in a path segment.