From 37f8e3e3b3798b27d92aa4f971d11b26b4c39772 Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Mon, 8 Dec 2025 15:34:29 +0100 Subject: [PATCH 01/10] Extended CallHierarchyItem with the optional field referenceTags of type ReferenceTag[]. --- .../lsp/3.18/language/callHierarchy.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/_specifications/lsp/3.18/language/callHierarchy.md b/_specifications/lsp/3.18/language/callHierarchy.md index 6567d119b..61dcd08ab 100644 --- a/_specifications/lsp/3.18/language/callHierarchy.md +++ b/_specifications/lsp/3.18/language/callHierarchy.md @@ -69,6 +69,19 @@ _Response_:
```typescript +export namespace ReferenceTag { + /** + * Statement with r-value usage of the referenced variable. + */ + export const Read = 1; + /** + * Statement with l-value usage of the referenced variable. + */ + export const Write = 2; +} + +export type ReferenceTag = 1 | 2; + export interface CallHierarchyItem { /** * The name of this item. @@ -85,6 +98,11 @@ export interface CallHierarchyItem { */ tags?: SymbolTag[]; + /** + * Reference tags of this item. + */ + referenceTags?: ReferenceTag[]; + /** * More detail for this item, e.g. the signature of a function. */ From 2460a2fe25b8c29f05f7264eca757dda7dac540c Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Tue, 3 Feb 2026 21:07:41 +0100 Subject: [PATCH 02/10] doc: description for the new field. --- _specifications/lsp/3.18/metaModel/metaModel.json | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/_specifications/lsp/3.18/metaModel/metaModel.json b/_specifications/lsp/3.18/metaModel/metaModel.json index f54ba757a..6aa99c155 100644 --- a/_specifications/lsp/3.18/metaModel/metaModel.json +++ b/_specifications/lsp/3.18/metaModel/metaModel.json @@ -3043,6 +3043,18 @@ "optional": true, "documentation": "Tags for this item." }, + { + "name": "referenceTags", + "type": { + "kind": "array", + "element": { + "kind": "reference", + "name": "ReferenceTag" + } + }, + "optional": true, + "documentation": "Reference tags for this item, i.e. determines the operations on the referenced symbol, read, write or both" + }, { "name": "detail", "type": { From cdd179688a9d0c2ffca5c31ca79eb6224ac3f5c3 Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Tue, 3 Feb 2026 21:41:49 +0100 Subject: [PATCH 03/10] doc: descriptions for ReferenceTag. --- .../lsp/3.18/language/callHierarchy.md | 4 ++-- .../lsp/3.18/metaModel/metaModel.json | 21 +++++++++++++++++++ 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/_specifications/lsp/3.18/language/callHierarchy.md b/_specifications/lsp/3.18/language/callHierarchy.md index 61dcd08ab..85d3e4ae0 100644 --- a/_specifications/lsp/3.18/language/callHierarchy.md +++ b/_specifications/lsp/3.18/language/callHierarchy.md @@ -71,11 +71,11 @@ _Response_: ```typescript export namespace ReferenceTag { /** - * Statement with r-value usage of the referenced variable. + * Determines a read access to the referenced symbol. */ export const Read = 1; /** - * Statement with l-value usage of the referenced variable. + * Determines a write access to the referenced symbol. */ export const Write = 2; } diff --git a/_specifications/lsp/3.18/metaModel/metaModel.json b/_specifications/lsp/3.18/metaModel/metaModel.json index bc94ca209..2d9e3f96d 100644 --- a/_specifications/lsp/3.18/metaModel/metaModel.json +++ b/_specifications/lsp/3.18/metaModel/metaModel.json @@ -14585,6 +14585,27 @@ "documentation": "Symbol tags are extra annotations that tweak the rendering of a symbol.\n\n@since 3.16", "since": "3.16" }, + { + "name": "RferenceTag", + "type": { + "kind": "base", + "name": "uinteger" + }, + "values": [ + { + "name": "Read", + "value": 1, + "documentation": "Determines a read access to the referenced symbol." + }, + { + "name": "Write", + "value": 2, + "documentation": "Determines a write access to the referenced symbol." + } + ], + "documentation": "Reference tags are extra annotations that provide additional information about references.\n\n@since 3.18", + "since": "3.18" + }, { "name": "UniquenessLevel", "type": { From 2ac36277a547d4600c908d51215e044d3e82fd7c Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Fri, 6 Feb 2026 10:39:06 +0100 Subject: [PATCH 04/10] New: client capabilities for reference tags in ReferenceClientCapabilities and CallHierarchyClientCapabilities. New: Reference interface aggregating Location and reference tags. Change: response of the method textDocument/references now can contain the array with objects of the new type Reference. --- .../lsp/3.18/language/callHierarchy.md | 13 ++++++++++++ .../lsp/3.18/language/references.md | 17 ++++++++++++++-- .../lsp/3.18/metaModel/metaModel.json | 20 +++++++++++++++++++ _specifications/lsp/3.18/types/reference.md | 9 +++++++++ 4 files changed, 57 insertions(+), 2 deletions(-) create mode 100644 _specifications/lsp/3.18/types/reference.md diff --git a/_specifications/lsp/3.18/language/callHierarchy.md b/_specifications/lsp/3.18/language/callHierarchy.md index 85d3e4ae0..890c81792 100644 --- a/_specifications/lsp/3.18/language/callHierarchy.md +++ b/_specifications/lsp/3.18/language/callHierarchy.md @@ -23,6 +23,19 @@ interface CallHierarchyClientCapabilities { * capability as well. */ dynamicRegistration?: boolean; + + /** + * Whether client supports reference tags. + * Clients supporting tags have to handle unknown tags gracefully. + * + * @since 3.18.0 + */ + tagSupport?: { + /** + * The tags supported by the client. + */ + valueSet: ReferenceTag[]; + }; } ``` diff --git a/_specifications/lsp/3.18/language/references.md b/_specifications/lsp/3.18/language/references.md index e7d2e0303..c3e0664cb 100644 --- a/_specifications/lsp/3.18/language/references.md +++ b/_specifications/lsp/3.18/language/references.md @@ -14,6 +14,19 @@ export interface ReferenceClientCapabilities { * Whether references supports dynamic registration. */ dynamicRegistration?: boolean; + + /** + * Determines whether the client supports reference tags, and if so, which ones exactly. + * Clients supporting tags have to handle unknown tags gracefully. + * + * @since 3.18.0 + */ + tagSupport?: { + /** + * The tags supported by the client. + */ + valueSet: ReferenceTag[]; + }; } ``` @@ -62,6 +75,6 @@ export interface ReferenceContext { } ``` _Response_: -* result: [`Location`](#location)[] \| `null` -* partial result: [`Location`](#location)[] +* result: [`Location`](#location)[] \| [`Reference`](#reference)[] \| `null` +* partial result: [`Location`](#location)[] \| [`Reference`](#reference)[] * error: code and message set in case an exception happens during the reference request. diff --git a/_specifications/lsp/3.18/metaModel/metaModel.json b/_specifications/lsp/3.18/metaModel/metaModel.json index 2d9e3f96d..cbd9c36f7 100644 --- a/_specifications/lsp/3.18/metaModel/metaModel.json +++ b/_specifications/lsp/3.18/metaModel/metaModel.json @@ -12734,6 +12734,16 @@ }, "optional": true, "documentation": "Whether references supports dynamic registration." + }, + { + "name": "tagSupport", + "type": { + "kind": "reference", + "name": "ClientReferenceTagOptions" + }, + "optional": true, + "documentation": "Determines whether the client supports reference tags, and if so, which ones exactly.\nClients supporting tags have to handle unknown tags gracefully.", + "since": "3.18.0" } ], "documentation": "Client Capabilities for a {@link ReferencesRequest}." @@ -13165,6 +13175,16 @@ }, "optional": true, "documentation": "Whether implementation supports dynamic registration. If this is set to `true`\nthe client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`\nreturn value for the corresponding server capability as well." + }, + { + "name": "tagSupport", + "type": { + "kind": "reference", + "name": "ClientReferenceTagOptions" + }, + "optional": true, + "documentation": "Determines whether the client supports reference tags, and if so, which ones exactly.\nClients supporting tags have to handle unknown tags gracefully.", + "since": "3.18.0" } ], "documentation": "@since 3.16.0", diff --git a/_specifications/lsp/3.18/types/reference.md b/_specifications/lsp/3.18/types/reference.md new file mode 100644 index 000000000..e571cb1f0 --- /dev/null +++ b/_specifications/lsp/3.18/types/reference.md @@ -0,0 +1,9 @@ +#### Reference + +Represents a reference inside the workspace. A reference has a location and can have one or more tags. +```typescript +interface Reference { + location: Location; + referenceTags: ReferenceTag[]; +} +``` From e3cf0405bcb17d63ab24b3dd38d427c1d07caa0d Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Fri, 6 Feb 2026 15:44:05 +0100 Subject: [PATCH 05/10] Change: replaced capability array with one optional flag in ReferenceClientCapabilities and in CallHierarchyClientCapabilities. Change: referenceTags is optional in Reference interface. --- _specifications/lsp/3.18/language/callHierarchy.md | 11 ++--------- _specifications/lsp/3.18/language/references.md | 11 ++--------- _specifications/lsp/3.18/metaModel/metaModel.json | 12 ++++++------ _specifications/lsp/3.18/types/reference.md | 2 +- 4 files changed, 11 insertions(+), 25 deletions(-) diff --git a/_specifications/lsp/3.18/language/callHierarchy.md b/_specifications/lsp/3.18/language/callHierarchy.md index 890c81792..95595e1d5 100644 --- a/_specifications/lsp/3.18/language/callHierarchy.md +++ b/_specifications/lsp/3.18/language/callHierarchy.md @@ -25,17 +25,10 @@ interface CallHierarchyClientCapabilities { dynamicRegistration?: boolean; /** - * Whether client supports reference tags. - * Clients supporting tags have to handle unknown tags gracefully. - * + * Determines whether the client supports reference tags. * @since 3.18.0 */ - tagSupport?: { - /** - * The tags supported by the client. - */ - valueSet: ReferenceTag[]; - }; + referenceItemSupport?: boolean; } ``` diff --git a/_specifications/lsp/3.18/language/references.md b/_specifications/lsp/3.18/language/references.md index c3e0664cb..d3dc8d611 100644 --- a/_specifications/lsp/3.18/language/references.md +++ b/_specifications/lsp/3.18/language/references.md @@ -16,17 +16,10 @@ export interface ReferenceClientCapabilities { dynamicRegistration?: boolean; /** - * Determines whether the client supports reference tags, and if so, which ones exactly. - * Clients supporting tags have to handle unknown tags gracefully. - * + * Determines whether the client supports reference tags. * @since 3.18.0 */ - tagSupport?: { - /** - * The tags supported by the client. - */ - valueSet: ReferenceTag[]; - }; + referenceItemSupport?: boolean; } ``` diff --git a/_specifications/lsp/3.18/metaModel/metaModel.json b/_specifications/lsp/3.18/metaModel/metaModel.json index cbd9c36f7..c05fdf075 100644 --- a/_specifications/lsp/3.18/metaModel/metaModel.json +++ b/_specifications/lsp/3.18/metaModel/metaModel.json @@ -12736,13 +12736,13 @@ "documentation": "Whether references supports dynamic registration." }, { - "name": "tagSupport", + "name": "referenceItemSupport", "type": { "kind": "reference", - "name": "ClientReferenceTagOptions" + "name": "ClientReferenceTagSupportOption" }, "optional": true, - "documentation": "Determines whether the client supports reference tags, and if so, which ones exactly.\nClients supporting tags have to handle unknown tags gracefully.", + "documentation": "Determines whether the client supports reference tags.", "since": "3.18.0" } ], @@ -13177,13 +13177,13 @@ "documentation": "Whether implementation supports dynamic registration. If this is set to `true`\nthe client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`\nreturn value for the corresponding server capability as well." }, { - "name": "tagSupport", + "name": "referenceItemSupport", "type": { "kind": "reference", - "name": "ClientReferenceTagOptions" + "name": "ClientReferenceTagSupportOption" }, "optional": true, - "documentation": "Determines whether the client supports reference tags, and if so, which ones exactly.\nClients supporting tags have to handle unknown tags gracefully.", + "documentation": "Determines whether the client supports reference tags.", "since": "3.18.0" } ], diff --git a/_specifications/lsp/3.18/types/reference.md b/_specifications/lsp/3.18/types/reference.md index e571cb1f0..3d6b53f55 100644 --- a/_specifications/lsp/3.18/types/reference.md +++ b/_specifications/lsp/3.18/types/reference.md @@ -4,6 +4,6 @@ Represents a reference inside the workspace. A reference has a location and can ```typescript interface Reference { location: Location; - referenceTags: ReferenceTag[]; + referenceTags?: ReferenceTag[]; } ``` From a7fea238462ee9e4993d7b01ba9c7d781b7a1fbe Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Fri, 6 Feb 2026 16:05:28 +0100 Subject: [PATCH 06/10] Change: renamed referenceItemSupport to referencesItemSupport --- _specifications/lsp/3.18/language/callHierarchy.md | 2 +- _specifications/lsp/3.18/language/references.md | 2 +- _specifications/lsp/3.18/metaModel/metaModel.json | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/_specifications/lsp/3.18/language/callHierarchy.md b/_specifications/lsp/3.18/language/callHierarchy.md index 95595e1d5..6a1c97dfd 100644 --- a/_specifications/lsp/3.18/language/callHierarchy.md +++ b/_specifications/lsp/3.18/language/callHierarchy.md @@ -28,7 +28,7 @@ interface CallHierarchyClientCapabilities { * Determines whether the client supports reference tags. * @since 3.18.0 */ - referenceItemSupport?: boolean; + referencesItemSupport?: boolean; } ``` diff --git a/_specifications/lsp/3.18/language/references.md b/_specifications/lsp/3.18/language/references.md index d3dc8d611..64b7cd5b2 100644 --- a/_specifications/lsp/3.18/language/references.md +++ b/_specifications/lsp/3.18/language/references.md @@ -19,7 +19,7 @@ export interface ReferenceClientCapabilities { * Determines whether the client supports reference tags. * @since 3.18.0 */ - referenceItemSupport?: boolean; + referencesItemSupport?: boolean; } ``` diff --git a/_specifications/lsp/3.18/metaModel/metaModel.json b/_specifications/lsp/3.18/metaModel/metaModel.json index c05fdf075..2d6d80a7d 100644 --- a/_specifications/lsp/3.18/metaModel/metaModel.json +++ b/_specifications/lsp/3.18/metaModel/metaModel.json @@ -12736,7 +12736,7 @@ "documentation": "Whether references supports dynamic registration." }, { - "name": "referenceItemSupport", + "name": "referencesItemSupport", "type": { "kind": "reference", "name": "ClientReferenceTagSupportOption" @@ -13177,7 +13177,7 @@ "documentation": "Whether implementation supports dynamic registration. If this is set to `true`\nthe client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`\nreturn value for the corresponding server capability as well." }, { - "name": "referenceItemSupport", + "name": "referencesItemSupport", "type": { "kind": "reference", "name": "ClientReferenceTagSupportOption" From 63272d2cfa172e11f6627326417ffa736dc164f8 Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Fri, 6 Feb 2026 16:36:59 +0100 Subject: [PATCH 07/10] Change: rephrased comments for CallHierarchyClientCapabilities.referencesItemSupport and for ReferenceClientCapabilities.referencesTagSupport. --- _specifications/lsp/3.18/language/callHierarchy.md | 3 ++- _specifications/lsp/3.18/language/references.md | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/_specifications/lsp/3.18/language/callHierarchy.md b/_specifications/lsp/3.18/language/callHierarchy.md index 6a1c97dfd..9e7d65d4e 100644 --- a/_specifications/lsp/3.18/language/callHierarchy.md +++ b/_specifications/lsp/3.18/language/callHierarchy.md @@ -25,7 +25,8 @@ interface CallHierarchyClientCapabilities { dynamicRegistration?: boolean; /** - * Determines whether the client supports reference tags. + * Determines whether the client supports reference tags. If the value is missing, + * the server assumes that the client does not support reference tags. * @since 3.18.0 */ referencesItemSupport?: boolean; diff --git a/_specifications/lsp/3.18/language/references.md b/_specifications/lsp/3.18/language/references.md index 64b7cd5b2..3fd59b8d3 100644 --- a/_specifications/lsp/3.18/language/references.md +++ b/_specifications/lsp/3.18/language/references.md @@ -16,10 +16,12 @@ export interface ReferenceClientCapabilities { dynamicRegistration?: boolean; /** - * Determines whether the client supports reference tags. + * Determines whether the client supports and prefers Reference items instead + * of Location items. If this value is missing, the server assumes that the + * client accepts Location items as defined in earlier versions of the protocol. * @since 3.18.0 */ - referencesItemSupport?: boolean; + referencesTagSupport?: boolean; } ``` From dd3784490a1d3d1b77d244dcb895ed3dcc4da26a Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Sun, 8 Feb 2026 21:21:17 +0100 Subject: [PATCH 08/10] Fix: renamed referencesItemSupport to referenceTagsSupport in CallHierarchyClientCapabilities. Fix: renamed referencesTagSupport to referenceItemsSupport in ReferenceClientCapabilities. --- _specifications/lsp/3.18/language/callHierarchy.md | 2 +- _specifications/lsp/3.18/language/references.md | 2 +- _specifications/lsp/3.18/metaModel/metaModel.json | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/_specifications/lsp/3.18/language/callHierarchy.md b/_specifications/lsp/3.18/language/callHierarchy.md index 9e7d65d4e..8a8496a9c 100644 --- a/_specifications/lsp/3.18/language/callHierarchy.md +++ b/_specifications/lsp/3.18/language/callHierarchy.md @@ -29,7 +29,7 @@ interface CallHierarchyClientCapabilities { * the server assumes that the client does not support reference tags. * @since 3.18.0 */ - referencesItemSupport?: boolean; + referenceTagsSupport?: boolean; } ``` diff --git a/_specifications/lsp/3.18/language/references.md b/_specifications/lsp/3.18/language/references.md index 3fd59b8d3..70d12fa96 100644 --- a/_specifications/lsp/3.18/language/references.md +++ b/_specifications/lsp/3.18/language/references.md @@ -21,7 +21,7 @@ export interface ReferenceClientCapabilities { * client accepts Location items as defined in earlier versions of the protocol. * @since 3.18.0 */ - referencesTagSupport?: boolean; + referenceItemsSupport?: boolean; } ``` diff --git a/_specifications/lsp/3.18/metaModel/metaModel.json b/_specifications/lsp/3.18/metaModel/metaModel.json index 2d6d80a7d..78617d540 100644 --- a/_specifications/lsp/3.18/metaModel/metaModel.json +++ b/_specifications/lsp/3.18/metaModel/metaModel.json @@ -12736,13 +12736,13 @@ "documentation": "Whether references supports dynamic registration." }, { - "name": "referencesItemSupport", + "name": "referenceItemsSupport", "type": { "kind": "reference", "name": "ClientReferenceTagSupportOption" }, "optional": true, - "documentation": "Determines whether the client supports reference tags.", + "documentation": "Determines whether the client supports and prefers Reference items instead\nof Location items. If this value is missing, the server assumes that the\nclient accepts Location items as defined in earlier versions of the protocol.", "since": "3.18.0" } ], @@ -13177,7 +13177,7 @@ "documentation": "Whether implementation supports dynamic registration. If this is set to `true`\nthe client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`\nreturn value for the corresponding server capability as well." }, { - "name": "referencesItemSupport", + "name": "referenceTagsSupport", "type": { "kind": "reference", "name": "ClientReferenceTagSupportOption" From 30c3137fc8df584095d5745328fb2bf445c799ba Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Tue, 10 Feb 2026 22:08:28 +0100 Subject: [PATCH 09/10] Fix: format --- _specifications/lsp/3.18/language/references.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_specifications/lsp/3.18/language/references.md b/_specifications/lsp/3.18/language/references.md index 70d12fa96..9911a9d70 100644 --- a/_specifications/lsp/3.18/language/references.md +++ b/_specifications/lsp/3.18/language/references.md @@ -10,10 +10,10 @@ _Client Capability_: ```typescript export interface ReferenceClientCapabilities { - /** - * Whether references supports dynamic registration. - */ - dynamicRegistration?: boolean; + /** + * Whether references supports dynamic registration. + */ + dynamicRegistration?: boolean; /** * Determines whether the client supports and prefers Reference items instead From ddffe1d268bc67ab5958d1082e5716e533c870c4 Mon Sep 17 00:00:00 2001 From: Dimitri Ratz Date: Tue, 10 Feb 2026 22:09:18 +0100 Subject: [PATCH 10/10] Doc: added/reword comments. --- _specifications/lsp/3.18/types/reference.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/_specifications/lsp/3.18/types/reference.md b/_specifications/lsp/3.18/types/reference.md index 3d6b53f55..d8324a877 100644 --- a/_specifications/lsp/3.18/types/reference.md +++ b/_specifications/lsp/3.18/types/reference.md @@ -1,9 +1,20 @@ -#### Reference +#### Reference + +> *Since version 3.18.0* Represents a reference inside the workspace. A reference has a location and can have one or more tags. + ```typescript interface Reference { - location: Location; - referenceTags?: ReferenceTag[]; + /** + * The location of this reference. + * @since 3.18.0 + */ + location: Location; + /** + * Optional, one or more tags describing this reference. + * @since 3.18.0 + */ + referenceTags?: ReferenceTag[]; } ```