From b32affb7e897858d9678eb032d61cfb25d229882 Mon Sep 17 00:00:00 2001 From: Alvaro Saburido Date: Mon, 23 Mar 2026 14:17:43 +0100 Subject: [PATCH 1/5] Update documentation to include 'archived' field in collections guide (#577) --- content/guides/01.data-model/1.collections.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/guides/01.data-model/1.collections.md b/content/guides/01.data-model/1.collections.md index 893e4a9b..98a1e4f9 100644 --- a/content/guides/01.data-model/1.collections.md +++ b/content/guides/01.data-model/1.collections.md @@ -35,7 +35,7 @@ The primary key field contains a unique value for each item in the collection. T The primary key type defines the strategy for creating unique primary keys. Once selected, this cannot be modified. -Additionally, Directus can create some common fields, including a status field, sort, as well as fields related to who and when items are created or edited. Directus supports the following types of IDs: +Additionally, Directus can create some common fields, including an archived field, sort, as well as fields related to who and when items are created or edited. Directus supports the following types of IDs: - **Auto-Incremented Integer**: IDs increment from `1` to `2^31-1` (`2,147,483,647`). - **Auto-Incremented Big Integer**: IDs increment from `1` to `2^63-1` (`9,223,372,036,854,775,807`). This is only available if using MySQL and PostgreSQL as your database. @@ -124,6 +124,8 @@ When you duplicate an item, any related items are not copied. You must create ne Archived items still exist in your collections, but are filtered within the Data Studio. If not selected as an optional field when creating a collection, you will need to create a new field. +When creating a collection via the wizard, the optional `archived` field is a **boolean** type. The archive value is `true` and the unarchive value is `false`. If you create an archive field manually, you can use any string or boolean field. + To configure an archive field, set the following four input fields as desired. - **Archive Field**: selects the archive field. From e5b146a0628bb21876e93e71bf96345c60c41ceb Mon Sep 17 00:00:00 2001 From: Alvaro Saburido Date: Mon, 23 Mar 2026 14:18:11 +0100 Subject: [PATCH 2/5] Update content versioning terminology from 'main' to 'published' (#596) Update content versioning terminology and clarify reserved keys in documentation - Changed references from "main" to "published" for consistency across versioning concepts. - Added clarification on reserved version keys and their usage in API queries. - Updated examples and instructions to reflect the new terminology and ensure accurate guidance for users. --- .../guides/02.content/6.content-versioning.md | 35 +++++++++++-------- .../8.visual-editor/2.studio-module.md | 12 +++---- .../guides/04.connect/3.query-parameters.md | 5 +++ .../implementing-live-preview-in-astro.md | 2 +- 4 files changed, 32 insertions(+), 22 deletions(-) diff --git a/content/guides/02.content/6.content-versioning.md b/content/guides/02.content/6.content-versioning.md index 336c55f1..fea1d53b 100644 --- a/content/guides/02.content/6.content-versioning.md +++ b/content/guides/02.content/6.content-versioning.md @@ -10,11 +10,11 @@ use content versioning, including drafting content without publishing it, and mo ## Concepts -- **Version**: A version of an item that allows you to safely make changes without affecting the main item. Versions can be promoted to become the new main item. -- **Main**: The published version of your content that is live and visible to users. All new versions are created from the main item. -- **Draft**: a reserved global version that is automatically available when content versioning is enabled. The draft version provides a dedicated workspace for making changes before publishing to main, and appears empty until edits are saved. -- **Promote**: when a version is promoted, it becomes the main item that is displayed to users. -- **Revision**: revisions are individual changes to items made within a version or main item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state. +- **Version**: A version of an item that allows you to safely make changes without affecting the published item. Versions can be promoted to become the new published item. +- **Published**: The published version of your content that is live and visible to users. All new versions are created from the published item. This version is identified by the reserved key `published` (the key `main` also works and is kept for backward compatibility). +- **Draft**: a reserved global version that is automatically available when content versioning is enabled. The draft version provides a dedicated workspace for making changes before publishing, and appears empty until edits are saved. +- **Promote**: when a version is promoted, it becomes the published item that is displayed to users. +- **Revision**: revisions are individual changes to items made within a version or the published item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state. ::callout{icon="material-symbols:info-outline" to="/guides/content/live-preview"} **Using Versions in Live Preview** @@ -41,6 +41,11 @@ The draft version: - Transforms from a virtual placeholder to an actual version when you save changes - Uses "**draft**" as a reserved version key that cannot be used for custom versions +::callout{icon="material-symbols:info-outline"} +**Reserved version keys** +The keys `published`, `main`, and `draft` are all reserved and cannot be used for custom versions. Attempting to create a version with any of these keys returns a `400` error. +:: + ::callout{icon="material-symbols:warning"} **Backward Compatibility** The reserved global "draft" version was introduced in Directus 11.16.0. If you have an existing version with the key `draft` and a custom name other than "Draft", the display name will be standardized to "Draft" (i.e. transformed) to support the new global versioning feature. The version content and functionality remain unchanged. @@ -50,21 +55,21 @@ The reserved global "draft" version was introduced in Directus 11.16.0. If you h The Visual Editor integrates seamlessly with the draft version, allowing you to preview and edit changes in context: -1. **Switch versions** using the dropdown in the Visual Editor header to toggle between "Main" and "Draft" +1. **Switch versions** using the dropdown in the Visual Editor header to toggle between "Published" and "Draft" 2. **Edit items** that have content in the active version – items are only directly editable when they exist in the selected version -3. **Preview changes** using the version-aware preview URL before publishing to main -4. **Fallback behavior** - items without content in the selected version display their main version content (read-only) +3. **Preview changes** using the version-aware preview URL before publishing +4. **Fallback behavior** - items without content in the selected version display their published version content (read-only) ## Creating a New Version ![Creating a new version in the content module](/img/versions-example.png) -Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the main Content Version displayed as "main". Select "Create Version" and provide a key and a name for the new version. You can then save your new version. +Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the published content version displayed as "Published". Select "Create Version" and provide a key and a name for the new version. You can then save your new version. ::callout{icon="material-symbols:info-outline"} **Version Source** -All new versions originate from the main item. This implies that the main item acts as the single source of truth for other versions. The draft version is always available and doesn't need to be manually created. +All new versions originate from the published item. This implies that the published item acts as the single source of truth for other versions. The draft version is always available and doesn't need to be manually created. :: ## Making Changes to a Version @@ -80,19 +85,19 @@ Upon saving the changes, you'll notice that the main item remains unaffected, wh ![Promoting a version, comparing its changes](/img/versions-example-comparison.png) -Promoting a version makes it the main (current) version of your content. +Promoting a version makes it the published (current) version of your content. ### How to Promote a Version 1. Open the version you want to promote 2. Select the **"Promote Version"** option from the dropdown. 3. In the comparison modal, review the changes: - - Fields with differences from the main item are highlighted with color indicators + - Fields with differences from the published item are highlighted with color indicators - Review each highlighted field to understand what will change 4. Accept or reject individual changes as needed 5. Click **"Promote"** to finalize and make this version the new main item -Once promoted, this version becomes the active content, and the previous main item is preserved in the version history. +Once promoted, this version becomes the active content, and the previous published item is preserved in the version history. After promoting a version, you can choose to keep or delete the version. For the global draft version, you'll see options to "Discard Edits" or "Keep Edits" instead of "Delete Version" or "Keep Version". @@ -184,7 +189,7 @@ When working with content versioning through the API, it's important to understa ### Standard Item Response -When fetching items from a collection endpoint `/items/{collection}`, you receive the main version data: +When fetching items from a collection endpoint `/items/{collection}`, you receive the published version data: ```json { "data": [ @@ -223,4 +228,4 @@ When fetching versions from the `/versions/{version}` endpoint, each version con } ``` -The `delta` object contains only the modified fields, making it easy to see exactly what changed in each version compared to the state of main at the time that version was created. +The `delta` object contains only the modified fields, making it easy to see exactly what changed in each version compared to the published item at the time that version was created. diff --git a/content/guides/02.content/8.visual-editor/2.studio-module.md b/content/guides/02.content/8.visual-editor/2.studio-module.md index ce5741e9..7e7f792e 100644 --- a/content/guides/02.content/8.visual-editor/2.studio-module.md +++ b/content/guides/02.content/8.visual-editor/2.studio-module.md @@ -27,7 +27,7 @@ The URL field supports a `{{$version}}` template variable. When included, the Vi https://your-site.com/preview?version={{$version}} ``` - - **Resolution**: When no version is selected, `{{$version}}` resolves to `main`. + - **Resolution**: When no version is selected, `{{$version}}` resolves to `published`. - **Flexibility**: The variable can be placed in any part of the URL (query parameters, path segments, subdomains, or hash fragments). #### Implementation Checklist @@ -37,7 +37,7 @@ https://your-site.com/preview?version={{$version}} **1. Frontend Integration** - **Template Variable**: You must include `{{$version}}` in the URL field. If omitted, the version selection dropdown will not appear in the Visual Editor toolbar. - **Directus Frontend Library**: Your website must be configured using our publicly available [Frontend Library](1.frontend-library.md). - - **Version-Aware Fetching**: Your code must detect the version parameter from the URL and pass it to the Directus API (e.g., `/items/posts/42?version=draft`). Without this, the site will continue to display "Main" content regardless of your selection. + - **Version-Aware Fetching**: Your code must detect the version parameter from the URL and pass it to the Directus API (e.g., `/items/posts/42?version=draft`). Without this, the site will continue to display "Published" content regardless of your selection. **2. Environment Configuration** @@ -86,18 +86,18 @@ When a URL includes the `{{$version}}` variable, a version dropdown appears in t The dropdown lists: -- **Main** — the published version (default) +- **Published** — the published version (default) - **Draft** — the global [draft version](/guides/content/content-versioning#working-with-the-draft-version), always available for collections with versioning enabled -If your website URL contains a version key that doesn't match "main" or "draft" (e.g. from a custom query parameter), it will also appear as a dynamic option in the dropdown. +If your website URL contains a version key that doesn't match "published", "main", or "draft" (e.g. from a custom query parameter), it will also appear as a dynamic option in the dropdown. ### Version-Aware Editing -When a version other than main is selected: +When a version other than "Published" is selected: - **Only items on collections with versioning enabled** will show editable elements. Items on non-versioned collections are hidden from editing. - **Saving an edit** creates or updates the version for that specific item. If the version doesn't exist yet for the item, it's created automatically on save. -- **Items without content in the selected version** display their main version content as a read-only fallback. +- **Items without content in the selected version** display their published version content as a read-only fallback. ::callout{icon="material-symbols:info-outline"} The version dropdown requires the user to have **read** permission on `directus_versions`. Editing in a version additionally requires **create** or **update** permission on `directus_versions`. diff --git a/content/guides/04.connect/3.query-parameters.md b/content/guides/04.connect/3.query-parameters.md index bc18b546..1af8e34f 100644 --- a/content/guides/04.connect/3.query-parameters.md +++ b/content/guides/04.connect/3.query-parameters.md @@ -537,6 +537,11 @@ Saves the API response to a file. Valid values are `csv`, `json`, `xml`, `yaml`. Queries a version of a record by version key when [content versioning](/guides/content/content-versioning) is enabled on a collection. Applies only to single item retrieval. +::callout{icon="material-symbols:info-outline"} +**Reserved version keys** +The keys `published` and `draft` are reserved. Use `published` (or `main` for backward compatibility) to explicitly fetch the published base item. Use `draft` to fetch the global draft version. +:: + ```http [GET /items/posts/1] ?version=v1 ``` diff --git a/content/tutorials/1.getting-started/implementing-live-preview-in-astro.md b/content/tutorials/1.getting-started/implementing-live-preview-in-astro.md index 59955c54..11a5b567 100644 --- a/content/tutorials/1.getting-started/implementing-live-preview-in-astro.md +++ b/content/tutorials/1.getting-started/implementing-live-preview-in-astro.md @@ -282,7 +282,7 @@ Next, update the Directus live preview URL pattern to include the version. The U ## Testing Live Preview To test the live preview, navigate to the `http://localhost:4321/` page and click on any of the posts. You will be redirected to the post page, and the post content will be displayed. -At the end of the URL, add `?preview=true&token=YOUR_GENERATED_TOKEN&version=main` to view the post in preview mode. +At the end of the URL, add `?preview=true&token=YOUR_GENERATED_TOKEN&version=published` to view the post in preview mode. This should provide you with a preview of the post content that looks like the image below: From 1a86d2cda20391129fb583bbb74dd9c54e5b841b Mon Sep 17 00:00:00 2001 From: Alvaro Saburido Date: Mon, 23 Mar 2026 14:19:48 +0100 Subject: [PATCH 3/5] Clarify required field validation in content versioning (#600) Enhance content versioning guide with information on required fields (#599) Added a note clarifying that versions can be saved with empty required fields, deferring validation to allow for partial drafts. Updated the promotion process to include validation error handling for empty fields before finalizing a version. --- content/guides/02.content/6.content-versioning.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/content/guides/02.content/6.content-versioning.md b/content/guides/02.content/6.content-versioning.md index fea1d53b..de7b83eb 100644 --- a/content/guides/02.content/6.content-versioning.md +++ b/content/guides/02.content/6.content-versioning.md @@ -80,6 +80,11 @@ Open the item in the newly created version, and make the desired edits to the it Upon saving the changes, you'll notice that the main item remains unaffected, while the changes are reflected only in the modified version. +::callout{icon="material-symbols:info-outline"} +**Required Fields** +Versions can be saved even if required fields are empty. Validation of required fields is deferred to promote time, so you can save partial drafts without completing all required fields. +:: + ## Comparing and Promoting a Version ![Promoting a version, comparing its changes](/img/versions-example-comparison.png) @@ -90,12 +95,12 @@ Promoting a version makes it the published (current) version of your content. ### How to Promote a Version 1. Open the version you want to promote -2. Select the **"Promote Version"** option from the dropdown. +2. Select the **"Promote Version"** option from the dropdown. 3. In the comparison modal, review the changes: - Fields with differences from the published item are highlighted with color indicators - Review each highlighted field to understand what will change 4. Accept or reject individual changes as needed -5. Click **"Promote"** to finalize and make this version the new main item +5. Click **"Promote"** to finalize and make this version the new main item. If any required fields are empty, validation errors are shown at this point - fill in the missing fields before promoting Once promoted, this version becomes the active content, and the previous published item is preserved in the version history. From c862d1a7cbb5bc6088fc714962ef3ea325439cd9 Mon Sep 17 00:00:00 2001 From: Alvaro Saburido Date: Mon, 23 Mar 2026 14:20:11 +0100 Subject: [PATCH 4/5] docs: add itemless draft creation flow to content versioning guide (#604) * Enhance content versioning guide with information on required fields (#599) Added a note clarifying that versions can be saved with empty required fields, deferring validation to allow for partial drafts. Updated the promotion process to include validation error handling for empty fields before finalizing a version. * Add draft item creation process to content versioning guide --- .../guides/02.content/6.content-versioning.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/content/guides/02.content/6.content-versioning.md b/content/guides/02.content/6.content-versioning.md index de7b83eb..b3f73938 100644 --- a/content/guides/02.content/6.content-versioning.md +++ b/content/guides/02.content/6.content-versioning.md @@ -61,6 +61,27 @@ The Visual Editor integrates seamlessly with the draft version, allowing you to 4. **Fallback behavior** - items without content in the selected version display their published version content (read-only) +## Creating New Items as Drafts + +In a versioned collection, clicking **"Create Item"** (the `+` button) automatically puts you into draft context. Instead of creating the item immediately, Directus opens the form in the draft version - no published item exists yet. + +### Saving an Itemless Draft + +Fill in your fields and save as normal. On first save, Directus creates a draft version with no published item backing it. The item does not yet exist in the collection. + +You can save as many times as needed. Required fields do not need to be complete at this stage - see [Making Changes to a Version](#making-changes-to-a-version). + +### Publishing via Promote + +When you are ready to publish, select **"Promote Version"** from the version dropdown. Because there is no existing item to compare against, Directus skips the comparison modal and creates the item directly. + +After promotion, you are redirected to the newly created item in its main version. + +::callout{icon="material-symbols:info-outline"} +**Permissions** +Promoting an itemless draft creates a new item, so it requires **create** permission on the collection - not edit permission. +:: + ## Creating a New Version ![Creating a new version in the content module](/img/versions-example.png) From 6300b342d7b78aa4ac0b972413a009eac80b9e1f Mon Sep 17 00:00:00 2001 From: alvarosabu Date: Mon, 23 Mar 2026 14:26:21 +0100 Subject: [PATCH 5/5] Add content versioning guide with required field validation details CMS-1992 --- content/guides/02.content/6.content-versioning.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/content/guides/02.content/6.content-versioning.md b/content/guides/02.content/6.content-versioning.md index b3f73938..13edc969 100644 --- a/content/guides/02.content/6.content-versioning.md +++ b/content/guides/02.content/6.content-versioning.md @@ -117,11 +117,17 @@ Promoting a version makes it the published (current) version of your content. 1. Open the version you want to promote 2. Select the **"Promote Version"** option from the dropdown. + +::callout{icon="material-symbols:warning"} +**Required Field Validation** +If the version has missing required fields, Directus will display field-level validation errors and a notice banner. The comparison modal will not open until all required fields are filled in. +:: + 3. In the comparison modal, review the changes: - Fields with differences from the published item are highlighted with color indicators - Review each highlighted field to understand what will change 4. Accept or reject individual changes as needed -5. Click **"Promote"** to finalize and make this version the new main item. If any required fields are empty, validation errors are shown at this point - fill in the missing fields before promoting +5. Click **"Promote"** to finalize and make this version the new main item. Once promoted, this version becomes the active content, and the previous published item is preserved in the version history.