From d771b545c7d35539b17b1f41170b1aa40a21d9fd Mon Sep 17 00:00:00 2001
From: Katharina Przybill <30441792+kathap@users.noreply.github.com>
Date: Thu, 29 Oct 2026 09:54:09 +0100
Subject: [PATCH 1/4] Allow updating stack description via PATCH
 /v3/stacks/:guid
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This adds an optional `description` parameter
to PATCH /v3/stacks/:guid so a stack's description can be changed after
creation — e.g. to mark a newly introduced stack as "preview".

Validation: when provided, description must be non-empty and <= 250
characters. The create message is tightened to match,
POST and PATCH now behave identically for description:
  - Omitted → allowed (comes from cf-deployment)
  - Non-empty, ≤250 → allowed
  - "", whitespace-only, or null → 422 rejected
  - >250 → rejected
---
 app/actions/stack_update.rb                   |  1 +
 app/messages/stack_create_message.rb          |  6 +-
 app/messages/stack_update_message.rb          |  7 +-
 spec/request/stacks_spec.rb                   | 17 +++++
 spec/unit/actions/stack_update_spec.rb        | 22 ++++++
 .../messages/stack_create_message_spec.rb     | 35 +++++++++
 .../messages/stack_update_message_spec.rb     | 73 +++++++++++++++++++
 7 files changed, 159 insertions(+), 2 deletions(-)

diff --git a/app/actions/stack_update.rb b/app/actions/stack_update.rb
index 5d373c09bc2..8adc8e9f1e5 100644
--- a/app/actions/stack_update.rb
+++ b/app/actions/stack_update.rb
@@ -15,6 +15,7 @@ def update(stack, message)
         stack_updates = {}
         stack_updates[:state] = message.state if message.requested?(:state)
         stack_updates[:state_reason] = message.state_reason if message.state_reason_requested?
+        stack_updates[:description] = message.description if message.description_requested?
         stack.update(stack_updates) if stack_updates.any?
 
         MetadataUpdate.update(stack, message)
diff --git a/app/messages/stack_create_message.rb b/app/messages/stack_create_message.rb
index 9c08739142c..e5104822716 100644
--- a/app/messages/stack_create_message.rb
+++ b/app/messages/stack_create_message.rb
@@ -6,7 +6,7 @@ class StackCreateMessage < MetadataBaseMessage
     register_allowed_keys %i[name description state state_reason]
 
     validates :name, presence: true, length: { maximum: 250 }
-    validates :description, length: { maximum: 250 }
+    validates :description, presence: true, length: { maximum: 250 }, if: :description_requested?
     validates :state, inclusion: { in: StackStates::VALID_STATES, message: "must be one of #{StackStates::VALID_STATES.join(', ')}" }, allow_nil: false, if: :state_requested?
     validates :state_reason, length: { maximum: 5000 }, allow_nil: true
 
@@ -14,6 +14,10 @@ def state_requested?
       requested?(:state)
     end
 
+    def description_requested?
+      requested?(:description)
+    end
+
     def state
       return @state if defined?(@state)
 
diff --git a/app/messages/stack_update_message.rb b/app/messages/stack_update_message.rb
index 57afeea42c1..18c225c419b 100644
--- a/app/messages/stack_update_message.rb
+++ b/app/messages/stack_update_message.rb
@@ -3,11 +3,12 @@
 
 module VCAP::CloudController
   class StackUpdateMessage < MetadataBaseMessage
-    register_allowed_keys %i[state state_reason]
+    register_allowed_keys %i[state state_reason description]
 
     validates_with NoAdditionalKeysValidator
     validates :state, inclusion: { in: StackStates::VALID_STATES, message: "must be one of #{StackStates::VALID_STATES.join(', ')}" }, allow_nil: false, if: :state_requested?
     validates :state_reason, length: { maximum: 5000 }, allow_nil: true
+    validates :description, presence: true, length: { maximum: 250 }, if: :description_requested?
 
     def state_requested?
       requested?(:state)
@@ -16,5 +17,9 @@ def state_requested?
     def state_reason_requested?
       requested?(:state_reason)
     end
+
+    def description_requested?
+      requested?(:description)
+    end
   end
 end
