Fields Generated by Payload

Payload automatically adds fields to collections and globals based on their configuration. For example, collections receive an id field, auth-enabled collections receive fields such as email, and upload-enabled collections receive fields such as filename.

You can override the configuration of supported generated fields by defining a top-level field with the same name in your collection or global fields array. Payload merges auth, upload, and version field overrides into its default field configuration, preserving properties that you do not override, including hooks. Custom ID and timestamp fields replace the generated field instead.

Example

The following auth collection further restricts writes to Payload's default apiKey field. Field overrides replace matching access functions, so the custom functions build on Payload's canAccessAdmin boundary before applying an application role:

1import {
canAccessAdmin,
type CollectionConfig,
type FieldAccess,
UnauthorizedError,
6} from 'payload'
7
8const canCreateOrUpdateAPIKeys: FieldAccess = async ({ req }) => {
try {
  await canAccessAdmin({ req })
} catch (error) {
  if (error instanceof UnauthorizedError) {
    return false
  }
15
  throw error
}
18
return req.user?.roles?.includes('api-key-admin') === true
20}
21
22export const Users: CollectionConfig = {
slug: 'users',
auth: {
  useAPIKey: true,
},
fields: [
  {
    name: 'apiKey', 
    type: 'text',
    access: {
      create: canCreateOrUpdateAPIKeys,
      update: canCreateOrUpdateAPIKeys,
    },
  },
],
37}

Document fields

The following fields are available on collections and globals without enabling authentication, uploads, or versions:

Field	Used by	Override behavior
`id`	Collections	Replaces the generated ID field. See Custom ID fields.
`createdAt`	Collections with timestamps and all globals	Replaces the generated field. Keep this as a `date` field.
`updatedAt`	Collections with timestamps and all globals	Replaces the generated field. Keep this as a `date` field.
`deletedAt`	Collections with `trash` enabled	Replaces the generated field. Keep this as a `date` field.

Custom ID fields

All Collections automatically generate their own ID field. If needed, you can override this behavior by providing an explicit ID field to your config. This field should either be required or have a hook to generate the ID dynamically.

To define a custom ID field, add a top-level field with the name property set to id:

1import type { CollectionConfig } from 'payload'
2
3export const MyCollection: CollectionConfig = {
4  // ...
5  fields: [
6    {
7      name: 'id', 
8      required: true,
9      type: 'number',
10    },
11  ],
12}

Authentication fields

Authentication fields are added to a collection according to its auth configuration. Payload deep-merges matching fields from your collection's fields array into these defaults, except for the special password override described below.

Fields	Added when
`email`, `password`, `resetPasswordToken`, `resetPasswordExpiration`	The local authentication strategy is enabled.
`username`	`auth.loginWithUsername` is enabled.
`enableAPIKey` (legacy), `apiKey`, `apiKeyIndex`, `hasAPIKey`	`auth.useAPIKey` is enabled.
`_verified`, `_verificationToken`	`auth.verify` is enabled.
`loginAttempts`, `lockUntil`	`auth.maxLoginAttempts` is greater than `0`.
`sessions`	`auth.useSessions` is enabled.

The password override is also applied to the generated new-password and confirm-password fields in the Admin Panel. You may need to set hidden: true on the override to prevent an additional field from being displayed.

The salt and hash fields are reserved and cannot be overridden.

Upload fields

The following fields are added to upload-enabled collections. Payload deep-merges matching fields from your collection's fields array into these defaults.

Fields	Added when
`filename`, `mimeType`, `filesize`, `width`, `height`, `url`, `thumbnailURL`	Uploads are enabled.
`focalX`, `focalY`	Focal points are enabled, or `imageSizes` or `resizeOptions` is configured.
`sizes`	`imageSizes` is configured. Matching fields nested under `sizes` are also merged recursively.

The file field is reserved and cannot be overridden.

Version fields

The _status field is added to collections and globals when drafts are enabled. Define a top-level _status field to merge custom configuration into Payload's default field.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.