dingtalk-workspace-cli/internal/cli/param_concepts.json

{
  "$schema": "./param_concepts.schema.json",
  "version": 1,

  "morphological_rules": {
    "kebab_camel_equivalence": {"desc": "--page-size == --pageSize", "enabled": true},
    "separator_normalization": {"desc": "-, _, . are equivalent separators", "enabled": true},
    "trailing_id_tolerance": {"desc": "--base tolerates --base-id when only one is a real flag on the command", "enabled": true, "guard": "the two must not both be real flags with different semantics"},
    "pluralization": {"desc": "--id<->--ids, --user<->--users", "enabled": false, "reason": "singular/list semantics can differ; handled by concept+intersection or command override instead"}
  },

  "concepts": {
    "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +search-user", "doc +template-search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"},
    "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "mail thread list", "oa +list-executed"], "risk": "green"},
    "page_number": {"denotes": "one-based page number", "canonical_hint": "page", "members": ["page", "page-no", "current-page", "page-num"], "excludes": ["cursor", "page-index", "page-size", "page-token"], "commands": ["devdoc article search"], "risk": "green"},
    "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list"], "risk": "green"},
    "content_text": {"denotes": "text body content", "canonical_hint": "text", "members": ["text", "content", "body"], "excludes": ["title", "name"], "commands": ["doc block insert", "doc block update"], "risk": "green"},
    "time_start": {"denotes": "start time point with unchanged value format and unit", "canonical_hint": "start", "members": ["start", "start-time", "start-date", "from", "from-date", "begin", "since", "time-min", "min-time"], "excludes": ["date", "time", "end"], "commands": ["calendar event list", "chat message list-all", "report list"], "risk": "yellow"},
    "time_end": {"denotes": "end time point with unchanged value format and unit", "canonical_hint": "end", "members": ["end", "end-time", "end-date", "time-max", "max-time"], "excludes": ["date", "time", "start"], "commands": ["calendar event list"], "risk": "yellow"},
    "base_id": {"denotes": "multi-dimensional table Base id", "canonical_hint": "base-id", "members": ["base", "base-id", "base-token"], "excludes": [], "commands": ["aitable +field-get", "aitable +list-tables", "aitable +record-query", "aitable +record-share-url", "aitable +table-get"], "risk": "green"},
    "dept_id": {"denotes": "single department id", "canonical_hint": "dept", "members": ["dept", "dept-id", "department", "department-id"], "excludes": ["depts", "dept-ids", "department-ids", "name", "query", "parent"], "commands": ["contact +list-sub-depts", "contact dept list-children"], "risk": "yellow"},
    "dept_ids": {"denotes": "department id list", "canonical_hint": "dept-ids", "members": ["depts", "dept-ids", "department-ids"], "excludes": ["dept", "dept-id", "department-id", "name", "query"], "commands": ["contact +list-dept-members"], "risk": "yellow"},
    "group_id": {"denotes": "single group/conversation id", "canonical_hint": "conversation-id", "members": ["group", "group-id", "conversation-id", "chat-id", "open-conversation-id"], "excludes": ["conversation-ids", "group-ids", "id", "name"], "commands": ["chat group members", "chat group members add", "chat group members remove", "chat group rename"], "risk": "yellow"},
    "user_id": {"denotes": "single user id", "canonical_hint": "user-id", "members": ["user", "user-id", "userid", "uid", "staff-id"], "excludes": ["at-user-ids", "to-user", "users", "user-ids", "name"], "commands": ["contact user profile get"], "risk": "yellow"},
    "user_ids": {"denotes": "user id list", "canonical_hint": "user-ids", "members": ["users", "user-ids"], "excludes": ["user", "user-id", "userid", "uid", "staff-id", "at-user-ids"], "commands": ["attendance check result", "chat message send-by-bot"], "risk": "yellow"},
    "ding_id": {"denotes": "DING id", "canonical_hint": "ding-id", "members": ["ding-id", "open-ding-id"], "excludes": ["id"], "commands": ["ding message receiver-status"], "risk": "yellow"},
    "folder_id": {"denotes": "drive folder id", "canonical_hint": "folder", "members": ["folder", "folder-id"], "excludes": ["space-id"], "commands": ["drive list", "mail folder update"], "risk": "green"},
    "space_id": {"denotes": "drive/wiki space id", "canonical_hint": "space-id", "members": ["space-id", "space", "workspace", "workspace-id"], "excludes": ["folder", "node"], "commands": ["drive info"], "risk": "yellow"},
    "app_id": {"denotes": "application id", "canonical_hint": "unified-app-id", "members": ["app-id", "unified-app-id", "application-id"], "excludes": ["app-key", "app-secret", "agent-id"], "commands": ["dev app get"], "risk": "yellow"},
    "robot_code": {"denotes": "robot code", "canonical_hint": "robot-code", "members": ["robot-code", "robot"], "excludes": ["robot-id"], "commands": ["ding message send"], "risk": "yellow"}
  },

  "command_overrides": {
    "chat group rename": {"bind": {"id": "group_id"}, "note": "this command's --id is the group id; --group thus reduces to --id"},
    "chat group members": {"bind": {"id": "group_id"}},
    "chat group members add": {"bind": {"id": "group_id"}},
    "chat group members remove": {"bind": {"id": "group_id"}},
    "chat message add-emoji": {"scoped_aliases": {"group-id": "conversation-id", "chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["conversation-ids"], "note": "reviewed against RunE and final add_emoji_reaction payload: all singular aliases pass the same unchanged openConversationId; plural --conversation-ids is blocked from the singular field"},
    "chat message add-text-emotion": {"scoped_aliases": {"group-id": "conversation-id", "chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["conversation-ids"], "note": "reviewed against RunE and final add_text_emotion payload: all singular aliases pass the same unchanged openConversationId; plural --conversation-ids is blocked from the singular field"},
    "chat message remove-emoji": {"scoped_aliases": {"group-id": "conversation-id", "chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["conversation-ids"], "note": "reviewed against RunE and final remove_emoji_reaction payload: all singular aliases pass the same unchanged openConversationId; plural --conversation-ids is blocked from the singular field"},
    "chat message remove-text-emotion": {"scoped_aliases": {"group-id": "conversation-id", "chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["conversation-ids"], "note": "reviewed against RunE and final remove_text_emotion payload: all singular aliases pass the same unchanged openConversationId; plural --conversation-ids is blocked from the singular field"},
    "drive list": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"},
    "drive upload": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"},
    "ding +receiver-status": {"scoped_aliases": {"id": "ding-id"}, "note": "generic id reduces to ding-id"},
    "ding message receiver-status": {"scoped_aliases": {"id": "ding-id"}},
    "contact user profile get": {"scoped_aliases": {"id": "staff-id", "ids": "staff-id"}, "note": "user-id is reduced by the user_id concept; generic id/ids bound explicitly"},
    "mail folder update": {"bind": {"id": "folder_id"}, "note": "this command's --id is the folder id; --folder-id reduces to --id"},
    "contact dept list-children": {"scoped_aliases": {"parent": "dept", "parent-id": "dept"}, "note": "reviewed against command payload: --dept is the parent department id"},
    "mail message search": {"scoped_aliases": {"subject": "query"}, "scope_strict": true, "note": "never globalize: mail template create has a real and different --subject"},
    "calendar event list": {"scoped_aliases": {"date": "start"}, "note": "reviewed against ParseISOTimeToMillis and final list_calendar_events payload; --date is normalized centrally while the command's existing hidden compatibility flags remain native fallbacks"},
    "chat message list-by-sender": {"block": ["time"], "note": "--time does not state the RFC3339 start-boundary semantics required by this command"},
    "contact +resolve-dept": {"scoped_aliases": {"query": "name"}, "note": "reviewed against shortcut source: --name is passed unchanged as search_dept_by_keyword.query"},
    "contact +list-sub-depts": {"block": ["name", "query"], "note": "--dept is an integer department id; names and search queries require a separate resolution command"},
    "contact +dept-members": {"scoped_aliases": {"name": "dept", "query": "dept"}, "note": "reviewed against shortcut source: --dept is explicitly a department name/search keyword"},
    "chat message send": {"scoped_aliases": {"to-user": "user"}, "note": "reviewed write mapping: both names denote one direct-message recipient user id; final payload is asserted by an end-to-end test"},
    "chat +group-members": {"scoped_aliases": {"group-name": "group"}, "note": "reviewed against shortcut source: --group is explicitly the group-name search keyword"},
    "doc block insert": {"block": ["before-block-id"], "note": "requires a two-parameter conversion to --ref-block plus --where before; name-only normalization would silently default to after"},
    "chat message send-by-bot": {"block": ["user-id", "to-user-id"], "note": "--users is a recipient list, so singular --user-id/--to-user-id are not silently promoted to list cardinality; group mentions must use the explicit --at-user-ids"},
    "attendance +check-result": {"block": ["user-id"], "note": "--users is a list; singular --user-id is not silently promoted to list cardinality"},
    "doc +export-get": {"block": ["node"], "note": "node is a document node id, a different entity from job-id"},
    "doc block delete": {"block": ["index"], "note": "index (position) vs node (node id) are different"},
    "report outbox list": {"block": ["template-type"], "note": "type vs name are different fields"}
  },

  "validation_fixture": {
    "cases": [
      {"command": "oa +search-forms", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 28},
      {"command": "aitable +list-tables", "emitted": "base-id", "expect": "base", "via": "concept:base_id+morph", "occ": 26},
      {"command": "mail +find-mail-user", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 18},
      {"command": "aitable +field-get", "emitted": "base", "expect": "base-id", "via": "concept:base_id+morph", "occ": 8},
      {"command": "aitable +record-query", "emitted": "base", "expect": "base-id", "via": "concept:base_id+morph", "occ": 8},
      {"command": "aitable +table-get", "emitted": "base", "expect": "base-id", "via": "concept:base_id+morph", "occ": 8},
      {"command": "doc block update", "emitted": "content", "expect": "text", "via": "concept:content_text", "occ": 6},
      {"command": "contact +resolve-dept", "emitted": "query", "expect": "name", "via": "override:scoped(reviewed)", "occ": 4},
      {"command": "devdoc article search", "emitted": "limit", "expect": "size", "via": "concept:pagination_size", "occ": 2},
      {"command": "devdoc article search", "emitted": "page-size", "expect": "size", "via": "concept:pagination_size", "occ": 2},
      {"command": "devdoc article search", "emitted": "current-page", "expect": "page", "via": "concept:page_number", "occ": 2},
      {"command": "mail message search", "emitted": "subject", "expect": "query", "via": "override:scoped_strict", "occ": 4},
      {"command": "aitable +record-share-url", "emitted": "base", "expect": "base-id", "via": "concept:base_id+morph", "occ": 3},
      {"command": "aitable record query", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size", "occ": 2},
      {"command": "calendar event list", "emitted": "date", "expect": "start", "via": "override:scoped(reviewed+payload)", "occ": 2},
      {"command": "calendar event list", "emitted": "start-time", "expect": "start", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "calendar event list", "emitted": "min-time", "expect": "start", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "calendar event list", "emitted": "time-min", "expect": "start", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "calendar event list", "emitted": "end-time", "expect": "end", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "calendar event list", "emitted": "time-max", "expect": "end", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "calendar event list", "emitted": "max-results", "expect": "limit", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "calendar event list", "emitted": "next-cursor", "expect": "cursor", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "calendar event list", "emitted": "calendar", "expect": "calendar-id", "via": "native:reviewed-compatibility-fallback", "occ": 2},
      {"command": "chat message list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size", "occ": 2},
      {"command": "chat message list-by-sender", "emitted": "time", "expect": "did-you-mean:blocked", "via": "guard:time-format-boundary", "occ": 2},
      {"command": "doc +template-search", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 2},
      {"command": "doc block insert", "emitted": "content", "expect": "text", "via": "concept:content_text", "occ": 2},
      {"command": "drive list", "emitted": "folder-id", "expect": "folder", "via": "concept:folder_id+morph", "occ": 2},
      {"command": "mail thread list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size", "occ": 2},
      {"command": "mail user search", "emitted": "query", "expect": "keyword", "via": "concept:search_query", "occ": 2},
      {"command": "oa +list-executed", "emitted": "take", "expect": "limit", "via": "concept:pagination_size", "occ": 2},
      {"command": "oa approval search-forms", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 2},
      {"command": "report list", "emitted": "from-date", "expect": "start", "via": "concept:time_start", "occ": 2},
      {"command": "aitable +base-search", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 1},
      {"command": "contact +search-user", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 1},
      {"command": "chat group rename", "emitted": "group", "expect": "id", "via": "override:bind(group_id)", "occ": 31},
      {"command": "ding +receiver-status", "emitted": "id", "expect": "ding-id", "via": "override:scoped(ding_id)", "occ": 24},
      {"command": "chat group members", "emitted": "group", "expect": "id", "via": "override:bind(group_id)", "occ": 8},
      {"command": "contact +list-sub-depts", "emitted": "dept-id", "expect": "dept", "via": "concept:dept_id+morph", "occ": 4},
      {"command": "contact +list-sub-depts", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:name-vs-id", "occ": 2},
      {"command": "contact +list-sub-depts", "emitted": "query", "expect": "did-you-mean:blocked", "via": "guard:query-vs-id", "occ": 2},
      {"command": "contact user profile get", "emitted": "user-id", "expect": "staff-id", "via": "concept:user_id", "occ": 2},
      {"command": "contact user profile get", "emitted": "id", "expect": "staff-id", "via": "override:scoped", "occ": 2},
      {"command": "contact user profile get", "emitted": "ids", "expect": "staff-id", "via": "override:scoped", "occ": 2},
      {"command": "chat message send-by-bot", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list", "occ": 4},
      {"command": "chat message send-by-bot", "emitted": "to-user-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list", "occ": 1},
      {"command": "dev app get", "emitted": "app-id", "expect": "unified-app-id", "via": "concept:app_id", "occ": 5},
      {"command": "chat message list-all", "emitted": "from", "expect": "start", "via": "concept:time_start", "occ": 2},
      {"command": "chat message list-all", "emitted": "start-time", "expect": "start", "via": "concept:time_start", "occ": 2},
      {"command": "chat message search-advanced", "emitted": "group", "expect": "conversation-ids", "via": "native:reviewed-single-to-list", "occ": 4},
      {"command": "chat message send", "emitted": "to-user", "expect": "user", "via": "override:scoped(reviewed+payload)", "occ": 4},
      {"command": "contact +dept-members", "emitted": "name", "expect": "dept", "via": "override:scoped(reviewed)", "occ": 2},
      {"command": "contact +dept-members", "emitted": "query", "expect": "dept", "via": "override:scoped(reviewed)", "occ": 2},
      {"command": "contact dept list-children", "emitted": "parent-id", "expect": "dept", "via": "override:scoped(reviewed)", "occ": 2},
      {"command": "contact dept list-children", "emitted": "parent", "expect": "dept", "via": "override:scoped(reviewed)", "occ": 2},
      {"command": "ding message receiver-status", "emitted": "id", "expect": "ding-id", "via": "override:scoped(ding_id)", "occ": 2},
      {"command": "ding message receiver-status", "emitted": "open-ding-id", "expect": "ding-id", "via": "concept:ding_id", "occ": 2},
      {"command": "chat group members add", "emitted": "group", "expect": "id", "via": "override:bind(group_id)", "occ": 3},
      {"command": "attendance +check-result", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list", "occ": 2},
      {"command": "attendance check result", "emitted": "user-ids", "expect": "users", "via": "concept:user_ids", "occ": 2},
      {"command": "chat group members remove", "emitted": "group", "expect": "id", "via": "override:bind(group_id)", "occ": 2},
      {"command": "chat group set-admin", "emitted": "user-id", "expect": "user", "via": "native:reviewed-compatibility-alias", "occ": 2},
      {"command": "ding message send", "emitted": "robot", "expect": "robot-code", "via": "concept:robot_code", "occ": 2},
      {"command": "doc +export-get", "emitted": "node", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2},
      {"command": "doc block delete", "emitted": "index", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2},
      {"command": "doc block insert", "emitted": "before-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-multi-parameter-transform", "occ": 2},
      {"command": "drive info", "emitted": "workspace", "expect": "space-id", "via": "concept:space_id", "occ": 2},
      {"command": "mail folder update", "emitted": "folder-id", "expect": "id", "via": "override:bind(folder_id)", "occ": 2},
      {"command": "report outbox list", "emitted": "template-type", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2},
      {"command": "chat +group-members", "emitted": "group-name", "expect": "group", "via": "override:scoped(reviewed)", "occ": 1}
    ]
  }
}