diff --git a/spec/request/stacks_spec.rb b/spec/request/stacks_spec.rb
index acff9384930..a1b6ffd95b7 100644
--- a/spec/request/stacks_spec.rb
+++ b/spec/request/stacks_spec.rb
@@ -763,6 +763,23 @@
         }
       )
     end
+
+    it 'updates the description of a stack' do
+      patch "/v3/stacks/#{stack.guid}", { description: 'Preview stack, do not use in production' }.to_json, headers
+
+      expect(last_response.status).to eq(200)
+      expect(parsed_response['description']).to eq('Preview stack, do not use in production')
+
+      stack.reload
+      expect(stack.description).to eq('Preview stack, do not use in production')
+    end
+
+    it 'returns 422 when description is empty' do
+      patch "/v3/stacks/#{stack.guid}", { description: '' }.to_json, headers
+
+      expect(last_response.status).to eq(422)
+      expect(last_response).to have_error_message("Description can't be blank")
+    end
   end
 
   describe 'DELETE /v3/stacks/:guid' do
diff --git a/spec/unit/actions/stack_update_spec.rb b/spec/unit/actions/stack_update_spec.rb
index bc3e6d4691c..cec0fb0e5d8 100644
--- a/spec/unit/actions/stack_update_spec.rb
+++ b/spec/unit/actions/stack_update_spec.rb
@@ -95,5 +95,27 @@ module VCAP::CloudController
         expect(stack.state_reason).to eq('Existing reason')
       end
     end
+
+    context 'when updating description' do
+      let(:stack) { create(:stack, description: 'Original description') }
+
+      it 'updates description when provided' do
+        message = StackUpdateMessage.new({ description: 'Preview stack' })
+
+        stack_update.update(stack, message)
+        stack.reload
+
+        expect(stack.description).to eq('Preview stack')
+      end
+
+      it 'preserves description when not requested' do
+        message = StackUpdateMessage.new({ state: 'RESTRICTED' })
+
+        stack_update.update(stack, message)
+        stack.reload
+
+        expect(stack.description).to eq('Original description')
+      end
+    end
   end
 end
diff --git a/spec/unit/messages/stack_create_message_spec.rb b/spec/unit/messages/stack_create_message_spec.rb
index aadf7b9191b..90eabb78e6b 100644
--- a/spec/unit/messages/stack_create_message_spec.rb
+++ b/spec/unit/messages/stack_create_message_spec.rb
@@ -64,6 +64,14 @@
     end
 
     describe 'description' do
+      context 'when it is not provided' do
+        let(:params) { valid_params }
+
+        it 'is valid' do
+          expect(subject).to be_valid
+        end
+      end
+
       context 'when it is just long enough' do
         let(:params) { valid_params.merge({ description: 'A' * MAX_DESCRIPTION_LENGTH }) }
 
@@ -80,6 +88,33 @@
           expect(subject.errors[:description]).to eq ["is too long (maximum is #{MAX_DESCRIPTION_LENGTH} characters)"]
         end
       end
+
+      context 'when it is an empty string' do
+        let(:params) { valid_params.merge({ description: '' }) }
+
+        it 'returns an error' do
+          expect(subject).not_to be_valid
+          expect(subject.errors[:description]).to include("can't be blank")
+        end
+      end
+
+      context 'when it is only whitespace' do
+        let(:params) { valid_params.merge({ description: '   ' }) }
+
+        it 'returns an error' do
+          expect(subject).not_to be_valid
+          expect(subject.errors[:description]).to include("can't be blank")
+        end
+      end
+
+      context 'when it is explicitly null' do
+        let(:params) { valid_params.merge({ description: nil }) }
+
+        it 'returns an error' do
+          expect(subject).not_to be_valid
+          expect(subject.errors[:description]).to include("can't be blank")
+        end
+      end
     end
 
     describe 'state' do
diff --git a/spec/unit/messages/stack_update_message_spec.rb b/spec/unit/messages/stack_update_message_spec.rb
index a069f73d470..a5cca4064fb 100644
--- a/spec/unit/messages/stack_update_message_spec.rb
+++ b/spec/unit/messages/stack_update_message_spec.rb
@@ -120,5 +120,78 @@
         end
       end
     end
