LSIF Typed protocol reference

Descriptor

Name	Type	Description
name	string
disambiguator	string
suffix	Suffix

Suffix

Number	Name	Description
0	UnspecifiedSuffix
1	Package
2	Type
3	Term
4	Method
5	TypeParameter
6	Parameter
7	Meta	Can be used for any purpose.
8	Local

Diagnostic

Represents a diagnostic, such as a compiler error or warning, which should be reported for a document.

Name	Type	Description
severity	Severity	Should this diagnostic be reported as an error, warning, info, or hint?
code	string	Code of this diagnostic, which might appear in the user interface.
message	string	Message of this diagnostic.
source	string	Human-readable string describing the source of this diagnostic, e.g. 'typescript' or 'super lint'.
repeated tags	DiagnosticTag

Document

Document defines the metadata about a source file on disk.

Name	Type	Description
relative_path	string	(Required) Path to the text document relative to the directory supplied in the associated `Metadata.project_root`. Not URI-encoded. This value should not begin with a directory separator.
repeated occurrences	Occurrence	Occurrences that appear in this file.
repeated symbols	SymbolInformation	Symbols that are defined within this document.

Index

Index represents a complete LSIF index for a workspace this is rooted at a single directory. An Index message payload can have a large memory footprint and it's therefore recommended to emit and consume an Index payload one field value at a time. To permit streaming consumption of an Index payload, the metadata field must appear at the start of the stream and must only appear once in the stream. Other field values may appear in any order.

Name	Type	Description
metadata	Metadata	Metadata about this index.
repeated documents	Document	Documents that belong to this index.
repeated external_symbols	SymbolInformation	(optional) Symbols that are referenced from this index but are defined in an external package (a separate `Index` message). Leave this field empty if you assume the external package will get indexed separately. If the external package won't get indexed for some reason then you can use this field to provide hover documentation for those external symbols.

Metadata

Name	Type	Description
version	ProtocolVersion	Which version of this protocol was used to generate this index?
tool_info	ToolInfo	Information about the tool that produced this index.
project_root	string	URI-encoded absolute path to the root directory of this index. All documents in this index must appear in a subdirectory of this root directory.
text_document_encoding	TextEncoding	Text encoding of the source files on disk that are referenced from `Document.relative_path`.

Occurrence

Occurrence associates a source position with a symbol and/or highlighting information.

Name	Type	Description
repeated range	int32	Source position of this occurrence. Must be exactly three or four elements:
symbol	string	(optional) The symbol that appears at this position. See `SymbolInformation.symbol` for how to format symbols as strings.
symbol_roles	int32	(optional) Bitmask for what `SymbolRole` apply to this occurrence. See `SymbolRole` for how to read and write this field.
repeated override_documentation	string	(optional) Markdown-formatted documentation for this specific range. If empty, the `Symbol.documentation` field is used instead. One example where this field might be useful is when the symbol represents a generic function (with abstract type parameters such as `List<T>`) and at this occurrence we know the exact values (such as `List<String>`).
syntax_kind	SyntaxKind	(optional) What syntax highlighting class should be used for this range?
repeated diagnostics	Diagnostic	Diagnostics that have been reported for this specific range.

Additional notes on range:

Source position of this occurrence. Must be exactly three or four elements:

Four elements: [startLine, startCharacter, endLine, endCharacter]
Three elements: [startLine, startCharacter, endCharacter]. The end line is inferred to have the same value as the start line.

Line numbers and characters are always 0-based. Make sure to increment the line/character values before displaying them in an editor-like UI because editors conventionally use 1-based numbers.

Historical note: the original draft of this schema had a Range message type with start and end fields of type Position, mirroring LSP. Benchmarks revealed that this encoding was inefficient and that we could reduce the total payload size of an index by 50% by using repeated int32 instead. The repeated int32 encoding is admittedly more embarrassing to work with in some programming languages but we hope the performance improvements make up for it.

Package

Name	Type	Description
manager	string
name	string
version	string

Relationship

