Add support for completionList.applyKind to determine how values from completionList.itemDefaults and completion are combined.

_specifications/lsp/3.18/language/completion.md

@@ -166,6 +166,21 @@ export interface CompletionClientCapabilities {
  * @since 3.17.0
  */
  itemDefaults?: string[];
+
+ /**
+ * Specifies whether the client supports `CompletionList.applyKind` to
+ * indicate how supported values from `completionList.itemDefaults`
+ * and `completion` will be combined.
+ * 
+ * If a client supports `applyKind` it must support it for all fields
+ * that it supports that are listed in `CompletionList.applyKind`. This
+ * means when clients add support for new/future fields in completion
+ * items the MUST also support merge for them if those fields are
+ * defined in `CompletionList.applyKind`.
+ *
+ * @since 3.18.0
+ */
+ applyKindSupport?: boolean;
  }
 }
 ```
@@ -338,7 +353,9 @@ export interface CompletionList {
  * be used if a completion item itself doesn't specify the value.
  *
  * If a completion list specifies a default value and a completion item
- * also specifies a corresponding value, the one from the item is used.
+ * also specifies a corresponding value, the rules for combining these are
+ * defined by `applyKinds` (if the client supports it), defaulting to
+ * "replace".
  *
  * Servers are only allowed to return default values if the client
  * signals support for this via the `completionList.itemDefaults`
@@ -386,6 +403,72 @@ export interface CompletionList {
  data?: LSPAny;
  }
 
+ /**
+ * Specifies how fields from a completion item should be combined with those
+ * from `completionList.itemDefaults`.
+ * 
+ * In unspecified, all fields will be treated as "replace".
+ * 
+ * If a field's value is "replace", the value from a completion item (if
+ * provided and not `null`) will always be used instead of the value from
+ * `completionItem.itemDefaults`.
+ * 
+ * If a field's value is "merge", the values will be merged using the rules
+ * defined against each field below.
+ *
+ * Servers are only allowed to return `applyKind` if the client
+ * signals support for this via the `completionList.applyKindSupport`
+ * capability.
+ *
+ * @since 3.18.0
+ */
+ applyKind?: {
+ /**
+ * Specifies whether commitCharacters on a completion will replace or be
+ * merged with those in `completionList.itemDefaults.commitCharacters`.
+ * 
+ * If "replace", the commit characters from the completion item will
+ * always be used unless not provided (or `null`), in which case those
+ * from `completionList.itemDefaults.commitCharacters` will be used. An
+ * empty list can be used if a completion item does not have any commit
+ * characters and also should not use those from
+ * `completionList.itemDefaults.commitCharacters`.
+ * 
+ * If "merge" the commitCharacters for the completion will be the union
+ * of all values in both `completionList.itemDefaults.commitCharacters`
+ * and the completion's own `commitCharacters`.
+ *
+ * @since 3.18.0
+ */
+ commitCharacters?: ApplyKind;
+
+ /**
+ * Specifies whether the `data` field on a completion will replace or
+ * be merged with data from `completionList.itemDefaults.data`.
+ * 
+ * If "replace", the data from the completion item will be used if
+ * provided (and not `null`), otherwise
+ * `completionList.itemDefaults.data` will be used. An empty object can
+ * be used if a completion item does not have any data but also should
+ * not use the value from `completionList.itemDefaults.data`.
+ * 
+ * If "merge", a shallow merge will be performed between
+ * `completionList.itemDefaults.data` and the completion's own data
+ * using the following rules:
+ * 
+ * - If a completion's `data` field is not provided (or `null`), the
+ * entire `data` field from `completionList.itemDefaults.data` will be
+ * used as-is.
+ * - If a completion's `data` field is provided, each field will
+ * overwrite the field of the same name in
+ * `completionList.itemDefaults.data` but no merging of nested fields
+ * within that value will occur.
+ *
+ * @since 3.18.0
+ */
+ data?: ApplyKind;
+ }
+
  /**
  * The completion items.
  */
@@ -525,6 +608,32 @@ export interface CompletionItemLabelDetails {
 }
 ```
 
+<div class="anchorHolder"><a href="#applyKind" name="applyKind" class="linkableAnchor"></a></div>
+
+```typescript
+/**
+ * Defines how values from a set of defaults and an individual item will be
+ * merged.
+ */
+export namespace ApplyKind {
+ /**
+ * The value from the individual item (if provided and not `null`) will be
+ * used instead of the default.
+ */
+ export const Replace: 'replace' = 'replace;
+
+ /**
+ * The value from the item will be merged with the default.
+ * 
+ * The specific rules for mergeing values are defined against each field
+ * that supports merging.
+ */
+ export const Merge: 'merge' = 'merge';
+}
+
+export type ApplyKind = ApplyKind.Replace | ApplyKind.Merge;
+```
+
 <div class="anchorHolder"><a href="#completionItem" name="completionItem" class="linkableAnchor"></a></div>
 
 ```typescript

_specifications/lsp/3.18/specification.md

@@ -737,6 +737,7 @@ Since 3.17 there is a meta model describing the LSP protocol:
 * Support for snippets in text document edits.
 * Support for debug message kind.
 * Client capability to enumerate properties that can be resolved for code lenses.
+* Added support for `completionList.applyKind` to determine how values from `completionList.itemDefaults` and `completion` are combined.
 
 
 #### <a href="#version_3_17_0" name="version_3_17_0" class="anchor">3.17.0 (05/10/2022)</a>