+
+    describe 'description' do
+      MAX_DESCRIPTION_LENGTH = 250
+
+      context 'when it is not provided' do
+        let(:params) { valid_params }
+
+        it 'is valid' do
+          expect(subject).to be_valid
+        end
+
+        it 'reports description not requested' do
+          expect(subject.description_requested?).to be false
+        end
+      end
+
+      context 'when it is provided' do
+        let(:params) { valid_params.merge({ description: 'Preview stack, do not use in production' }) }
+
+        it 'is valid' do
+          expect(subject).to be_valid
+          expect(subject.description).to eq('Preview stack, do not use in production')
+        end
+
+        it 'reports description requested' do
+          expect(subject.description_requested?).to be true
+        end
+      end
+
+      context 'when it is at maximum length' do
+        let(:params) { valid_params.merge({ description: 'A' * MAX_DESCRIPTION_LENGTH }) }
+
+        it 'is valid' do
+          expect(subject).to be_valid
+        end
+      end
+
+      context 'when it exceeds maximum length' do
+        let(:params) { valid_params.merge({ description: 'A' * (MAX_DESCRIPTION_LENGTH + 1) }) }
+
+        it 'returns an error' do
+          expect(subject).not_to be_valid
+          expect(subject.errors[:description]).to eq ["is too long (maximum is #{MAX_DESCRIPTION_LENGTH} characters)"]
+        end
+      end
+
+      context 'when it is an empty string' do
+        let(:params) { valid_params.merge({ description: '' }) }
+
+        it 'returns an error' do
+          expect(subject).not_to be_valid
+          expect(subject.errors[:description]).to include("can't be blank")
+        end
+      end
+
+      context 'when it is only whitespace' do
+        let(:params) { valid_params.merge({ description: '   ' }) }
+
+        it 'returns an error' do
+          expect(subject).not_to be_valid
+          expect(subject.errors[:description]).to include("can't be blank")
+        end
+      end
+
+      context 'when it is explicitly null' do
+        let(:params) { valid_params.merge({ description: nil }) }
+
+        it 'returns an error' do
+          expect(subject).not_to be_valid
+          expect(subject.errors[:description]).to include("can't be blank")
+        end
+      end
+    end
   end
 end

From f9f0d98769cf377d6526d5c4da03507847989c64 Mon Sep 17 00:00:00 2001
From: Katharina Przybill <30441792+kathap@users.noreply.github.com>
Date: Thu, 29 Oct 2026 10:02:13 +0100
Subject: [PATCH 2/4] Adapt docs

---
 .../components/requestBodies/StackCreateRequestBody.yaml     | 4 ++--
 docs/openapi/apis/cf/latest/paths/Stacks.yaml                | 5 +++++
 docs/v3/source/includes/resources/stacks/_create.md.erb      | 2 +-
 docs/v3/source/includes/resources/stacks/_update.md.erb      | 3 ++-
 4 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
index 758be34716b..843236a9681 100644
--- a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
+++ b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
@@ -10,8 +10,8 @@ content:
           description: Name of the stack; must be unique and no longer than 250 characters
           maxLength: 250
         description:
-          type: [string, "null"]
-          description: Description of the stack; must no longer than 250 characters
+          type: string
+          description: Description of the stack; must be non-empty and no longer than 250 characters
           maxLength: 250
         metadata:
           $ref: '../schemas/Metadata.yaml'
diff --git a/docs/openapi/apis/cf/latest/paths/Stacks.yaml b/docs/openapi/apis/cf/latest/paths/Stacks.yaml
index c69c09e0e66..74e230a5b19 100644
--- a/docs/openapi/apis/cf/latest/paths/Stacks.yaml
+++ b/docs/openapi/apis/cf/latest/paths/Stacks.yaml
@@ -153,6 +153,10 @@
         application/json:
           schema:
             properties:
+              description:
+                type: string
+                description: Description of the stack; must be non-empty and no longer than 250 characters
+                maxLength: 250
               metadata:
                 $ref: ../components/schemas/Metadata.yaml
           examples:
@@ -164,6 +168,7 @@
                     key: value
                   annotations:
                     note: detailed information
+                description: Example stack description
                 state: ACTIVE
                 state_reason: Optional plain text describing the stack state change
     responses:
