YAML Language Support by Red Hat

Delivers full-featured YAML language capabilities for Visual Studio Code through the yaml-language-server, featuring integrated Kubernetes syntax assistance.

Capabilities

1. YAML validation:
   • Verifies if the complete file contains valid yaml
   • Identifies errors including:
     • Node cannot be located
     • Node contains an invalid key node type
     • Node contains an invalid type
     • Node is not a valid child node
2. Document Outlining (Ctrl + Shift + O):
   • Generates the document outline containing all completed nodes within the file
3. Auto completion (Ctrl + Space):
   • Completes automatically for all commands
   • Scalar nodes auto-complete to schema defaults when available
4. Hover support:
   • Moving the cursor over a node displays its description when supplied by the schema
5. Formatter:
   • Enables formatting of the active file
   • On-the-fly formatting automatically indents array elements

Auto completion and hover support depend on the schema. Refer to Language Server Settings to configure a schema

YAML version support

From version 1.0.0 onwards, the extension employs eemeli/yaml as its new YAML parser, which rigorously enforces the designated YAML specification version. The default YAML specification version is 1.2, which can be modified using the yaml.yamlVersion setting.

Extension Settings

The extension supports the following configuration options:

• yaml.yamlVersion: Configure the default YAML specification version (1.2 or 1.1)
• yaml.format.enable: Toggle the default YAML formatter on or off (restart required)
• yaml.format.singleQuote: Prefer single quotes over double quotes
• yaml.format.bracketSpacing: Insert spaces between brackets in objects
• yaml.format.proseWrap: Always: wrap text when it exceeds print width, Never: never wrap text, Preserve: maintain text wrapping as-is
• yaml.format.printWidth: Define the line length threshold for printer wrapping
• yaml.format.trailingComma: Determine whether trailing commas should be included in JSON-like YAML segments
• yaml.validate: Toggle validation functionality
• yaml.hover: Toggle hover tooltips
• yaml.completion: Toggle autocompletion
• yaml.schemas: Assists in linking schemas to files using glob patterns
• yaml.schemaStore.enable: When enabled, the YAML language server retrieves all available schemas from JSON Schema Store
• yaml.schemaStore.url: URL of a schema store catalog utilized when fetching schemas.
• yaml.customTags: Collection of custom tags that the parser validates. There are two usage methods. Either an array item is a custom tag like "!Ref" which automatically maps !Ref to a scalar, or you can specify the object type that !Ref should represent, e.g. "!Ref sequence". The object type can be scalar (for strings and booleans), sequence (for arrays), or mapping (for objects).
• yaml.maxItemsComputed: The upper limit for outline symbols and folding regions calculated (restricted for performance optimization).
• yaml.disableDefaultProperties: Prevent adding optional properties with default values into completion text (default is false).
• yaml.suggest.parentSkeletonSelectedFirst: When true, users must select a parent skeleton first before autocompletion suggests remaining properties. When the YAML object is non-empty, autocompletion bypasses this setting and returns all properties and skeletons.

• [yaml]: VSCode-YAML applies default configuration to all YAML files. Specifically, it converts tabs to spaces to maintain valid YAML, configures tab size, enables live typing autocompletion and formatting, and also enables code lens. These settings can be adjusted via corresponding options within the [yaml] section in settings:
  • editor.tabSize
  • editor.formatOnType
  • editor.codeLens

• http.proxy: The URL of the proxy server utilized when downloading a schema. If unset or undefined, no proxy server will be used.

• http.proxyStrictSSL: When true, the proxy server certificate must be validated against the provided CA list. Default is false.
• yaml.style.flowMapping : Prohibits flow style mappings when set to forbid
• yaml.style.flowSequence : Prohibits flow style sequences when set to forbid
• yaml.keyOrdering : Enforces alphabetical key ordering in mappings when set to true. Default is false
• yaml.extension.recommendations : Enable extension recommendations for YAML files. Default is true

Adding custom tags

To utilize custom tags in your YAML file, you must first define the custom tags in your code editor settings. For instance, you can configure the following custom tags:

"yaml.customTags": [
    "!Scalar-example scalar",
    "!Seq-example sequence",
    "!Mapping-example mapping"
]

The !Scalar-example maps to a scalar custom tag, the !Seq-example maps to a sequence custom tag, the !Mapping-example maps to a mapping custom tag.

You can then utilize the newly defined custom tags within the YAML file:

some_key: !Scalar-example some_value
some_sequence: !Seq-example
  - some_seq_key_1: some_seq_value_1
  - some_seq_key_2: some_seq_value_2
