From 13d8325aaa02fa80ff0bf8a3c94ea5490830b5d7 Mon Sep 17 00:00:00 2001 From: Martin Aeschlimann Date: Fri, 19 Jul 2019 10:33:50 +0200 Subject: [PATCH] [json] update server readme --- .../json-language-features/server/README.md | 49 +++++++++++++------ 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/extensions/json-language-features/server/README.md b/extensions/json-language-features/server/README.md index 9b02dc24ef6..5ca997d9e12 100644 --- a/extensions/json-language-features/server/README.md +++ b/extensions/json-language-features/server/README.md @@ -21,6 +21,8 @@ The server implements the following capabilities of the language server protocol - [Document Symbols](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol) for quick navigation to properties in the document. - [Document Colors](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentColor) for showing color decorators on values representing colors and [Color Presentation](https://microsoft.github.io/language-server-protocol/specification#textDocument_colorPresentation) for color presentation information to support color pickers. The location of colors is defined by the document's [JSON schema](http://json-schema.org/). All values marked with `"format": "color-hex"` (VSCode specific, non-standard JSON Schema extension) are considered color values. The supported color formats are `#rgb[a]` and `#rrggbb[aa]`. - [Code Formatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_rangeFormatting) supporting ranges and formatting the whole document. +- [Folding Ranges](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange) for all folding ranges in the document. +- Semantic Selection for semantic selection for one or multiple cursor positions. - [Diagnostics (Validation)](https://microsoft.github.io/language-server-protocol/specification#textDocument_publishDiagnostics) are pushed for all open documents - syntax errors - structural validation based on the document's [JSON schema](http://json-schema.org/). @@ -90,10 +92,39 @@ To find the schema for a given JSON document, the server uses the following mech - The settings define a schema association based on the documents URL. Settings can either associate a schema URL to a file or path pattern, and they can directly provide a schema. - Additionally, schema associations can also be provided by a custom 'schemaAssociations' configuration call. -Schemas are identified by URLs. To load the content of a schema, the JSON language server tries to load from that URL or path. The following URL schemas are supported: +Schemas are identified by URLs. To load the content of a schema, the JSON language server either tries to load from that URI or path itself, or delegates to the client. + +The `initializationOptions.handledSchemaProtocols` initialization option defines which URLs are handled by the server. Requests for all other URIs are send to the client. + +`handledSchemaProtocols` is part of the initialization options and can't be changed while the server is running. + +```ts +let clientOptions: LanguageClientOptions = { + initializationOptions: { + handledSchemaProtocols: ['file'] // language server should only try to load file URLs + } + ... +} +``` + +If `handledSchemaProtocols` is not set, the JSON language server will load the following URLs itself: + - `http`, `https`: Loaded using NodeJS's HTTP support. Proxies can be configured through the settings. - `file`: Loaded using NodeJS's `fs` support. -- `vscode`: Loaded by an LSP call to the client. + +#### Schema content request + +Requests for schemas with URLs not handled by the server are forwarded to the client through an LSP request. This request is a JSON language server specific, non-standardized, extension to the LSP. + +Request: +- method: 'vscode/content' +- params: `string` - The schema URL to request. +- response: `string` - The content of the schema with the given URL + +#### Schema content change notification + +When the client is aware that a schema content has changed, it will notify the server through a notification. This notification is a JSON language server specific, non-standardized, extension to the LSP. +The server will, as a response, clear the schema content from the cache and reload the schema content when required again. #### Schema associations notification @@ -111,20 +142,6 @@ interface ISchemaAssociations { - keys: a file names or file path (separated by `/`). `*` can be used as a wildcard. - values: An array of schema URLs -#### Schema content request - -The schema content for schema URLs that start with `vscode://` will be requested from the client through an LSP request. This request is a JSON language server specific, non-standardized, extension to the LSP. - -Request: -- method: 'vscode/content' -- params: `string` - The schema URL to request. The server will only ask for URLs that start with `vscode://` -- response: `string` - The content of the schema with the given URL - -#### Schema content change notification - -When the client is aware that a schema content has changed, it will notify the server through a notification. This notification is a JSON language server specific, non-standardized, extension to the LSP. -The server will, as a response, clear the schema content from the cache and reload the schema content when required again. - Notification: - method: 'json/schemaContent' - params: `string` the URL of the schema that has changed.