Make specification more machine-readable

[hediet]

It would be very handy if parts of the specification could be read by machines.
This would help developing SDKs for typed languages a lot, as many types can be auto generated.

Besides, there are some inconsistencies in non-normative parts of the specification that could be easily fixed (e.g. interfaces vs exported interfaces, params vs param).

Something like this would be awesome in addition to the existing specification:
(comments removed to keep it short)

interface RequestMessage<TMethod extends string, TParams> {
    id: number | string;
    method: TMethod;
    params: TParams
}

interface ResponseMessage<TResult, TError> {
    id: number | string;
    result?: TResult;
    error?: ResponseError<TError>;
}

interface Request<TRequest, TResponse> {}
interface Notification<TRequest> {}

// ...

type InitializeRequest = Request<
    RequestMessage<"initialize", InitializeParams>,
    ResponseMessage<InitializeResult, InitializeError>
>;

type ShutdownRequest = Request<
    RequestMessage<"shutdown", undefined>,
    ResponseMessage<undefined, undefined>
>;

type ShowMessageNotification = Notification<
    RequestMessage<"window/showMessage", ShowMessageParams>
>;

What do you think? I can offer to add these additional typescript definitions for all of the about 30 notifications / requests.

[gorkem]

#25 may be related

[hediet]

The link mentioned in the first comment in #25 is not valid anymore and #40 only covers the types, not the actual protocol (methods, request/notification, expected response types and so on).

[hediet]

I basically was looking for protocol.ts.

[dbaeumer]

Agree with @gorkem that a machine readable specification should be in JSON Schema since this is more universal. There are quite some tools out there to generate interface files from JSON for different languages.

[felixfbecker]

JSON schema would be awesome, and also allow to be more specific than TS interfaces. For example, you can apply RegExp constraints to strings.

[vicencb]

An editor will need to have fast response times from a server to be interactive.
It looks to me that a text based protocol will hurt this interactivity. It is well known that text processing is much slower than well structured binary data.
So, why not use protocol buffers:
https://github.com/google/upb

With upb the backend can be chosen:

1. use the fast protocol buffers in release mode
2. use the human readable JSON format in debug mode

The protocol is defined with an schema and is fully machine-readable.

[dbaeumer]

@vicencb the protocol buffer is about the transport. Since the message header allows to specify a content type we can send binary data if this is necessary due to performance.

This issue is about having the specification in a machine readable from.

[DanTup]

Not sure if you want to collect examples of what's difficult to parse here in this issue, but I just came across another one and thought it worth noting.. The response to textDocument/prepareRename is documented as Range | { range: Range, placeholder: string } | null.

However this text only appears in the results: note against the request, there's no typescript codeblock with the definition. This means if you want to codegen a class for the range+placeholder, you need to regex it out, but the same line contains a bunch of english:

• result: Range | { range: Range, placeholder: string } | null describing the range of the string to rename and optionally a placeholder text of the string content to be renamed. If null is returned then it is deemed that a 'textDocument/rename' request is not valid at the given position.

I really want to avoid too many special cases to make it easier to keep my classes up-to-date, but now I have a regex like \* result:[^\.]*({.*}) to try and extract this reliably. The rest of the spec outgrew my regexes (they got really complicated) and I ended up writing a small TypeScript parser in order to extract everything from here). I don't know how the other servers are doing it, but it feels like a bit of a burden :-(

[DanTup]

Another inconsistency found while parsing:

Some notifications list their params as params: void and others use params: none. As far as I can tell, these mean the same, which is the params field can be omitted.

[dbaeumer]

@DanTup when I started to convert this to JSON schema I used a TS compiler to parse the TS file from https://github.com/Microsoft/vscode-languageserver-node/blob/dbaeumer/464/protocol/src/protocol.ts#L1 which should give the best result.