diff --git a/docs/v3/source/includes/resources/stacks/_create.md.erb b/docs/v3/source/includes/resources/stacks/_create.md.erb
index e97fee9f0f0..a36a367e4f7 100644
--- a/docs/v3/source/includes/resources/stacks/_create.md.erb
+++ b/docs/v3/source/includes/resources/stacks/_create.md.erb
@@ -41,7 +41,7 @@ Name | Type | Description
 
 Name | Type | Description | Default
 ---- | ---- | ----------- | -------
-**description** | _string_ | Description of the stack; must no longer than 250 characters | `null`
+**description** | _string_ | Description of the stack; when provided, must be non-empty and no longer than 250 characters | `null`
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
diff --git a/docs/v3/source/includes/resources/stacks/_update.md.erb b/docs/v3/source/includes/resources/stacks/_update.md.erb
index e950a4c6089..be06e6ed9fe 100644
--- a/docs/v3/source/includes/resources/stacks/_update.md.erb
+++ b/docs/v3/source/includes/resources/stacks/_update.md.erb
@@ -9,7 +9,7 @@ curl "https://api.example.org/v3/stacks/[guid]" \
   -X PATCH \
   -H "Authorization: bearer [token]" \
   -H "Content-Type: application/json" \
-  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}},"state":"ACTIVE", "state_reason": "Optional plain text describing the stack state change" }'
+  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}},"description": "Example stack description", "state":"ACTIVE", "state_reason": "Optional plain text describing the stack state change" }'
 
 ```
 
@@ -31,6 +31,7 @@ Content-Type: application/json
 
 Name | Type | Description
 ---- | ---- | -----------
+**description** | _string_ | Description of the stack; must be non-empty and no longer than 250 characters
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`

From 8a79f29fce6803d39af57e66d0d8ef7357593184 Mon Sep 17 00:00:00 2001
From: Katharina Przybill <30441792+kathap@users.noreply.github.com>
Date: Fri, 30 Oct 2026 12:12:31 +0100
Subject: [PATCH 3/4] make max length 5000, let empty be valid

---
 app/actions/stack_update.rb                   |  2 +-
 app/messages/stack_create_message.rb          |  6 +----
 app/messages/stack_update_message.rb          |  6 +----
 .../requestBodies/StackCreateRequestBody.yaml |  6 ++---
 docs/openapi/apis/cf/latest/paths/Stacks.yaml |  2 +-
 .../includes/resources/stacks/_create.md.erb  |  2 +-
 .../includes/resources/stacks/_update.md.erb  |  2 +-
 spec/request/stacks_spec.rb                   |  6 ++---
 .../messages/stack_create_message_spec.rb     | 27 -------------------
 .../messages/stack_update_message_spec.rb     | 27 +++----------------
 10 files changed, 16 insertions(+), 70 deletions(-)

diff --git a/app/actions/stack_update.rb b/app/actions/stack_update.rb
index 8adc8e9f1e5..eb0c7fb6faf 100644
--- a/app/actions/stack_update.rb
+++ b/app/actions/stack_update.rb
@@ -15,7 +15,7 @@ def update(stack, message)
         stack_updates = {}
         stack_updates[:state] = message.state if message.requested?(:state)
         stack_updates[:state_reason] = message.state_reason if message.state_reason_requested?
-        stack_updates[:description] = message.description if message.description_requested?
+        stack_updates[:description] = message.description if message.requested?(:description)
         stack.update(stack_updates) if stack_updates.any?
 
         MetadataUpdate.update(stack, message)
diff --git a/app/messages/stack_create_message.rb b/app/messages/stack_create_message.rb
index e5104822716..9c08739142c 100644
--- a/app/messages/stack_create_message.rb
+++ b/app/messages/stack_create_message.rb
@@ -6,7 +6,7 @@ class StackCreateMessage < MetadataBaseMessage
     register_allowed_keys %i[name description state state_reason]
 
     validates :name, presence: true, length: { maximum: 250 }
-    validates :description, presence: true, length: { maximum: 250 }, if: :description_requested?
+    validates :description, length: { maximum: 250 }
     validates :state, inclusion: { in: StackStates::VALID_STATES, message: "must be one of #{StackStates::VALID_STATES.join(', ')}" }, allow_nil: false, if: :state_requested?
     validates :state_reason, length: { maximum: 5000 }, allow_nil: true
 
