ISL

ISL is a low-code, interpreted scripting language designed primarily for JSON-to-JSON transformations, utilizing a WYSIWYG (What You See Is What You Get) approach to make scripting visual and intuitive.

Operating within a JVM-based runtime container, ISL provides a ready-to-deploy execution environment that allows both developers and non-developers to easily write, test, and integrate their custom code into virtually any service.

⏩ Get started now with this Java or Kotlin Hello World

⏩ Checkout the Overview for examples and the basics of the ISL

Command Line Interface — run isl transform, isl validate, isl test, and isl info with JSON/YAML I/O and parameters.

VS Code & Cursor extension — syntax highlighting, IntelliSense, validation, formatting, tests, debugging; see the site for features and screenshots.

✅ ISL has a permissive

Overview

Originally ISL was designed as a JSON-to-JSON transformation library as an alternative to JOLT and other Java based JSON-to-JSON transformations but since then ISL has evolved into a fully fledged scripting languange while still providing a simple powerful JSON-to-JSON transformation capabilities.

The ISL supports an intuitive simplified syntax with features that make data transformations easy with minimal lines of code. In addition, the language supports easy extensibility allowing it to be used as a multi-purpose service extensibility language.

The ISL can be embedded in any JVM based project to provide runtime based extensibility through a fast and lightweight runtime.

If it looks like a JSON it's a valid ISL :)

Checkout the Overview for examples and the basics of the ISL.

Major Features

• JSON Compatible Object Building item: { field: true, "my-property": 12 }.
• Comprehensive Conditions, If/Else & Switch statements including RegEx Switch Case
• Script Imports.
• Math Expressions $total: {{ $amount * $quantity * 1.2 }}.
• Functional Expressions for:
  • Filters: $positive: [ -1, 0, 1 ] | filter( $ > 0 ).
  • Reduce $total: [ 1, 2, 3, 4 ] | reduce( {{ $acc + $it }} ).
  • Map item: [ 1, 2, 3, 4 ] | map( { id : $ } ).
• Easily Extensible with
  • functions: @.Service.Function( ... ).
  • modifiers: | calculate_tax( ... ).
  • wildcard modifiers: | encode.base64( ... ).
  • block statement extensions similar to pagination support @.Pagination.Page() { ... block ... }.
  • annotations that work as interceptors @cache() fun getCurrentUser(){ ... }
• Pagination Strategies for Page and Cursor.
• Utilities for dealing with Time & Dates, Signatures & Hashing.
• Support for parsing XML and outputting XML, parsing CSV.
• Support for advanced String Interpolation Hi there $name. Today is ${ @.Date.Now() | to.string("yyyy MM dd") }. .
• Support for find, match and replace using Regular Expressions.

Documentation

See the ISL Documentation for complete reference.

Extensibility Points

As a generic runtime, the runtime is designed to be heavily extensible while maintaining the same simple grammar. Modules, Functions, ISL Modifiers, Custom Functions and Custom Modifiers are a few of the available existing extension points:

Custom Functions

Most common extensibility is to provide new services/functions to be callable from inside the script.

Note: At the moment the expectation is that all registered services as async coroutines using the suspend keyword.

Registration (Kotlin):

companion object{
  fun myExtension(context: FunctionExecuteContext): Any?{
    // do stuff
    val value = context.firstParamer;
    ...
    return "result";
  }
}

// register custom extension function.
// Name has to be in format `Service.Name` and will be callable from code as `@.Service.Name( ... )`
context.registerExtensionMethod("MyService.MyMethod", MyClass::myExtension);

// You can register closure callbacks so you can use any existing state you have
context.registerExtensionMethod("MyService.MyMethod", {
  // it: params of Array<Any?> all the parameters that were passed
  myLocalService.DoStuff ( ... )
});

You can now call those functions from the script:

value: @.MyService.MyMethod( parameters );

Custom Modifiers

In some situations custom modifiers are more appropriate as they make code more succinct and fluent. Register an extension method with prefix Modifier. This will added it to the list of modifiers.

// register custom extension modifier by using the prefix "Modifier."
context.registerExtensionMethod("Modifier.taxAmount", MyClass::calculateTaxAmount);

// Or you can register just the lambda
context.registerExtensionMethod("Modifier.taxAmount", {
  // it: params of Array<Any?> all the parameters that were passed
  return calculatedAmount;
});

You now have access to the modifier using the | modifier format:

value: $price | taxAmount;

Note: You can override system modifiers if you really want by overriding by name e.g. registering a modifier with Modifier.Trim will override the default |trim modifier.

Note: Parameters to modifiers are supported. The first parameter you receive in the list of parameters is always the left-hand-side of the modifier, then all the other passed in parameters.

Command line

ISL CLI (isl-cmd) is the standalone command-line runner for the same language and runtime used inside JVM services. Typical workflows:

Command	Purpose
isl transform	Run a script (default entry run); optional -i / -o, -v variables file, -p key=value parameters, -f output format
isl validate	Check compile-time syntax and imports
isl test	Discover and run .isl tests and *.tests.yaml suites
isl info	Print ISL and JVM environment details

From a clone of this repo, use isl.sh (Linux/macOS) or isl.bat (Windows) in the repository root to build or invoke the shadow JAR. For Gradle tasks, fat JAR output path, stdin pipelines, and CI snippets, read the full CLI documentation and isl-cmd/README.md.

VS Code and Cursor

The ISL Language Support extension (sources under plugin/) provides editor integration: completion, hovers, diagnostics, format-on-save, CodeLens run/test/debug, Test Explorer for ISL and YAML suites, and an embedded CLI plus debug adapter. Install from the marketplace or a .vsix, configure isl.execution.* if needed, and open any .isl file.

Extension guide on the docs site — features, settings table, screenshots, and contributor notes for adding more figures.

How to use the ISL in your own project:

Embedding the ISL in your own Java project to add scripting features is straight forward: Java Hello World

ISL vs JOLT

In most common scenarios on a 1:1 comparison ISL is about 46% faster than JOLT.

Read the Detailed benchmark of ISL vs JOLT vs MVEL.

Feature	ISL	JOLT
Custom Functions	✅ Reusable helper functions	❌ No function support
String Manipulation	✅ trim, upperCase, lowerCase, ...	❌ Limited
Math Operations	✅ precision, Math.sum, expressions, ...	❌ No math support
Conditionals	✅ if/else, when/case, if-expressions logic	⚠️ Complex syntax
Array Operations	✅ map, filter, unique, sort, ...	⚠️ Limited
Type Conversions	✅ to.string, to.decimal, to.number, to.boolean, ...	❌ Manual
Content Type Conversions	✅ json, csv, xsl, base64, ...	❌ Manual
Crypto Support	✅ hmac, sha, rsa, ...	❌ Manual
Date Parsing	✅ Full date/time support with formatting	❌ No date support
String Templates	✅ Native interpolation	❌ Workarounds needed
Variables	✅ Named variables for clarity	❌ No variables
Object Spread	✅ Spread syntax for objects	❌ Not available

And many more features.

Release Strategy

This repo uses semantic versioning for releases:

• Impact: Major > x.0.0
• Impact: Minor > 0.x.0
• Impact: Patch > 0.0.1

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

Eager to contribute to this service? Check out our Contribution Guidelines!

Thank you very much to our contributors: @corneliutusnea, @arikgdev, @francoisbeaussier, Paulo Miguel Magalhaes, @wilsonchendevelopment, @AaronTheSoftWearEngineer, @andrewPapad and many many others.