some_mapping: !Mapping-example
  some_mapping_key_1: some_mapping_value_1
  some_mapping_key_2: some_mapping_value_2

Associating schemas

YAML Language support leverages JSON Schemas to comprehend the structure of a YAML file, encompassing value sets, defaults, and descriptions. Schema support is bundled with JSON Schema Draft 7.

We support schemas delivered via JSON Schema Store. Additionally, schemas can be defined within a workspace.

Linking a YAML file to a schema can be accomplished either within the YAML file itself using a modeline or in User or Workspace settings under the yaml.schemas property.

Associating a schema in the YAML file

You can specify a yaml schema using a modeline. The schema url can be a relative path. When a relative path is specified, it is resolved from the yaml file path, not from the workspace root path

# yaml-language-server: $schema=<urlToTheSchema>

Associating a schema to a glob pattern via yaml.schemas:

yaml.schemas assigns a schema to a file. In other words, the schema (positioned on the left) is assigned to the glob pattern on the right. Your schema can be local or remote. Your schema must be a relative path rather than an absolute path. The entry point for yaml.schemas is a location in user and workspace settings

When linking a schema it should adhere to the format below

"yaml.schemas": {
    "url": "globPattern",
    "Kubernetes": "globPattern"
}

for example.

yaml.schemas: {
    "https://json.schemastore.org/composer": "/*"
}

for example.

yaml.schemas: {
    "kubernetes": "/myYamlFile.yaml"
}

for example.

yaml.schemas: {
    "https://json.schemastore.org/composer": "/*",
    "kubernetes": "/myYamlFile.yaml"
}

On Windows with absolute path:

yaml.schemas: {
    "C:\\Users\\user\\Documents\\custom_schema.json": "someFilePattern.yaml",
    "file:///C:/Users/user/Documents/custom_schema.json": "someFilePattern.yaml",
}

On Mac/Linux with absolute path:

yaml.schemas: {
    "/home/user/custom_schema.json": "someFilePattern.yaml",
}

Since version 0.11.0 YAML Schemas can be utilized for validation:

 "/home/user/custom_schema.yaml": "someFilePattern.yaml"

A schema can be linked to multiple glob patterns using a json array, for example.

yaml.schemas: {
    "kubernetes": ["filePattern1.yaml", "filePattern2.yaml"]
}

for example.

"yaml.schemas": {
    "http://json.schemastore.org/composer": ["/*"],
    "file:///home/johnd/some-schema.json": ["some.yaml"],
    "../relative/path/schema.json": ["/config*.yaml"],
    "/Users/johnd/some-schema.json": ["some.yaml"],
}

for example.

"yaml.schemas": {
    "kubernetes": ["/myYamlFile.yaml"]
}

for example.

"yaml.schemas": {
    "http://json.schemastore.org/composer": ["/*"],
    "kubernetes": ["/myYamlFile.yaml"]
}

Multi root schema association:

You can also utilize relative paths when working with multi-root workspaces.

Imagine you have a multi-root workspace structured like:

My_first_project:
   test.yaml
   my_schema.json
My_second_project:
   test2.yaml
   my_schema2.json

You must then link schemas relative to the root of the multi root workspace project.

yaml.schemas: {
    "My_first_project/my_schema.json": "test.yaml",
    "My_second_project/my_schema2.json": "test2.yaml"
}

yaml.schemas enables you to specify JSON schemas that you want to validate your YAML against. Kubernetes is a reserved keyword field. It does not require a URL, as the language server supplies it. You need the kubernetes keyword and a glob pattern.

Mapping a schema in an extension

• Supports the yamlValidation point, which enables you to contribute a schema for a specific type of YAML file (Similar to jsonValidation) for example.

{
  "contributes": {
    "yamlValidation": [
      {
        "fileMatch": "yourfile.yml",
        "url": "./schema.json"
      }
    ]
  }
}

Feedback & Questions

If you encounter an issue please report it and we will address it promptly.

• Report an issue in GitHub Issues.
• Start a Discussion on GitHub.

License

MIT, See LICENSE for additional details.

Data and Telemetry

The vscode-yaml extension gathers anonymous usage data and transmits it to Red Hat servers to assist in improving our products and services. Review our privacy statement for more information. This extension honors the redhat.telemetry.enabled setting, which you can learn more about at https://github.com/redhat-developer/vscode-redhat-telemetry#how-to-disable-telemetry-reporting

How to contribute

The guidelines are available in the contribution guide.