@@ -14,10 +14,6 @@ def state_requested?
       requested?(:state)
     end
 
-    def description_requested?
-      requested?(:description)
-    end
-
     def state
       return @state if defined?(@state)
 
diff --git a/app/messages/stack_update_message.rb b/app/messages/stack_update_message.rb
index 18c225c419b..59ea7ad8a7c 100644
--- a/app/messages/stack_update_message.rb
+++ b/app/messages/stack_update_message.rb
@@ -8,7 +8,7 @@ class StackUpdateMessage < MetadataBaseMessage
     validates_with NoAdditionalKeysValidator
     validates :state, inclusion: { in: StackStates::VALID_STATES, message: "must be one of #{StackStates::VALID_STATES.join(', ')}" }, allow_nil: false, if: :state_requested?
     validates :state_reason, length: { maximum: 5000 }, allow_nil: true
-    validates :description, presence: true, length: { maximum: 250 }, if: :description_requested?
+    validates :description, length: { maximum: 5000 }, allow_nil: true
 
     def state_requested?
       requested?(:state)
@@ -17,9 +17,5 @@ def state_requested?
     def state_reason_requested?
       requested?(:state_reason)
     end
-
-    def description_requested?
-      requested?(:description)
-    end
   end
 end
diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
index 843236a9681..884fa2b1c6f 100644
--- a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
+++ b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
@@ -10,9 +10,9 @@ content:
           description: Name of the stack; must be unique and no longer than 250 characters
           maxLength: 250
         description:
-          type: string
-          description: Description of the stack; must be non-empty and no longer than 250 characters
-          maxLength: 250
+          type: [string, "null"]
+          description: Description of the stack; must be no longer than 5000 characters
+          maxLength: 5000
         metadata:
           $ref: '../schemas/Metadata.yaml'
       required:
diff --git a/docs/openapi/apis/cf/latest/paths/Stacks.yaml b/docs/openapi/apis/cf/latest/paths/Stacks.yaml
index 74e230a5b19..c543b9f49e7 100644
--- a/docs/openapi/apis/cf/latest/paths/Stacks.yaml
+++ b/docs/openapi/apis/cf/latest/paths/Stacks.yaml
@@ -155,7 +155,7 @@
             properties:
               description:
                 type: string
-                description: Description of the stack; must be non-empty and no longer than 250 characters
+                description: Description of the stack; must be no longer than 5000 characters
                 maxLength: 250
               metadata:
                 $ref: ../components/schemas/Metadata.yaml
diff --git a/docs/v3/source/includes/resources/stacks/_create.md.erb b/docs/v3/source/includes/resources/stacks/_create.md.erb
index a36a367e4f7..25f3cd30f17 100644
--- a/docs/v3/source/includes/resources/stacks/_create.md.erb
+++ b/docs/v3/source/includes/resources/stacks/_create.md.erb
@@ -41,7 +41,7 @@ Name | Type | Description
 
 Name | Type | Description | Default
 ---- | ---- | ----------- | -------
-**description** | _string_ | Description of the stack; when provided, must be non-empty and no longer than 250 characters | `null`
+**description** | _string_ | Description of the stack; must be no longer than 5000 characters | `null`
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
diff --git a/docs/v3/source/includes/resources/stacks/_update.md.erb b/docs/v3/source/includes/resources/stacks/_update.md.erb
index be06e6ed9fe..db77d379225 100644
--- a/docs/v3/source/includes/resources/stacks/_update.md.erb
+++ b/docs/v3/source/includes/resources/stacks/_update.md.erb
@@ -31,7 +31,7 @@ Content-Type: application/json
 
 Name | Type | Description
 ---- | ---- | -----------
-**description** | _string_ | Description of the stack; must be non-empty and no longer than 250 characters
+**description** | _string_ | Description of the stack; must be no longer than 5000 characters
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
diff --git a/spec/request/stacks_spec.rb b/spec/request/stacks_spec.rb
index a1b6ffd95b7..370593c61f4 100644
--- a/spec/request/stacks_spec.rb
+++ b/spec/request/stacks_spec.rb
@@ -774,11 +774,11 @@
       expect(stack.description).to eq('Preview stack, do not use in production')
     end
 
