Skip to content

feat: support mrkdwn descriptions on OptionObject (#1471) #1645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
zimeg wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

feat: support mrkdwn descriptions on OptionObject (#1471) #1645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9b52084
Allow mrkdwn descriptions on OptionObject (fixes #1471)
zimeg Sep 10, 2026
5f44fd2
test: fold mrkdwn option description into existing checkboxes test
zimeg Sep 10, 2026
6b352a1
test: set OptionObject descriptions in sample-JSON generator for Text…
zimeg Sep 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions json-logs/samples/api/views.open.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2502,9 +2502,9 @@
},
"value": "",
"description": {
"type": "plain_text",
"type": "mrkdwn",
"text": "",
"emoji": false
"verbatim": false
},
"url": ""
}
Expand Down
4 changes: 2 additions & 2 deletions json-logs/samples/api/views.publish.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2502,9 +2502,9 @@
},
"value": "",
"description": {
"type": "plain_text",
"type": "mrkdwn",
"text": "",
"emoji": false
"verbatim": false
},
"url": ""
}
Expand Down
4 changes: 2 additions & 2 deletions json-logs/samples/api/views.push.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2502,9 +2502,9 @@
},
"value": "",
"description": {
"type": "plain_text",
"type": "mrkdwn",
"text": "",
"emoji": false
"verbatim": false
},
"url": ""
}
Expand Down
4 changes: 2 additions & 2 deletions json-logs/samples/api/views.update.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2502,9 +2502,9 @@
},
"value": "",
"description": {
"type": "plain_text",
"type": "mrkdwn",
"text": "",
"emoji": false
"verbatim": false
},
"url": ""
}
Expand Down
6 changes: 3 additions & 3 deletions slack-api-client/src/test/java/util/sample_json_generation/SampleObjects.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,10 +262,10 @@ private static List<JsonElement> initBlocks() {
.text(initProperties(PlainTextObject.builder().build()))
.build()))
.options(Arrays.asList(
initProperties(OptionObject.builder().text(initProperties(PlainTextObject.builder().build())).build()),
initProperties(OptionObject.builder().text(initProperties(MarkdownTextObject.builder().build())).build())
initProperties(OptionObject.builder().text(initProperties(PlainTextObject.builder().build())).description(initProperties(PlainTextObject.builder().build())).build()),
initProperties(OptionObject.builder().text(initProperties(MarkdownTextObject.builder().build())).description(initProperties(MarkdownTextObject.builder().build())).build())
))
.initialOption(initProperties(OptionObject.builder().text(initProperties(PlainTextObject.builder().build())).build()))
.initialOption(initProperties(OptionObject.builder().text(initProperties(PlainTextObject.builder().build())).description(initProperties(PlainTextObject.builder().build())).build()))
Comment on lines +265 to +268

@zimeg zimeg Sep 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔭 note: These description values are added to tests so JSON reflections don't error when deciding between plain_text and mrkdwn values.

@zimeg zimeg Sep 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👾 note: This is a test change and wouldn't require similar from developers as I understand.

.build());

