English for Payload CMS Developers

Payload CMS is code-first — schemas, permissions, and business logic all live in TypeScript rather than a visual admin builder — which means discussing it well requires precise terms for collections, fields, and hooks. Vague language like “the content thing” or “the permission stuff” slows down code review on a Payload codebase. This guide covers the vocabulary developers need.

Key Vocabulary

Collection — a Payload construct defining a content type (like Posts or Users), configured as a TypeScript object with fields, access control, and hooks. “We need a new field on the Products collection to store the SKU, not a whole new collection.”

Field — a single piece of data within a collection, with a type (text, relationship, richText, array) and its own validation rules. “The relationship field on Posts links to the Authors collection so we can populate the author’s name at query time.”

Access control function — a function attached to a collection or field that returns true or false to determine whether a given user can read, create, update, or delete a document. “The access control function checks req.user.role and only allows editors to publish, not just save a draft.”

Hook — a function that runs at a specific point in a document’s lifecycle (beforeChange, afterChange, beforeRead), used for side effects like sending notifications or transforming data. “We added an afterChange hook that triggers a Slack notification whenever a post’s status changes to published.”

Local API — Payload’s server-side API for querying and mutating data directly in Node.js code, bypassing HTTP, used in scripts, hooks, and server components. “Instead of calling our own REST endpoint from the server, we use the local API directly — it’s faster and skips the network round trip.”

Live Preview — a Payload feature that renders a draft document in an iframe in real time as an editor types, without requiring a publish first. “Live Preview lets the marketing team see exactly how the landing page will look before they hit publish.”

Common Phrases

• “Should this be a new field on the existing collection, or does it need its own collection?”
• “Is the access control function scoped per-field, or does it apply to the whole collection?”
• “Which hook should run this — beforeChange so we can still modify the data, or afterChange since it’s just a side effect?”
• “Are we calling this through the REST API or the local API? That changes the auth context.”
• “Does Live Preview need a special route to render the draft correctly?”

Example Sentences

Explaining a schema decision in a design review: “We modeled Testimonials as its own collection instead of an array field on Pages, because we want testimonials to be reusable across multiple pages, not duplicated per page.”

Reporting a bug: “The afterChange hook is firing twice on save — it looks like it’s also triggering on the autosave draft, not just the final publish.”

Discussing permissions with a teammate: “The access control function is returning true for all authenticated users right now, but we actually want to restrict delete access to admins only — let’s scope that down before this ships.”

Professional Tips

• Say “collection” and “field” precisely, matching Payload’s own terminology, rather than generic CMS words like “content type” or “attribute” — it keeps code review comments unambiguous.
• When describing a bug in lifecycle logic, name the specific hook (beforeChange, afterChange, beforeValidate) rather than saying “the save logic,” since each hook runs at a different point.
• Distinguish the local API from the REST API when explaining performance — the local API skips HTTP entirely and is the right choice inside hooks and scripts.
• Clarify whether an access rule is a collection-level or field-level access control function, since they can be layered and the more restrictive one wins.

Practice Exercise

1. Explain in two sentences why an access control function is more flexible than a static role list.
2. Write a one-sentence bug report about a hook firing at the wrong point in a document’s lifecycle.
3. Describe, in your own words, when you’d use the local API instead of the REST API in a Payload project.