Name	Type	Description
symbol	string
is_reference	bool	When resolving "Find references", this field documents what other symbols should be included together with this symbol. For example, consider the following TypeScript code that defines two symbols `Animal#sound()` and `Dog#sound()`: ts interface Animal { ^^^^^^ definition Animal# sound(): string ^^^^^ definition Animal#sound() } class Dog implements Animal { ^^^ definition Dog#, implementation_symbols = Animal# public sound(): string { return "woof" } ^^^^^ definition Dog#sound(), references_symbols = Animal#sound(), implementation_symbols = Animal#sound() } const animal: Animal = new Dog() ^^^^^^ reference Animal# console.log(animal.sound()) ^^^^^ reference Animal#sound() Doing "Find references" on the symbol `Animal#sound()` should return references to the `Dog#sound()` method as well. Vice-versa, doing "Find references" on the `Dog#sound()` method should include references to the `Animal#sound()` method as well.
is_implementation	bool	Similar to `references_symbols` but for "Go to implementation". It's common for the `implementation_symbols` and `references_symbols` fields have the same values but that's not always the case. In the TypeScript example above, observe that `implementation_symbols` has the value `"Animal#"` for the "Dog#" symbol while `references_symbols` is empty. When requesting "Find references" on the "Animal#" symbol we don't want to include references to "Dog#" even if "Go to implementation" on the "Animal#" symbol should navigate to the "Dog#" symbol.
is_type_definition	bool	Similar to `references_symbols` but for "Go to type definition".

Symbol

Symbol is similar to a URI, it identifies a class, method, or a local variable. SymbolInformation contains rich metadata about symbols such as the docstring.

Symbol has a standardized string representation, which can be used interchangeably with Symbol. The syntax for Symbol is the following:

  <symbol>               ::= <scheme> ' ' <package> ' ' { <descriptor> } | 'local ' <local-id>
  <package>              ::= <manager> ' ' <package-name> ' ' <version>
  <scheme>               ::= any UTF-8, escape spaces with double space.
  <manager>              ::= same as above, use the placeholder '.' to indicate an empty value
  <package-name>         ::= same as above
  <version>              ::= same as above
  <descriptor>           ::= <package> | <type> | <term> | <method> | <type-parameter> | <parameter> | <meta>
  <package>              ::= <name> '/'
  <type>                 ::= <name> '#'
  <term>                 ::= <name> '.'
  <meta>                 ::= <name> ':'
  <method>               ::= <name> '(' <method-disambiguator> ').'
  <type-parameter>       ::= '[' <name> ']'
  <parameter>            ::= '(' <name> ')'
  <name>                 ::= <identifier>
  <method-disambiguator> ::= <simple-identifier>
  <identifier>           ::= <simple-identifier> | <escaped-identifier>
  <simple-identifier>    ::= { <identifier-character> }
  <identifier-character> ::= '_' | '+' | '-' | '$' | ASCII letter or digit
  <escaped-identifier>   ::= '`' { <escaped-character> } '`'
  <escaped-characters>   ::= any UTF-8 character, escape backticks with double backtick.

Name	Type	Description
scheme	string
package	Package
repeated descriptors	Descriptor

SymbolInformation

SymbolInformation defines metadata about a symbol, such as the symbol's docstring or what package it's defined it.

Name	Type	Description
symbol	string	Identifier of this symbol, which can be referenced from `Occurence.symbol`. The string must be formatted according to the grammar in `Symbol`.
repeated documentation	string	(optional, but strongly recommended) The markdown-formatted documentation for this symbol. This field is repeated to allow different kinds of documentation. For example, it's nice to include both the signature of a method (parameters and return type) along with the accompanying docstring.
repeated relationships	Relationship	(optional) Relationships to other symbols (e.g., implements, type definition).

ToolInfo

Name	Type	Description
name	string	Name of the indexer that produced this index.
version	string	Version of the indexer that produced this index.
repeated arguments	string	Command-line arguments that were used to invoke this indexer.

DiagnosticTag

Number	Name	Description
0	UnspecifiedDiagnosticTag
1	Unnecessary
2	Deprecated

ProtocolVersion

Number	Name	Description
0	UnspecifiedProtocolVersion

Severity

Number	Name	Description
0	UnspecifiedSeverity
1	Error
2	Warning
3	Information
4	Hint

SymbolRole

SymbolRole declares what "role" a symbol has in an occurrence. A role is encoded as a bitmask where each bit represents a different role. For example, to determine if the Import role is set test whether the second bit of the enum value is defined. In psuedo-code, this can be implemented with the logic: const isImportRole = (role.value & SymbolRole.Import.value) > 0.

Number	Name	Description
0	UnspecifiedSymbolRole
1	Definition	Is the symbol defined here? If not, then this is a symbol reference.
2	Import	Is the symbol imported here?
4	WriteAccess	Is the symbol written here?
8	ReadAccess	Is the symbol read here?
16	Generated	Is the symbol in generated code?
32	Test	Is the symbol in test code?

SyntaxKind

Number	Name	Description
0	UnspecifiedSyntaxKind
1	Comment	Comment, including comment markers and text
2	PunctuationDelimiter	`;` `.` `,`
3	PunctuationBracket	(), {}, [] when used syntactically
4	IdentifierKeyword	`if`, `else`, `return`, `class`, etc.
5	IdentifierOperator	`+`, `*`, etc.
6	Identifier	non-specific catch-all for any identifier not better described elsewhere
7	IdentifierBuiltin	Identifiers builtin to the language: `min`, `print` in Python.
8	IdentifierNull	Identifiers representing `null`-like values: `None` in Python, `nil` in Go.
9	IdentifierConstant	`xyz` in `const xyz = "hello"`
10	IdentifierMutableGlobal	`var X = "hello"` in Go
11	IdentifierParameter	both parameter definition and references
12	IdentifierLocal	identifiers for variable definitions and references within a local scope
13	IdentifierShadowed	Used when identifier shadowes some other identifier within the scope
14	IdentifierModule	`package main`
15	IdentifierFunction	Function call/reference
16	IdentifierFunctionDefinition	Function definition only
17	IdentifierMacro	Macro call/reference
18	IdentifierMacroDefinition	Macro definition only
19	IdentifierType	non-builtin types, including namespaces
20	IdentifierBuiltinType	builtin types only, such as `str` for Python or `int` in Go
21	IdentifierAttribute	Python decorators, c-like attribute
22	RegexEscape	`\b`
23	RegexRepeated	`*`, `+`
24	RegexWildcard	`.`
25	RegexDelimiter	`(`, `)`, `[`, `]`
26	RegexJoin	`
27	StringLiteral	Literal strings: "Hello, world!"
28	StringLiteralEscape	non-regex escapes: "\t", "\n"
29	StringLiteralSpecial	datetimes within strings, special words within a string, `{}` in format strings
30	StringLiteralKey	"key" in { "key": "value" }, useful for example in JSON
31	CharacterLiteral	'c' or similar, in languages that differentiate strings and characters
32	NumericLiteral	Literal numbers, both floats and integers
33	BooleanLiteral	`true`, `false`
34	Tag	Used for XML-like tags
35	TagAttribute	Attribute name in XML-like tags
36	TagDelimiter	Delimiters for XML-like tags

TextEncoding

Number	Name	Description
0	UnspecifiedTextEncoding
1	UTF8
2	UTF16