Welcome to the Jolt language extension! This provides syntax coloring, method completion, and variable completion for your Jolt transformers when using the *.jolt.json file extension to make reading and managing your transforms a bit easier. The Jolt language interpreter is written in C# and published to NuGet. Please see the project's GitHub repository for further information and complete documentation.
Disambiguation
This is not part of the much older and unrelated Java-based JSON transformation library, by coincidence also called Jolt.
Features
Syntax Coloring
The Jolt language is embedded inside JSON strings, and editing transforms with the default JSON coloring can make it more difficult to develop and maintain. This language extension provides syntax coloring to make that easier.
Method & Variable Completion
It can be a bit difficult to know at a glance what the available Jolt Library methods are and their signatures without some help, especially when trying to understand which methods are valid in which areas of your transformer. When you type either a method start symbol # or a piped method symbol ->, you will get a list of available methods with their signatures. Selecting one will provide a snippet to help get you going.
The same holds true for variables and understanding which are currently in scope for you to use and which are not. This extension also provides context-sensitive method and variable completions to help speed up your development and maintenance abilities.
Code Snippets
In addition, some of the method and variable completions include more help, such as a #foreach loop along with its template, a #using block with its statements, a #match with its cases, and a variable declaration. Start a new property name with "# or "@ (or type them without the quote) to see them. Choosing one replaces the property name you've started with the whole property, value included, and any commas needed to separate it from its neighbors are added for you.
You may forget what a particular method is for and need a quick refresher on the documented method information. It also slows down your development if you have to continually refer to the README file, so the documented definition for a given method is available when hovering over it.
Variable Navigation
Hovering over a variable shows what kind of variable it is (e.g. a #foreach loop item, a lambda parameter, or a #match pattern capture) and the property name or expression that declares it. Go to Definition (F12) on a variable jumps to its declaration, and on a custom method it opens the methods.json file that defines it.
You can also Rename (F2) a variable or Find All References (Shift+F12) to it, which cover its declaration and every reference to it, while leaving other variables that happen to share its name (such as a lambda parameter shadowing an outer variable) alone. Placing the cursor on a variable highlights its other occurrences in the same way.
Signature Help
While you're writing a method's arguments, its signature is shown with the current parameter highlighted, including any optional parameters that the completion snippet left out. This also works for piped methods (where the pipe supplies the first parameter) and for your custom methods. To bring it back up within a method's arguments, press Ctrl+Space, which also shows completions, or Ctrl+Shift+Space for the signature alone.
Transformers can be formatted with Format Document and Format Selection, which lay out the JSON while leaving your Jolt expressions untouched. The Outline view and breadcrumbs show the structure of your transformer, with properties that call a method (e.g. #foreach(...)) or declare a variable (e.g. @total) marked as such.
Custom Method Completions
Finally, with a little effort you can also have completions and on-hover documentation for your custom methods. In a trusted workspace, this extension will look for a .jolt folder containing a methods.json file, starting with the current folder containing the transformer and walking back up to either the workspace root or upon finding a methods.json file with its root property set to true. All .jolt/methods.json files collected in this way will be merged into the overall available methods to a given transformer, with files closer to the transformer's folder overriding any previously defined methods higher up the folder hierarchy. Given this behavior, you can then structure your instance-based Jolt context types accordingly to maximize your method selection.
IMPORTANT: This feature is unavailable in an untrusted workspace to increase security, although the rest of the extension's functionality is allowed. Make sure you are confident that your methods.json files are benign prior to establishing workspace trust.
As an example of a methods.json file, you could create one that looks like this:
Each method may also include an optional returnType property with the method's C# return type (e.g. "returnType": "OrderSummary"), which is shown alongside its documentation in completions and on hover. Similarly, a parameter whose kind is lambda may include an optional lambdaVariables array naming the one or two variables it binds (e.g. "lambdaVariables": ["acc", "current"] for a Func<> with two inputs), which is shown in the method's signature (e.g. @acc;@current: combiner) and used for the placeholders when completing it. Lambdas without it are shown with a single @x variable.
After creating the file, it would then be accessible to a transformer within that folder or a subfolder, like this:
It's also important to note that any updates to the methods.json file will only be picked up when by this extension when the file is saved. Unsaved definitions will not be loaded. Additionally, transformers opened from outside the workspace will only check their own folder and that file isn't watched for changes, meaning that any changes there will need to reload the VSCode window to be applied. As a last caveat, any custom methods whose name collides with a defined Jolt standard library method will be ignored (as per Jolt's execution rules) and will not be available in your transformer completions or on-hover behavior.
Validation
As you edit a transformer, it is validated by the Jolt library itself (the same validation as JoltTransformer.Validate()), and any problems are shown in the editor and the Problems panel. This includes invalid JSON, expression syntax errors, undeclared variables, methods used where they aren't allowed, the wrong number of arguments to a method, and the use of unsafe methods (as warnings). In a Jolt test file (with a testGroups array), the transformer in each test is validated on its own.
Without a .jolt/methods.json file, calls to methods that aren't in the standard library aren't reported, since they may be custom methods that the extension doesn't know about. The exception is a name that's very close to a standard library method (e.g. #valeuOf), which is reported as a warning since it's most likely a misspelling.
Validation also uses your .jolt/methods.json files in a trusted workspace. Calls to methods that aren't standard library methods or listed in an applicable methods.json file are reported as unknown, and when no methods.json file applies to a transformer, unknown methods aren't reported at all. Similarly, you can list the names of the transformers that your application registers, so that #transformWith() calls using any other transformer name are reported:
{
"transformers": ["address", "person"],
"methods": []
}
Transformer names from all of the applicable methods.json files are combined, and when none of them have a transformers property, #transformWith() calls aren't checked.
Quick Fixes
Some validation problems come with quick fixes (Ctrl+., or the light bulb):
- Unknown methods: change the call to a method with a similar name (e.g.
#valeuOf to #valueOf), or add the method to the closest applicable .jolt/methods.json file (creating one in the transformer's folder if there isn't one). The new entry's parameters are inferred from the call, including lambdas and the variables they bind, and the file opens on it so that you can fill in its description.
- Undeclared variables: change the reference to a variable in scope with a similar name, or declare the variable just before the property that uses it.
Preview
You can see what a transformer produces without leaving the editor. Use the Open Preview to the Side button in a transformer's title bar (or Jolt: Open Preview to the Side) to run it against an input file and show its output beside it. The preview runs again as you edit the transformer or the input file, saved or not, and its first lines describe the run: the input file used, how long it took, and any error (along with the output of the last successful run).
A transformer's input files are kept in a folder named after it, inside a .jolt folder next to it. For orders.jolt.json, they'd be in .jolt/orders/, such as .jolt/orders/multi-item-order.input.json. When a transformer has no input files yet, the preview offers to create one, asking for its name. Otherwise it runs against the input file you last chose for it, or the first one by name. The code lenses at the top of the preview show the current input file: click it to switch to another one (or to open it, when it's the only one), or click New Input File to create another. The Choose Preview Input and Open Preview Input File buttons in the preview's title bar do the same.
An input file holds the source document in its input property. Since your custom methods are part of your application, the preview can't call them, so mocks gives the value that each one returns instead, whatever its arguments:
{
"input": { "order": { "country": "DE", "items": [] } },
"mocks": {
"lookupRegion": { "returns": "EMEA" }
}
}
New input files include a mock to fill in for each custom method that the transformer calls (from your .jolt/methods.json files, in a trusted workspace). Calling a custom method from a methods.json file that has no mock is reported in the preview. A mock for a standard library method is ignored, since Jolt always calls the standard library method, and the preview warns about it.
The preview runs transformers with the language server, so it needs validation to be turned on. If it's off when you open a preview, you'll be asked whether to turn it on. Transformers that take longer than 10 seconds to run are reported as timed out, and Jolt test files (with a testGroups array) can't be previewed.
Language Status
The language status area of the status bar (the { } next to "Jolt") shows whether validation is running, starting, turned off, or has failed (and why), along with the methods.json files that apply to the current transformer, which you can open from there. It also shows the version of Jolt that this extension's completions, hover and validation are based on.
NOTE: This extension currently includes its own copy of the Jolt library, so if your application uses a different version of the Jolt NuGet package, its standard library methods may not match what's offered here. The included version is also shown at the end of each standard library method's hover documentation. If the language server can't be started, the warning offers to show its output, retry, or turn validation off.
The following commands are also available from the Command Palette:
- Jolt: Restart Language Server: stops and restarts validation, e.g. after installing .NET.
- Jolt: Show Language Server Output: shows the language server's log, which is kept across restarts.
Requirements
Validation uses the Jolt language server, which needs .NET 8 or later. If a suitable .NET runtime isn't already installed, the .NET Install Tool extension (installed along with this one) downloads one for this extension's use. Everything else works without .NET, and validation can be turned off with the jolt.validation.enabled setting.
Extension Settings
This extension offers default colorization settings via the editor.tokenColorCustomizations setting. This supports the following themes:
- Dark Mode (via
Dark 2026, Dark Modern, Dark+, or Visual Studio Dark)
- Light Mode (via
Light 2026, Light Modern, Light+, or Visual Studio Light)
Older versions of VS Code name these themes Default Dark Modern, Default Dark+, Default Light Modern, and Default Light+, which are also supported.
It also contributes the following settings:
jolt.completion.includeUnsafeMethods: include unsafe library methods (such as #eval) in completions. Defaults to false.jolt.validation.enabled: validate transformers as you edit them. Defaults to true.jolt.validation.allowUnsafeMethods: don't report the use of unsafe library methods, for when your application enables them. Defaults to false.
- Please visit the Jolt GitHub page for complete documentation on the Jolt language.
