Specification for MarkupContent support in diagnostic messages (#1905)

* add markup diagnostic message spec

* Update metamodel

Author: Maria José Solano

_specifications/lsp/3.18/general/initialize.md

@@ -885,6 +885,28 @@ interface ServerCapabilities {
 	 */
 	inlineCompletionProvider?: boolean | InlineCompletionOptions;
 
+	/**
+	 * Text document specific server capabilities.
+	 * 
+	 * @since 3.18.0
+	 */
+	textDocument?: {
+		/**
+		 * Capabilities specific to the diagnostic pull model.
+		 * 
+		 * @since 3.18.0
+		 */
+		diagnostic?: {
+			/**
+			 * Whether the server supports `MarkupContent` in diagnostic messages.
+			 * 
+			 * @since 3.18.0
+			 * @proposed
+			 */
+			markupMessageSupport?: boolean;
+		};
+	};
+
 	/**
 	 * Workspace specific server capabilities
 	 */

_specifications/lsp/3.18/language/codeAction.md

@@ -361,6 +361,9 @@ export interface CodeActionContext {
 	 * for the given range. There is no guarantee that these accurately reflect
 	 * the error state of the resource. The primary parameter
 	 * to compute code actions is the provided range.
+	 * 
+	 * Note that the client should check the `textDocument.diagnostic.markupMessageSupport`
+	 * server capability before sending diagnostics with markup messages to a server.
 	 */
 	diagnostics: Diagnostic[];
 

_specifications/lsp/3.18/language/pullDiagnostics.md

@@ -30,6 +30,14 @@ export interface DiagnosticClientCapabilities {
 	 * pulls.
 	 */
 	relatedDocumentSupport?: boolean;
+
+	/**
+	 * Whether the client supports `MarkupContent` in diagnostic messages.
+	 * 
+	 * @since 3.18.0
+	 * @proposed
+	 */
+	markupMessageSupport?: boolean;
 }
 ```
 

_specifications/lsp/3.18/metaModel/metaModel.json

@@ -8736,6 +8736,41 @@
 					"since": "3.18.0",
 					"proposed": true
 				},
+				{
+					"name": "textDocument",
+					"type": {
+						"kind": "literal",
+						"value": {
+							"properties": [
+								{
+									"name": "diagnostic",
+									"type": {
+										"kind": "literal",
+										"properties": [
+											{
+												"name": "markupMessageSupport",
+												"type": {
+													"kind": "base",
+													"name": "boolean"
+												},
+												"optional": true,
+												"documentation": "Whether the server supports `MarkupContent` in diagnostic messages.",
+												"since": "3.18.0",
+												"proposed": true
+											}
+										]
+									},
+									"optional": true,
+									"documentation": "Capabilities specific to the diagnostic pull model.\n\n@since 3.18.0",
+									"since": "3.18.0"
+								}
+							]
+						}
+					},
+					"optional": true,
+					"documentation": "Text document specific server capabilities.\n\n@since 3.18.0\n@proposed",
+					"since": "3.18.0"
+				},
 				{
 					"name": "workspace",
 					"type": {
@@ -8920,10 +8955,19 @@
 				{
 					"name": "message",
 					"type": {
-						"kind": "base",
-						"name": "string"
+						"kind": "or",
+						"items": [
+							{
+								"kind": "base",
+								"name": "string"
+							},
+							{
+								"kind": "reference",
+								"name": "MarkupContent"
+							}
+						]
 					},
-					"documentation": "The diagnostic's message. It usually appears in the user interface"
+					"documentation": "The diagnostic's message. It usually appears in the user interface.\n\n@since 3.18.0 - support for `MarkupContent`. This is guarded by the client capability `textDocument.diagnostic.markupMessageSupport`."
 				},
 				{
 					"name": "tags",
@@ -9388,7 +9432,7 @@
 							"name": "Diagnostic"
 						}
 					},
-					"documentation": "An array of diagnostics known on the client side overlapping the range provided to the\n`textDocument/codeAction` request. They are provided so that the server knows which\nerrors are currently presented to the user for the given range. There is no guarantee\nthat these accurately reflect the error state of the resource. The primary parameter\nto compute code actions is the provided range."
+					"documentation": "An array of diagnostics known on the client side overlapping the range provided to the\n`textDocument/codeAction` request. They are provided so that the server knows which\nerrors are currently presented to the user for the given range. There is no guarantee\nthat these accurately reflect the error state of the resource. The primary parameter\nto compute code actions is the provided range.\n\nNote that the client should check the `textDocument.diagnostic.markupMessageSupport` server capability before sending diagnostics with markup messages to a server."
 				},
 				{
 					"name": "only",
@@ -12870,6 +12914,17 @@
 					},
 					"optional": true,
 					"documentation": "Whether the clients supports related documents for document diagnostic pulls."
+				},
+				{
+					"name": "markupMessageSupport",
+					"type": {
+						"kind": "base",
+						"name": "boolean"
+					},
+					"optional": true,
+					"documentation": "Whether the client supports `MarkupContent` in diagnostic messages.",
+					"since": "3.18.0",
+					"proposed": true
 				}
 			],
 			"documentation": "Client capabilities specific to diagnostic pull requests.\n\n@since 3.17.0",

_specifications/lsp/3.18/types/diagnostic.md

@@ -1,5 +1,9 @@
 #### <a href="#diagnostic" name="diagnostic" class="anchor"> Diagnostic </a>
 
+- New in version 3.18: support for markup content in diagnostic messages. The support is guarded by the 
+client capability `textDocument.diagnostic.markupMessageSupport`. If a client doesn't signal the capability, 
+servers shouldn't send `MarkupContent` diagnostic messages back to the client.
+
 Represents a diagnostic, such as a compiler error or warning. Diagnostic objects are only valid in the scope of a resource.
 
 ```typescript
@@ -35,8 +39,11 @@ export interface Diagnostic {
 
 	/**
 	 * The diagnostic's message.
+	 * 
+	 * @since 3.18.0 - support for MarkupContent. This is guarded by the client
+	 * capability `textDocument.diagnostic.markupMessageSupport`.
 	 */
-	message: string;
+	message: string | MarkupContent;
 
 	/**
 	 * Additional metadata about the diagnostic.