LSIF Typed protocol reference

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 document	Document	Documents that belong to this index.
repeated external_symbols	SymbolInformation	Symbols that are referenced from this index and not defined in this index.

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?

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.

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 as "$SCHEME:$ID where:
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.
package	string	(optional) To enable cross-index navigation, specify which package this symbol is defined in. A package must be encoded as a space-separated string with the value "$manager $name $version" where: - $manager is the name of the package manager, for example npm. - $name is the name of the package, for example react. - $version is the version of the package, for example 1.2.0.
repeated reference_symbols	string	(optional) 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.
repeated implementation_symbols	string	(optional) 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.
repeated type_definition_symbols	string	(optional) Similar to references_symbols but for “Go to type definition”.

Additional notes on symbol:

Identifier of this symbol, which can be referenced from Occurence.symbol. The string must be formatted as "$SCHEME:$ID where:

• SCHEME: the value local for document-local symbols or an indexer-specific identifier for global symbols. Document-local symbols are symbols that cannot be referenced outside the document, for example local variables.
• ID: an opaque identifier that uniquely determines this symbol within the defined scheme. For global symbols, the ID must be stable between different invocations of the indexer against unchanged code. For document-local symbols, any string value that uniquely identifies the symbol within the document it belong to (ideally stable between runs).

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.