Field metadata

The plugin infers a JSON Schema for every field from its Payload type — a text field becomes a string, a number field a number, a select an enum, and so on. You rarely need to touch that. When you do, put a partial Schema Object under the field’s custom.openapi key. Whatever you put there is deep-merged on top of the inferred schema, and your keys win. You only change what you name; everything else the plugin inferred stays intact. The merge applies wherever the field appears — the read, create, and update schemas alike.

Annotating a field

collections/Posts.ts

import type { Field } from 'payload'

const slug: Field = {
  name: 'slug',
  type: 'text',
  custom: {
    openapi: {
      description: 'URL-safe identifier, lowercase with dashes.',
      pattern: '^[a-z0-9-]+$',
      example: 'hello-world',
    },
  },
}

Any Schema Object keyword works — format, deprecated, length and range constraints, or a full type override:

{
  name: 'website',
  type: 'text',
  custom: {
    openapi: { format: 'uri', example: 'https://example.com' },
  },
}

{
  name: 'legacyField',
  type: 'text',
  custom: {
    openapi: { deprecated: true },
  },
}

{
  name: 'phone',
  type: 'text',
  custom: {
    openapi: {
      format: 'phone',
      pattern: '^\\+[1-9]\\d{1,14}$',
      example: '+14155552671',
    },
  },
}

// The plugin infers `string` for a text field. If your hooks store
// structured data instead, override the inferred type entirely:
{
  name: 'coordinates',
  type: 'json',
  custom: {
    openapi: {
      type: 'object',
      properties: {
        lat: { type: 'number' },
        lng: { type: 'number' },
      },
      required: ['lat', 'lng'],
    },
  },
}

Fields nested in row, tabs, and other layout fields are annotated the same way — the plugin flattens layout fields when it looks for custom.openapi.

Localized strings

description, title, and summary under custom.openapi are localizable. Give them a function or a locale-keyed object instead of a plain string, and they resolve against the request language — the same way Payload labels do:

const slug: Field = {
  name: 'slug',
  type: 'text',
  custom: {
    openapi: {
      description: ({ t }) => t('fields:slugHelp'),
    },
  },
}

const phone: Field = {
  name: 'phone',
  type: 'text',
  custom: {
    openapi: {
      description: {
        en: 'E.164 formatted phone number',
        de: 'Telefonnummer im E.164-Format',
      },
    },
  },
}

The function receives { t, i18n } for the active request language. A locale map is any object whose keys are your project’s locales and whose values are strings. Resolution happens per request: GET /api/openapi.json?lang=de returns the German descriptions. See i18n for how the language is picked.

Only description, title, and summary are treated this way. Other keys keep their values as-is, so an object under properties named en is never mistaken for a locale map.

Entity-level metadata

Collections and globals accept a custom.openapi key too. At the entity level the plugin reads security — a per-operation override of the automatic public/secured marking:

collections/Posts.ts

export const Posts: CollectionConfig = {
  slug: 'posts',
  custom: {
    openapi: {
      // Reads are public; every write shows a padlock.
      security: { read: true, create: false, update: false, delete: false },
    },
  },
  fields: [
    /* … */
  ],
}

Pass a boolean to mark every operation at once, or a partial { read, create, update, delete } map. See Security marking for how this interacts with the access-function probe and securityWhen. The title and description shown on an entity’s tag in the docs UI come from Payload’s own config: the tag description is the collection’s or global’s admin.description, which is also resolved against the request language.

Security marking

How operations get their public/secured marking and every way to override it.

Custom endpoints

The same custom.openapi convention on endpoints, as a full Operation Object.

Documentation

Configuration

CLI

Guides

Reference

Annotating a field

Localized strings

Entity-level metadata

Security marking

Custom endpoints

​Annotating a field

​Localized strings

​Entity-level metadata

​Related

Security marking

Custom endpoints

Annotating a field

Localized strings

Entity-level metadata

Related