public static List<LayoutBlock> ModalBlocks = asBlocks(
Expand Down
20 changes: 17 additions & 3 deletions ...main/kotlin/com/slack/api/model/kotlin_extension/block/composition/OptionObjectBuilder.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
package com.slack.api.model.kotlin_extension.block.composition

import com.slack.api.model.block.composition.MarkdownTextObject
import com.slack.api.model.block.composition.OptionObject
import com.slack.api.model.block.composition.PlainTextObject
import com.slack.api.model.block.composition.TextObject
import com.slack.api.model.kotlin_extension.block.BlockLayoutBuilder
import com.slack.api.model.kotlin_extension.block.Builder
import com.slack.api.model.kotlin_extension.block.composition.container.SingleTextObjectContainer
Expand All @@ -14,7 +16,7 @@ class OptionObjectBuilder private constructor(
) : Builder<OptionObject>, TextObjectDsl by textContainer {
private var value: String? = null
private var url: String? = null
private var description: PlainTextObject? = null
private var description: TextObject? = null

constructor() : this(SingleTextObjectContainer())

Expand All @@ -40,15 +42,27 @@ class OptionObjectBuilder private constructor(
}

/**
* a line of descriptive text shown below the text field beside the radio button. Maximum length for the text
* object within this field is 75 characters.
* A plain_text text object that defines a line of descriptive text shown below the text field beside a single
* selectable item in a select menu, multi-select menu, checkbox group, radio button group, or overflow menu.
* Maximum length for the text within this field is 75 characters.
*
* @see <a href="https://docs.slack.dev/reference/block-kit/composition-objects/option-object">Option object documentation</a>
*/
fun description(text: String, emoji: Boolean? = null) {
description = PlainTextObject(text, emoji)
}

/**
* A mrkdwn text object that defines a line of descriptive text shown below the text field beside a single
* selectable item. Only checkbox group and radio button group items can use mrkdwn formatting.
* Maximum length for the text within this field is 75 characters.
*
* @see <a href="https://docs.slack.dev/reference/block-kit/composition-objects/option-object">Option object documentation</a>
*/
fun markdownDescription(text: String, verbatim: Boolean? = null) {
description = MarkdownTextObject(text, verbatim)
}
Comment on lines +62 to +64

@zimeg zimeg Sep 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👁️‍🗨️ note: This pattern is similar to how the text object is supported although I understand this isn't identical for the current description object:

  • plainText
  • markdownText

🔗 https://github.com/slackapi/java-slack-sdk/blob/dbe498ce0a2f0ed068b4bd7028ce31d22c91998d/slack-api-model-kotlin-extension/src/main/kotlin/com/slack/api/model/kotlin_extension/block/composition/dsl/TextObjectDsl.kt

@zimeg zimeg Sep 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

☁️ note: Calling this out here because I'm uncertain if we're using the best pattern without introducing a break:

  • description
  • markdownDescription


override fun build(): OptionObject {
return OptionObject.builder()
.description(description)
Expand Down
6 changes: 3 additions & 3 deletions slack-api-model-kotlin-extension/src/test/kotlin/test_locally/block/ActionsBlockTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -438,7 +438,7 @@ class ActionsBlockTest {
checkboxes {
options {
option {
description("I accept the terms and conditions")
markdownDescription("*I accept the terms and conditions*")
value("tac-accept")
}
option {
Expand Down Expand Up @@ -481,8 +481,8 @@ class ActionsBlockTest {
{
"value": "tac-accept",
"description": {
"type": "plain_text",
"text": "I accept the terms and conditions"
"type": "mrkdwn",
"text": "*I accept the terms and conditions*"
}
},
{
Expand Down
10 changes: 6 additions & 4 deletions slack-api-model/src/main/java/com/slack/api/model/block/composition/OptionObject.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,13 @@ public class OptionObject {
private String value;

/**
* A plain_text only text object that defines a line of descriptive text shown
* below the text field beside the radio button.
* Maximum length for the text object within this field is 75 characters.
* A plain_text text object that defines a line of descriptive text shown below
* the text field beside a single selectable item in a select menu, multi-select
* menu, checkbox group, radio button group, or overflow menu. Checkbox group and
* radio button group items can also use mrkdwn formatting.
* Maximum length for the text within this field is 75 characters.
*/
private PlainTextObject description;
private TextObject description;
Comment on lines +32 to +38

@zimeg zimeg Sep 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤓 note: This matches reference and becomes more general to support API requests with validation left to blocks itself.

🔗 https://docs.slack.dev/reference/block-kit/composition-objects/option-object


/**
* A URL to load in the user's browser when the option is clicked.
Expand Down
17 changes: 17 additions & 0 deletions slack-api-model/src/test/java/test_locally/api/model/block/BlockKitTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
import com.slack.api.model.Message;
import com.slack.api.model.block.*;
import com.slack.api.model.block.composition.ConfirmationDialogObject;
import com.slack.api.model.block.composition.MarkdownTextObject;
import com.slack.api.model.block.composition.OptionObject;
import com.slack.api.model.block.composition.PlainTextObject;
import com.slack.api.model.block.element.*;
import com.slack.api.model.view.View;
import org.junit.Test;
Expand Down Expand Up @@ -1042,6 +1045,10 @@ public void parseCheckboxes() {
" \"text\": \"*this is plain_text text*\",\n" +
" \"emoji\": true\n" +
" },\n" +
" \"description\": {\n" +
" \"type\": \"plain_text\",\n" +
" \"text\": \"this is a plain_text description\"\n" +
" },\n" +
" \"value\": \"value-0\"\n" +
" },\n" +
" {\n" +
Expand Down Expand Up @@ -1123,9 +1130,19 @@ public void parseCheckboxes() {
CheckboxesElement checkboxes1 = (CheckboxesElement) input.getElement();
assertThat(checkboxes1.getActionId(), is("input-action-id"));

OptionObject plainOption = checkboxes1.getOptions().get(0);
assertThat(plainOption.getDescription(), instanceOf(PlainTextObject.class));
assertThat(plainOption.getDescription().getType(), is("plain_text"));
assertThat(((PlainTextObject) plainOption.getDescription()).getText(), is("this is a plain_text description"));

SectionBlock block = (SectionBlock) message.getBlocks().get(1);
CheckboxesElement checkboxes2 = (CheckboxesElement) block.getAccessory();
assertThat(checkboxes2.getActionId(), is("section-action-id"));

OptionObject mrkdwnOption = checkboxes2.getOptions().get(0);
assertThat(mrkdwnOption.getDescription(), instanceOf(MarkdownTextObject.class));
assertThat(mrkdwnOption.getDescription().getType(), is("mrkdwn"));
assertThat(((MarkdownTextObject) mrkdwnOption.getDescription()).getText(), is("*this is mrkdwn text*"));
}

@Test
Expand Down
Loading