-    it 'returns 422 when description is empty' do
-      patch "/v3/stacks/#{stack.guid}", { description: '' }.to_json, headers
+    it 'returns 422 when description exceeds the maximum length' do
+      patch "/v3/stacks/#{stack.guid}", { description: 'A' * 5001 }.to_json, headers
 
       expect(last_response.status).to eq(422)
-      expect(last_response).to have_error_message("Description can't be blank")
+      expect(last_response).to have_error_message('Description is too long (maximum is 5000 characters)')
     end
   end
 
diff --git a/spec/unit/messages/stack_create_message_spec.rb b/spec/unit/messages/stack_create_message_spec.rb
index 90eabb78e6b..39734560e18 100644
--- a/spec/unit/messages/stack_create_message_spec.rb
+++ b/spec/unit/messages/stack_create_message_spec.rb
@@ -88,33 +88,6 @@
           expect(subject.errors[:description]).to eq ["is too long (maximum is #{MAX_DESCRIPTION_LENGTH} characters)"]
         end
       end
-
-      context 'when it is an empty string' do
-        let(:params) { valid_params.merge({ description: '' }) }
-
-        it 'returns an error' do
-          expect(subject).not_to be_valid
-          expect(subject.errors[:description]).to include("can't be blank")
-        end
-      end
-
-      context 'when it is only whitespace' do
-        let(:params) { valid_params.merge({ description: '   ' }) }
-
-        it 'returns an error' do
-          expect(subject).not_to be_valid
-          expect(subject.errors[:description]).to include("can't be blank")
-        end
-      end
-
-      context 'when it is explicitly null' do
-        let(:params) { valid_params.merge({ description: nil }) }
-
-        it 'returns an error' do
-          expect(subject).not_to be_valid
-          expect(subject.errors[:description]).to include("can't be blank")
-        end
-      end
     end
 
     describe 'state' do
diff --git a/spec/unit/messages/stack_update_message_spec.rb b/spec/unit/messages/stack_update_message_spec.rb
index a5cca4064fb..9bdec35674c 100644
--- a/spec/unit/messages/stack_update_message_spec.rb
+++ b/spec/unit/messages/stack_update_message_spec.rb
@@ -130,10 +130,6 @@
         it 'is valid' do
           expect(subject).to be_valid
         end
-
-        it 'reports description not requested' do
-          expect(subject.description_requested?).to be false
-        end
       end
 
       context 'when it is provided' do
@@ -143,10 +139,6 @@
           expect(subject).to be_valid
           expect(subject.description).to eq('Preview stack, do not use in production')
         end
-
-        it 'reports description requested' do
-          expect(subject.description_requested?).to be true
-        end
       end
 
       context 'when it is at maximum length' do
@@ -169,27 +161,16 @@
       context 'when it is an empty string' do
         let(:params) { valid_params.merge({ description: '' }) }
 
-        it 'returns an error' do
-          expect(subject).not_to be_valid
-          expect(subject.errors[:description]).to include("can't be blank")
-        end
-      end
-
-      context 'when it is only whitespace' do
-        let(:params) { valid_params.merge({ description: '   ' }) }
-
-        it 'returns an error' do
-          expect(subject).not_to be_valid
-          expect(subject.errors[:description]).to include("can't be blank")
+        it 'is valid' do
+          expect(subject).to be_valid
         end
       end
 
       context 'when it is explicitly null' do
         let(:params) { valid_params.merge({ description: nil }) }
 
-        it 'returns an error' do
-          expect(subject).not_to be_valid
-          expect(subject.errors[:description]).to include("can't be blank")
+        it 'is valid' do
+          expect(subject).to be_valid
         end
       end
     end

From b74515f880db6dd7404a9b608665f556c5a6069f Mon Sep 17 00:00:00 2001
From: Katharina Przybill <30441792+kathap@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:04:05 +0100
Subject: [PATCH 4/4] Set description length to 250 as it was already at this
 max lenght from beginning Commit 50e9b79

