LSP Specification

Language Server Protocol

Microsoft has great documentation on the LSP specifications.

You can check out the full docks here: LSP Docs

High Level Overview

For web developers who write restful APIs, or work with JSON in general this specification will seem very familiar. The LSP is a JSON-RPC based protocol that allows developers to write language servers that can communicate with a wide variety of editors and IDEs (the client). It follows the simple request/response pattern that is common in web development.

Request/Response Pattern

Each request and response has two parts a header and content which are separated by a \r\n. The header simply describes the content length and the content type, content-type defaulting to application/vscode-jsonrpc; charset=utf-8, so for our purposes only Content-Length is required. The request content is a JSON object that contains four main fields:

1. jsonrpc - the version of the protocol (we’ll be using 2.0)

2. method - the method that is being called by the client for example this 'textDocument/definition' to go to a object or functions definiton in your IDE/editor.

3. params - the parameters that are passed with that method, each method has it’s own set of parameters that are necessary for each call to work.

4. id - the id of the request, this is used to match the response to the request.

Note

Example (taken from the LSP docs):

Content-Length: ...\r\n
\r\n
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "textDocument/completion",
  "params": {
    ...
  }
}

For a response the content is very similar but with a few key differences: rather than a method and parameters, a result or error field is returned. The response of course includes the id of the request.

There are a couple of other message types.

• Notification messages which are similar to requests but do not require a response, they work like events.

• Notification and requests whose methods start with ’$/’ are messages which might not be supported by all clients or servers.

• Finally there are cancellation and progress support, which we will not be covering in this guide.

Server Capabilities

Capabilities communicate between the client and server what features are supported. Both client and server capabilities are sent as part of the initialize request, we won’t be too worried about the client capabilities in this guide but the server capabilities are important.

Lifecycle Messages

The client in the LSP spec is doing more than just requesting information, it is also responsible for starting and stopping the server. There are a couple of lifecycle messages that are used for this purpose.

• Initialize && Initialized - This message is sent from the client which includes the clients capabilities previously mentioned. The client will not send any other messages until it receives a response from the server, this is the initial handshake.

• Register & Unregister - These messages are used to register and unregister capabilities with the server.

• Shutdown & Exit - These messages are used to stop the server.