LSIF Typed protocol reference


Name Type Description
name string
disambiguator string
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


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 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 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.


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 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.


Name Type Description
manager string
name string
version string


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 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 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).


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.


Number Name Description
0 UnspecifiedDiagnosticTag
1 Unnecessary
2 Deprecated


Number Name Description
0 UnspecifiedProtocolVersion


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


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?


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


Number Name Description
0 UnspecifiedTextEncoding
1 UTF8
2 UTF16