fix jsdocs

docs: fix draft docs and jsdocs for payload.create draft argument
2025-04-01 16:20:51 -06:00 · 2025-04-01 16:11:59 -06:00
2 changed files with 10 additions and 5 deletions
--- a/docs/versions/drafts.mdx
+++ b/docs/versions/drafts.mdx
@@ -49,17 +49,21 @@ Within the Admin UI, if drafts are enabled, a document can be shown with one of
  specify if you are interacting with drafts or with live documents.
 </Banner>

-#### Updating or creating drafts
+#### Updating drafts

-If you enable drafts on a collection or global, the `create` and `update` operations for REST, GraphQL, and Local APIs expose a new option called `draft` which allows you to specify if you are creating or updating a **draft**, or if you're just sending your changes straight to the published document. For example, if you pass the query parameter `?draft=true` to a REST `create` or `update` operation, your action will be treated as if you are creating a `draft` and not a published document. By default, the `draft` argument is set to `false`.
+If you enable drafts on a collection or global, the `update` operation for REST, GraphQL, and Local APIs exposes a new option called `draft` which allows you to specify if you are updating a **draft**, or if you're just sending your changes straight to the published document. For example, if you pass the query parameter `?draft=true` to a REST `update` operation, your action will be treated as if you are updating a `draft` and not a published document. By default, the `draft` argument is set to `false`.

 **Required fields**

-If `draft` is enabled while creating or updating a document, all fields are considered as not required, so that you can save drafts that are incomplete.
+If `draft` is enabled while updating a document, all fields are considered as not required, so that you can save drafts that are incomplete.
+
+#### Creating drafts
+
+By default, draft-enabled collections will create draft documents when you create a new document. In order to create a published document, you need to pass `_status: 'published'` to the document data.

 #### Reading drafts vs. published documents

-In addition to the `draft` argument within `create` and `update` operations, a `draft` argument is also exposed for `find` and `findByID` operations.
+In addition to the `draft` argument within `update` operations, a `draft` argument is also exposed for `find` and `findByID` operations.

 If `draft` is set to `true` while reading a document, **Payload will automatically replace returned document(s) with their newest drafts** if any newer drafts are available.

--- a/packages/payload/src/collections/operations/local/create.ts
+++ b/packages/payload/src/collections/operations/local/create.ts
@@ -56,7 +56,8 @@ export type Options<TSlug extends CollectionSlug, TSelect extends SelectType> =
   */
  disableVerificationEmail?: boolean
  /**
-   * Create a **draft** document. [More](https://payloadcms.com/docs/versions/drafts#draft-api)
+   * @deprecated this property has no effect on the published status of the created document. It will only control whether validation runs or not. In order to control the draft status of the document, you can pass _status: 'draft' or _status: 'published' in the data object.
+   * By default, draft-enabled collections will create documents with _status: 'draft'.
   */
  draft?: boolean
  /**
Author	SHA1	Message	Date
Alessio Gravili	6562f08f8a	fix jsdocs	2025-04-01 16:20:51 -06:00
Alessio Gravili	51a1ce36e1	docs: fix draft docs and jsdocs for payload.create draft argument	2025-04-01 16:11:59 -06:00