Make PositionEncodingKind a type

_specifications/lsp/3.17/general/initialize.md

@@ -510,13 +510,6 @@ interface ClientCapabilities {
 		 *
 		 * If omitted it defaults to ['utf-16'].
 		 *
-		 * For the following standard Unicode encodings these values should be
-		 * used:
-		 *
-		 * UTF-8: 'utf-8'
-		 * UTF-16: 'utf-16'
-		 * UTF-32: 'utf-32'
-		 *
 		 * Implementation considerations: since the conversion from one encoding
 		 * into another requires the content of the file / line the conversion
 		 * is best done where the file is read which is usually on the server
@@ -525,7 +518,7 @@ interface ClientCapabilities {
 		 * @since 3.17.0
 		 * @proposed
 		 */
-		positionEncodings?: ('utf-16' | 'utf-8' | 'utf-32' | string)[];
+		positionEncodings?: PositionEncodingKind[];
 	};
 
 	/**
@@ -621,7 +614,7 @@ interface ServerCapabilities {
 	 * @since 3.17.0
 	 * @proposed
 	 */
-	positionEncoding?: 'utf-16' | 'utf-8' | 'utf-32' | string;
+	positionEncoding?: PositionEncodingKind;
 
 	/**
 	 * Defines how text documents are synced. Is either a detailed structure
@@ -873,4 +866,4 @@ interface ServerCapabilities {
 	 */
 	experimental?: LSPAny;
 }
-```
+```

_specifications/lsp/3.17/types/position.md

@@ -10,13 +10,51 @@ interface Position {
 	line: uinteger;
 
 	/**
-	 * Character offset on a line in a document (zero-based). Assuming that
-	 * the line is represented as a string, the `character` value represents
-	 * the gap between the `character` and `character + 1`.
+	 * Character offset on a line in a document (zero-based). The meaning of this
+	 * offset is determined by the negotiated `PositionEncodingKind`.
 	 *
 	 * If the character value is greater than the line length it defaults back
 	 * to the line length.
 	 */
 	character: uinteger;
 }
-```
+```
+
+When describing positions the protocol needs to specify how offsets (specifically character offsets) should be interpreted.
+The corresponding `PostionEncodingKind` is negotiated between the client and the server during initialization.
+
+```typscript
+/**
+ * A type indicating how positions are encoded,
+ * specifically what column offsets mean.
+ */
+export type PositionEncodingKind = string;
+
+/**
+ * A set of predefined position encoding kinds.
+ */
+export namespace PositionEncodingKind {
+
+	/**
+	 * Character offsets count UTF-8 code units.
+	 */
+	export const UTF8: PositionEncodingKind = 'utf-8';
+
+	/**
+	 * Character offsets count UTF-16 code units.
+	 *
+	 * This is the default and must always be supported
+	 * by servers
+	 */
+	export const UTF16: PositionEncodingKind = 'utf-16';
+
+	/**
+	 * Character offsets count UTF-32 code units. 
+	 *
+	 * Implementation note: these are the same as Unicode code points,
+	 * so this `PositionEncodingKind` may also be used for an 
+	 * encoding-agnostic representation of character offsets.
+	 */
+	export const UTF32: PositionEncodingKind = 'utf-32';
+}
+```