Editor Support

We provide a JSON schema file to integrate with your editor. This will help validate your yaml files and provide intellisense for the spec.

VSCode

For VSCode you'll need to use a YAML plugin that supports JSON schemas, such as YAML Support by Red Hat. Follow the plugins instructions to add the schema to your workspace. Here are some examples of vscode workspace configs settings.json enabling the JSON schema:

Schema is locally available and enable it for yml files under a single directory.

{
    "yaml.schemas": {
       "docs/spec.schema.json": "test/fixtures/*.yml"
    }
}

Schema is locally available and enable it for yml files under multiple directories.

{
    "yaml.schemas": {
       "docs/spec.schema.json": [
            "test/fixtures/*.yml",
            "docs/**/*.yml"
        ]
    }
}

Directly reference schema from GitHub repository URL.

{
    "yaml.schemas": {
        "https://raw.githubusercontent.com/Azure/dalec/<version>/docs/spec.schema.json" : "test/fixtures/*.yml"
    }
}

You may find with this extension that null-able yaml objects will show as errors in the editor unless you specify the empty value. An example:

args:
    FOO:

In this example the json schema says that FOO should be a string but we've left it null which is perfectly valid yaml and will unmarshal to an empty string. The yaml plugin will complain that it is an incorrect type. To fix this you can specify the empty string as the value:

args:
    FOO: ""

Vim

For vim there are 2 required vim plugins to add to your vimrc, though you may find your own equivalents. The example below uses vim-plug to manage the plugins. The first two listed below are required, the second two are recommended.

Plug 'prabirshrestha/vim-lsp'
Plug 'mattn/vim-lsp-settings'
Plug 'prabirshrestha/asyncomplete.vim'
Plug 'prabirshrestha/asyncomplete-lsp.vim'

The mattn/vim-lsp-settings is a generic plugin for installing and managing LSP servers on your system. See the github repo for more details as well as links to the other mentioned plugins.

After the plugins are installed, while editing a yaml file you need to run the following vim command to install the correct LSP, this only needs to be done one time:

:LspInstallServer

Finally, in your project dir you can add a file .vim-lsp-settings/settings.json where we'll put the yaml LSP config for the particular project. Here is an example similar to the vscode example above:

{
	"yaml-language-server": {
		"schemas": [
			{
				"fileMatch": ["test/fixtures/*.yml"],
				"url": "https://raw.githubusercontent.com/Azure/dalec/<version>/docs/spec.schema.json"
			}
		],
		"completion": true,
		"validate": true
	}
}

In the "fileMatch" section you can add the file patterns to associate the schema with. In this case, <version> should be replaced with the specific Dalec frontend version (i.e., v0.6.1) that is referenced in any files which match the fileMatch pattern. To pick up whatever the latest schema is, released or not, use main.

note

One or more of the above plugins depend on node.js and is known to work with node >= 16.20 but may work with earlier releases.

VSCode​

Vim​

VSCode

Vim