fix: flag duplicate action_id within a block (#67)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: StephenTangCook

README.md

@@ -15,7 +15,7 @@ JSON Schema (draft 2020-12) and validation helpers for Slack Block Kit JSON. Cat
 
 Slack's API returns `200 OK` when you send malformed Block Kit JSON — the metadata is dropped and the message renders as plain text (or a modal opens blank). The only way to find out is to eyeball a real Slack channel. Slack hasn't open-sourced their validator.
 
-This package compiles every rule in <https://docs.slack.dev/reference/block-kit> into a single JSON Schema, plus a handful of helpers for the cross-payload rules JSON Schema can't express (duplicate `block_id`, cumulative markdown length, one-table-per-message, `focus_on_load` uniqueness, surface compatibility).
+This package compiles every rule in <https://docs.slack.dev/reference/block-kit> into a single JSON Schema, plus a handful of helpers for the cross-payload rules JSON Schema can't express (duplicate `block_id`, duplicate `action_id` within a block, cumulative markdown length, one-table-per-message, `focus_on_load` uniqueness, surface compatibility).
 
 > Prefer an API call or an MCP server over an npm install? The repo also ships a Cloudflare Worker that exposes this package as a public, rate-limited HTTP endpoint plus a remote MCP server — see [`worker/`](./worker).
 
@@ -83,6 +83,7 @@ The helpers are pure (no deps, no Ajv) and can be stacked on top of any validato
 ```ts
 import {
   findDuplicateBlockIds,
+  findDuplicateActionIds,
   checkCumulativeMarkdownLength,
   checkSingleTableBlock,
   checkSinglePlanBlock,
@@ -122,6 +123,7 @@ The schema uses `$defs` for every block, element, composition object, rich-text
 | Helper | Signature | What it checks |
 |---|---|---|
 | `findDuplicateBlockIds` | `(blocks) => string[]` | Duplicate `block_id` values in a blocks array. |
+| `findDuplicateActionIds` | `(blocks) => string[]` | Duplicate `action_id` values *within* a single block (legal across different blocks). |
 | `checkCumulativeMarkdownLength` | `(blocks) => string[]` | Sum of all `markdown` block text > 12,000 chars. |
 | `checkSingleTableBlock` | `(blocks) => string[]` | More than one `table` block per payload. |
 | `checkSinglePlanBlock` | `(blocks) => string[]` | More than one `plan` block per payload. |
@@ -148,7 +150,7 @@ Each returns an array of human-readable error strings — empty when valid.
 - **All 9 composition objects**: text (plain_text + mrkdwn), confirm, option (3 contextual variants), option_group, slack_file, dispatch_action_config, conversation_filter, trigger, workflow.
 - **Rich text**: 4 container kinds (section, list, preformatted, quote) + 10 leaf kinds (text, link, user, usergroup, team, channel, emoji, broadcast, color, date) with style flags.
 - **View envelopes**: `modal_view` + `home_view` under `$defs`.
-- **Cross-payload rules** (via helpers): dup `block_id`, cumulative markdown, single-table, single-plan, two-data-visualization-per-message, chart series/category consistency, `focus_on_load` uniqueness, surface compatibility.
+- **Cross-payload rules** (via helpers): dup `block_id`, dup `action_id` within a block, cumulative markdown, single-table, single-plan, two-data-visualization-per-message, chart series/category consistency, `focus_on_load` uniqueness, surface compatibility.
 
 Every documented `maxLength`, regex (date / time / user ID / channel ID / team ID format), enum value, and array cardinality limit is enforced structurally.
 

src/helpers.ts

@@ -12,4 +12,5 @@ export * from "./helpers/check-response-url-enabled-context.js";
 export * from "./helpers/check-single-plan-block.js";
 export * from "./helpers/check-single-table-block.js";
 export * from "./helpers/check-surface-compatibility.js";
+export * from "./helpers/find-duplicate-action-ids.js";
 export * from "./helpers/find-duplicate-block-ids.js";

src/helpers/find-duplicate-action-ids.ts

@@ -0,0 +1,90 @@
+/**
+ * Block properties that hold a block's interactive elements. Slack keys
+ * `state.values` by `block_id` then `action_id`, so everything reachable from
+ * one block shares a single `action_id` namespace. `element` / `accessory` are
+ * single elements — they can't collide with anything, but they're listed for
+ * consistency and cost nothing.
+ */
+const ELEMENT_KEYS = ["elements", "actions", "element", "accessory"] as const;
+
+/**
+ * Blocks whose children are themselves blocks, each opening its own
+ * `action_id` namespace rather than sharing the parent's — a `carousel`'s
+ * cards and a `container`'s child blocks each carry their own `block_id`.
+ */
+const CHILD_BLOCK_KEYS = new Map<string, string>([
+  ["carousel", "elements"],
+  ["container", "child_blocks"],
+]);
+
+/**
+ * Cap for recursive traversal of block payloads. Well-formed payloads nest at
+ * most one level here (carousel → card, container → child block), so anything
+ * deeper is malformed or adversarial. Matches the cap used in the other
+ * walkers (`check-focus-on-load-uniqueness`, `check-number-input-bounds`).
+ */
+const MAX_WALK_DEPTH = 50;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * Returns error messages describing any duplicate `action_id` values within a
+ * single block. Slack rejects a payload where two interactive elements in the
+ * same block share an `action_id`. JSON Schema can't express per-property
+ * uniqueness across sibling items, so this check sits alongside structural
+ * validation like {@link findDuplicateBlockIds}.
+ *
+ * Uniqueness is required *within* a block, not across the payload: `state.values`
+ * is keyed `block_id` then `action_id`, so the same `action_id` in two different
+ * blocks is legal and is not flagged.
+ * @param blocks - array of Block Kit blocks (or anything with a nested shape)
+ * @returns array of human-readable error messages (empty when no duplicates)
+ */
+export function findDuplicateActionIds(blocks: readonly unknown[]): string[] {
+  const errors: string[] = [];
+
+  const visit = (block: unknown, path: string, depth: number): void => {
+    if (!isRecord(block) || depth > MAX_WALK_DEPTH) {
+      return;
+    }
+
+    const childKey = typeof block.type === "string" ? CHILD_BLOCK_KEYS.get(block.type) : undefined;
+    if (childKey !== undefined) {
+      const children = block[childKey];
+      if (Array.isArray(children)) {
+        children.forEach((child, i) => {
+          visit(child, `${path}.${childKey}[${i}]`, depth + 1);
+        });
+      }
+      return;
+    }
+
+    const seen = new Map<string, string>();
+    for (const key of ELEMENT_KEYS) {
+      const value = block[key];
+      const entries: [string, unknown][] = Array.isArray(value)
+        ? value.map((element, i) => [`${key}[${i}]`, element])
+        : [[key, value]];
+      for (const [rel, element] of entries) {
+        if (!isRecord(element) || typeof element.action_id !== "string") {
+          continue;
+        }
+        const id = element.action_id;
+        const prev = seen.get(id);
+        if (prev !== undefined) {
+          errors.push(
+            `${path}.${rel}.action_id must be unique within the block — '${id}' appears at ${prev} and ${rel}`,
+          );
+        } else {
+          seen.set(id, rel);
+        }
+      }
+    }
+  };
+
+  blocks.forEach((block, i) => {
+    visit(block, `blocks[${i}]`, 0);
+  });
+  return errors;
+}

src/validate-block-kit.ts

@@ -11,6 +11,7 @@ import { checkResponseUrlEnabledContext } from "./helpers/check-response-url-ena
 import { checkSinglePlanBlock } from "./helpers/check-single-plan-block.js";
 import { checkSingleTableBlock } from "./helpers/check-single-table-block.js";
 import { checkSurfaceCompatibility, type Surface } from "./helpers/check-surface-compatibility.js";
+import { findDuplicateActionIds } from "./helpers/find-duplicate-action-ids.js";
 import { findDuplicateBlockIds } from "./helpers/find-duplicate-block-ids.js";
 import schema from "./slack-block-kit.schema.json" with { type: "json" };
 
@@ -171,8 +172,9 @@ const stripUndefined = (input: unknown, depth = 0): unknown => {
 
 /**
  * Validates a Slack Block Kit payload against the JSON Schema and the set of
- * caveat helpers (duplicate block_ids, cumulative markdown length, single-table,
- * single-plan, focus_on_load uniqueness, surface compatibility).
+ * caveat helpers (duplicate block_ids, duplicate action_ids within a block,
+ * cumulative markdown length, single-table, single-plan, focus_on_load
+ * uniqueness, surface compatibility).
  * @param input - the payload to validate
  * @param options - target shape + optional surface
  * @returns `{ valid, errors }` — `errors` is a flat array of human-readable messages
@@ -198,6 +200,7 @@ export function validateBlockKit(input: unknown, options: ValidateBlockKitOption
   }[];
 
   errors.push(...findDuplicateBlockIds(blocks));
+  errors.push(...findDuplicateActionIds(blocks));
   errors.push(...checkCumulativeMarkdownLength(blocks));
   errors.push(...checkSingleTableBlock(blocks));
   errors.push(...checkSinglePlanBlock(blocks));

test/find-duplicate-action-ids.test.ts

@@ -0,0 +1,123 @@
+import { findDuplicateActionIds } from "../src/helpers/find-duplicate-action-ids";
+
+const button = (action_id?: string) => ({
+  type: "button",
+  text: { type: "plain_text", text: "Go", emoji: true },
+  ...(action_id === undefined ? {} : { action_id }),
+});
+
+describe("findDuplicateActionIds", () => {
+  it("returns no errors when action_ids within a block are unique", () => {
+    expect(findDuplicateActionIds([{ type: "actions", elements: [button("a"), button("b")] }])).toEqual([]);
+  });
+
+  it("returns no errors when elements have no action_id", () => {
+    expect(findDuplicateActionIds([{ type: "actions", elements: [button(), button()] }])).toEqual([]);
+  });
+
+  it("flags a duplicate action_id in an actions block with both positions", () => {
+    expect(findDuplicateActionIds([{ type: "actions", elements: [button("123"), button("123")] }])).toEqual([
+      "blocks[0].elements[1].action_id must be unique within the block — '123' appears at elements[0] and elements[1]",
+    ]);
+  });
+
+  it("flags each repeat of the same action_id independently", () => {
+    const errors = findDuplicateActionIds([
+      { type: "actions", elements: [button("a"), button("b"), button("a"), button("a")] },
+    ]);
+    expect(errors).toHaveLength(2);
+    expect(errors[0]).toContain("'a' appears at elements[0] and elements[2]");
+    expect(errors[1]).toContain("'a' appears at elements[0] and elements[3]");
+  });
+
+  it("allows the same action_id in two different blocks (state.values is keyed by block_id first)", () => {
+    expect(
+      findDuplicateActionIds([
+        { type: "actions", block_id: "one", elements: [button("a")] },
+        { type: "actions", block_id: "two", elements: [button("a")] },
+        { type: "section", text: { type: "mrkdwn", text: "hi" }, accessory: button("a") },
+      ]),
+    ).toEqual([]);
+  });
+
+  it("flags duplicates in a context_actions block", () => {
+    const errors = findDuplicateActionIds([
+      {
+        type: "context_actions",
+        elements: [
+          { type: "icon_button", icon: "bolt", action_id: "x" },
+          { type: "icon_button", icon: "bolt", action_id: "x" },
+        ],
+      },
+    ]);
+    expect(errors).toEqual([
+      "blocks[0].elements[1].action_id must be unique within the block — 'x' appears at elements[0] and elements[1]",
+    ]);
+  });
+
+  it("flags duplicates across a card block's actions", () => {
+    expect(findDuplicateActionIds([{ type: "card", actions: [button("go"), button("go")] }])).toEqual([
+      "blocks[0].actions[1].action_id must be unique within the block — 'go' appears at actions[0] and actions[1]",
+    ]);
+  });
+
+  it("scopes carousel cards separately and reports the offending card's path", () => {
+    const errors = findDuplicateActionIds([
+      {
+        type: "carousel",
+        elements: [
+          { type: "card", actions: [button("go")] },
+          { type: "card", actions: [button("go"), button("go")] },
+        ],
+      },
+    ]);
+    expect(errors).toEqual([
+      "blocks[0].elements[1].actions[1].action_id must be unique within the block — 'go' appears at actions[0] and actions[1]",
+    ]);
+  });
+
+  it("scopes container child blocks separately", () => {
+    const errors = findDuplicateActionIds([
+      {
+        type: "container",
+        child_blocks: [
+          { type: "actions", elements: [button("go")] },
+          { type: "actions", elements: [button("go"), button("go")] },
+        ],
+      },
+    ]);
+    expect(errors).toEqual([
+      "blocks[0].child_blocks[1].elements[1].action_id must be unique within the block — 'go' appears at elements[0] and elements[1]",
+    ]);
+  });
+
+  it("shares one namespace across an input block's element and any sibling keys", () => {
+    expect(
+      findDuplicateActionIds([
+        {
+          type: "input",
+          label: { type: "plain_text", text: "Name" },
+          element: { type: "plain_text_input", action_id: "a" },
+        },
+      ]),
+    ).toEqual([]);
+  });
+
+  it("ignores non-string action_ids", () => {
+    expect(
+      findDuplicateActionIds([{ type: "actions", elements: [{ action_id: 1 }, { action_id: 1 }, null, "nope"] }]),
+    ).toEqual([]);
+  });
+
+  it("accepts an empty array", () => {
+    expect(findDuplicateActionIds([])).toEqual([]);
+  });
+
+  it("terminates on pathologically nested containers", () => {
+    let block: unknown = { type: "actions", elements: [button("a"), button("a")] };
+    for (let i = 0; i < 200; i++) {
+      block = { type: "container", child_blocks: [block] };
+    }
+    expect(findDuplicateActionIds([block])).toEqual([]);
+  });
+});

test/property-based.test.ts

@@ -1,6 +1,7 @@
 import * as fc from "fast-check";
 import { checkFocusOnLoadUniqueness } from "../src/helpers/check-focus-on-load-uniqueness";
 import { checkNumberInputBounds } from "../src/helpers/check-number-input-bounds";
+import { findDuplicateActionIds } from "../src/helpers/find-duplicate-action-ids";
 import { findDuplicateBlockIds } from "../src/helpers/find-duplicate-block-ids";
 import { validateBlockKit } from "../src/validate-block-kit";
 
@@ -32,6 +33,16 @@ describe("property: helpers return without throwing on arbitrary input", () => {
     );
   });
 
+  it("findDuplicateActionIds terminates on deeply nested input", () => {
+    fc.assert(
+      fc.property(fc.array(arbAnything(), { maxLength: 10 }), (xs) => {
+        const errs = findDuplicateActionIds(xs);
+        expect(Array.isArray(errs)).toBe(true);
+      }),
+      { numRuns: 200 },
+    );
+  });
+
   it("checkFocusOnLoadUniqueness terminates on deeply nested input", () => {
     fc.assert(
       fc.property(fc.array(arbAnything(), { maxLength: 10 }), (xs) => {

test/validate-block-kit.test.ts

@@ -23,6 +23,30 @@ describe("validateBlockKit", () => {
       expect(result.errors.some((e) => e.includes("only one 'table' block"))).toBe(true);
     });
 
+    it("flags two elements in one block sharing an action_id", () => {
+      const button = (text: string) => ({
+        type: "button",
+        text: { type: "plain_text", text, emoji: true },
+        action_id: "123",
+      });
+      const result = validateBlockKit([{ type: "actions", elements: [button("A"), button("B")] }]);
+      expect(result.valid).toBe(false);
+      expect(result.errors).toEqual([
+        "blocks[0].elements[1].action_id must be unique within the block — '123' appears at elements[0] and elements[1]",
+      ]);
+    });
+
+    it("accepts the same action_id in two different blocks", () => {
+      const actions = (block_id: string) => ({
+        type: "actions",
+        block_id,
+        elements: [{ type: "button", text: { type: "plain_text", text: "Go", emoji: true }, action_id: "123" }],
+      });
+      const result = validateBlockKit([actions("one"), actions("two")], { surface: "message" });
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+
     it("accepts a single plan block", () => {
       const result = validateBlockKit([{ type: "plan", title: "Sprint plan" }]);
       expect(result.valid).toBe(true);