---
 app/messages/stack_update_message.rb                          | 2 +-
 .../components/requestBodies/StackCreateRequestBody.yaml      | 4 ++--
 docs/openapi/apis/cf/latest/paths/Stacks.yaml                 | 2 +-
 docs/v3/source/includes/resources/stacks/_create.md.erb       | 2 +-
 docs/v3/source/includes/resources/stacks/_update.md.erb       | 2 +-
 spec/request/stacks_spec.rb                                   | 4 ++--
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/app/messages/stack_update_message.rb b/app/messages/stack_update_message.rb
index 59ea7ad8a7c..fa7664258cd 100644
--- a/app/messages/stack_update_message.rb
+++ b/app/messages/stack_update_message.rb
@@ -8,7 +8,7 @@ class StackUpdateMessage < MetadataBaseMessage
     validates_with NoAdditionalKeysValidator
     validates :state, inclusion: { in: StackStates::VALID_STATES, message: "must be one of #{StackStates::VALID_STATES.join(', ')}" }, allow_nil: false, if: :state_requested?
     validates :state_reason, length: { maximum: 5000 }, allow_nil: true
-    validates :description, length: { maximum: 5000 }, allow_nil: true
+    validates :description, length: { maximum: 250 }, allow_nil: true
 
     def state_requested?
       requested?(:state)
diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
index 884fa2b1c6f..241712bf42f 100644
--- a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
+++ b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml
@@ -11,8 +11,8 @@ content:
           maxLength: 250
         description:
           type: [string, "null"]
-          description: Description of the stack; must be no longer than 5000 characters
-          maxLength: 5000
+          description: Description of the stack; must be no longer than 250 characters
+          maxLength: 250
         metadata:
           $ref: '../schemas/Metadata.yaml'
       required:
diff --git a/docs/openapi/apis/cf/latest/paths/Stacks.yaml b/docs/openapi/apis/cf/latest/paths/Stacks.yaml
index c543b9f49e7..73700235f04 100644
--- a/docs/openapi/apis/cf/latest/paths/Stacks.yaml
+++ b/docs/openapi/apis/cf/latest/paths/Stacks.yaml
@@ -155,7 +155,7 @@
             properties:
               description:
                 type: string
-                description: Description of the stack; must be no longer than 5000 characters
+                description: Description of the stack; must be no longer than 250 characters
                 maxLength: 250
               metadata:
                 $ref: ../components/schemas/Metadata.yaml
diff --git a/docs/v3/source/includes/resources/stacks/_create.md.erb b/docs/v3/source/includes/resources/stacks/_create.md.erb
index 25f3cd30f17..a4768ff4136 100644
--- a/docs/v3/source/includes/resources/stacks/_create.md.erb
+++ b/docs/v3/source/includes/resources/stacks/_create.md.erb
@@ -41,7 +41,7 @@ Name | Type | Description
 
 Name | Type | Description | Default
 ---- | ---- | ----------- | -------
-**description** | _string_ | Description of the stack; must be no longer than 5000 characters | `null`
+**description** | _string_ | Description of the stack; must be no longer than 250 characters | `null`
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
diff --git a/docs/v3/source/includes/resources/stacks/_update.md.erb b/docs/v3/source/includes/resources/stacks/_update.md.erb
index db77d379225..38a45c0d0a6 100644
--- a/docs/v3/source/includes/resources/stacks/_update.md.erb
+++ b/docs/v3/source/includes/resources/stacks/_update.md.erb
@@ -31,7 +31,7 @@ Content-Type: application/json
 
 Name | Type | Description
 ---- | ---- | -----------
-**description** | _string_ | Description of the stack; must be no longer than 5000 characters
+**description** | _string_ | Description of the stack; must be no longer than 250 characters
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
diff --git a/spec/request/stacks_spec.rb b/spec/request/stacks_spec.rb
index 370593c61f4..7823ee89d47 100644
--- a/spec/request/stacks_spec.rb
+++ b/spec/request/stacks_spec.rb
@@ -775,10 +775,10 @@
     end
 
     it 'returns 422 when description exceeds the maximum length' do
-      patch "/v3/stacks/#{stack.guid}", { description: 'A' * 5001 }.to_json, headers
+      patch "/v3/stacks/#{stack.guid}", { description: 'A' * 251 }.to_json, headers
 
       expect(last_response.status).to eq(422)
-      expect(last_response).to have_error_message('Description is too long (maximum is 5000 characters)')
+      expect(last_response).to have_error_message('Description is too long (maximum is 250 characters)')
     end
   end